Flutter SDK 4.0移行ガイド

Amplitude Flutter SDK 4.0はデフォルトのイベントトラッキング機能と簡素化されたインターフェースを特徴としており、最新のAmplitude iOS、Android Kotlin、Browser TypeScriptの各SDKをラップしています。

用語

amplitude_flutter:v3: Flutter SDK 3.0 です。
amplitude_flutter:v4: Flutter SDK 4.0 です。

依存関係

pubspec.yamlを開いて依存関係を更新します。

diff

dependencies:
-  amplitude_flutter: ^3
+  amplitude_flutter: ^4

依存関係を更新するには、ターミナルでflutter pub getを実行します。

Podfileを開いて更新します。

diff

- platform :ios, '10.0'
+ platform :ios, '13.0'

Flutterプロジェクトのiosディレクトリでpod installを実行し、CocoaPodsの依存関係を更新します。

Flutter Webの場合、web/index.htmlにある「Amplitude-JavaScript」スニペットを以下の「Browser SDK 2」スニペットに置き換えます。

html

<script type="text/javascript">
  !(function () {
    "use strict";
    !(function (e, t) {
      var r = e.amplitude || { _q: [], _iq: {} };
      if (r.invoked)
        e.console &&
          console.error &&
          console.error("Amplitude snippet has been loaded.");
      else {
        var n = function (e, t) {
            e.prototype[t] = function () {
              return (
                this._q.push({
                  name: t,
                  args: Array.prototype.slice.call(arguments, 0),
                }),
                this
              );
            };
          },
          s = function (e, t, r) {
            return function (n) {
              e._q.push({
                name: t,
                args: Array.prototype.slice.call(r, 0),
                resolve: n,
              });
            };
          },
          o = function (e, t, r) {
            e._q.push({ name: t, args: Array.prototype.slice.call(r, 0) });
          },
          i = function (e, t, r) {
            e[t] = function () {
              if (r)
                return {
                  promise: new Promise(
                    s(e, t, Array.prototype.slice.call(arguments)),
                  ),
                };
              o(e, t, Array.prototype.slice.call(arguments));
            };
          },
          a = function (e) {
            for (var t = 0; t < g.length; t++) i(e, g[t], !1);
            for (var r = 0; r < m.length; r++) i(e, m[r], !0);
          };
        r.invoked = !0;
        var c = t.createElement("script");
        ((c.type = "text/javascript"),
          (c.integrity =
            "sha384-R0H1kXlk6r2aEQMtwVcPolpk0NAuIqM/8NlxAv24Gr3/PBJPl+9elu0bc3o/FDjR"),
          (c.crossOrigin = "anonymous"),
          (c.async = !0),
          (c.src =
            "https://cdn.amplitude.com/libs/analytics-browser-2.11.10-min.js.gz"),
          (c.onload = function () {
            e.amplitude.runQueuedFunctions ||
              console.log("[Amplitude] Error: could not load SDK");
          }));
        var l = t.getElementsByTagName("script")[0];
        l.parentNode.insertBefore(c, l);
        for (
          var u = function () {
              return ((this._q = []), this);
            },
            p = [
              "add",
              "append",
              "clearAll",
              "prepend",
              "set",
              "setOnce",
              "unset",
              "preInsert",
              "postInsert",
              "remove",
              "getUserProperties",
            ],
            d = 0;
          d < p.length;
          d++
        )
          n(u, p[d]);
        r.Identify = u;
        for (
          var f = function () {
              return ((this._q = []), this);
            },
            v = [
              "getEventProperties",
              "setProductId",
              "setQuantity",
              "setPrice",
              "setRevenue",
              "setRevenueType",
              "setEventProperties",
            ],
            y = 0;
          y < v.length;
          y++
        )
          n(f, v[y]);
        r.Revenue = f;
        var g = [
            "getDeviceId",
            "setDeviceId",
            "getSessionId",
            "setSessionId",
            "getUserId",
            "setUserId",
            "setOptOut",
            "setTransport",
            "reset",
            "extendSession",
          ],
          m = [
            "init",
            "add",
            "remove",
            "track",
            "logEvent",
            "identify",
            "groupIdentify",
            "setGroup",
            "revenue",
            "flush",
          ];
        (a(r),
          (r.createInstance = function (e) {
            return ((r._iq[e] = { _q: [] }), a(r._iq[e]), r._iq[e]);
          }),
          (e.amplitude = r));
      }
    })(window, document);
  })();
</script>

インスツルメンテーション

Flutter SDK 4.0はイベントをインストルメンテーションするためのAPIを提供します。Flutter SDK 4.0 に移行するには、いくつかの呼び出しを更新する必要があります。次のセクションでは、どの呼び出しが変更されたかについて詳しく説明します。

初期化

Flutter SDK 4.0では、他のレガシーコールとともにinstance()が削除されました。Flutter SDK 4.0では、Configurationオブジェクトを使用して構成を設定します。詳細については、設定を参照してください。

dart

import 'package:amplitude_flutter/amplitude.dart';
import 'package:amplitude_flutter/identify.dart';
import 'package:amplitude_flutter/amplitude.dart';
import 'package:amplitude_flutter/configuration.dart';
// Create the instance and initialize SDK
final Amplitude amplitude = Amplitude.getInstance(instanceName: "project");
amplitude.setServerUrl("https://your.endpoint.com")
amplitude.setServerZone("US")
amplitude.trackingSessionEvents(true)
amplitude.init(widget.apiKey);
final Amplitude amplitude = Amplitude(Configuration(
    apiKey: "YOUR-API-KEY",
    serverUrl: "https://your.endpoint.com",
    serverZone: ServerZone.eu,
    autocapture: AutocaptureOptions(
       sessions: true
    )
  ));
await amplitude.isBuilt;

設定

Flutter SDK 4.0には以下の設定変更が含まれています。

構成はランタイム間でより一貫性が保たれます。
Flutter SDK 4.0 は特定の設定をサポートしなくなりました。
Flutter SDK 4.0 は、SDK バージョン 3.0 のセッターではなく、インスタンス変数を使用して設定を行います。
設定はAmplitudeに渡した後は変更不可能になります。
defaultTrackingおよびDefaultTrackingOptionsは非推奨です。代わりにAutocaptureOptionsではautocaptureを使用してください。Flutter SDK 4 リファレンスの「自動キャプチャ」を参照してください。

Flutter SDK 3.0	Flutter SDK 4.0
`enableCoppaControl()`または`disableCoppaControl()`	`config.enableCoppaControl`
`setMinTimeBetweenSessionsMillis()`	`config.minTimeBetweenSessionsMillis`
`setEventUploadThreshol(d)`	`config.flushQueueSize`
`setEventUploadPeriodMillis()`	`config.flushIntervalMillis`
`setServerZone()`	`config.serverZone`
`setServerUrl()`	`config.serverUrl`
`setUseDynamicConfig()`	サポートされていません
`setOptOut()`	`config.optOut`
`setOffline()`	サポートされていません
`trackingSessionEvents()`	`autocapture: AutocaptureOptions(sessions: true)`
`useAppSetIdForDeviceId()`	`config.useAppSetIdForDeviceId`

イベントを追跡

Flutter SDK 4.0では、統一されたtrackAPIを使用して、以下のlogEventAPIバリエーションを置き換えます。

withEventProperties。
withApiProperties。
withUserProperties。
withGroup。
withGroupProperties。

logEvent()

logEvent()APIはtrack()にマップされます。

dart

amplitude.logEvent('BUTTON_CLICKED');
amplitude.track(event: BaseEvent(eventType:'BUTTON_CLICKED'));

イベントプロパティを持つ logEvent()

dart

amplitude.logEvent('BUTTON_CLICKED', {"Hover Time": "100ms"});
amplitude.track(event: BaseEvent(eventType:'BUTTON_CLICKED', eventProperties: {"Hover Time": "100ms"}));

outOfSession を使用した logEvent()

logEvent()はオプションのブール値引数outOfSessionを受け取ります。新しいtrack()APIはoutOfSessionをサポートしていません。イベントをセッション外として追跡するには、event.sessionId = -1を設定します。

dart

amplitude.logEvent("BUTTON_CLICKED", outOfSession: true);
amplitude.track(event: BaseEvent(eventType:'BUTTON_CLICKED', sessionId: -1));

uploadEvents()

uploadEvents()APIはflush()にマップされます。

dart

amplitude.uploadEvents();
amplitude.flush();

ユーザープロパティを設定する

ユーザープロパティを設定するためのAPIは同じですが、Flutter SDK 4.0ではinstance()が削除されています。次のコードスニペットは、ユーザープロパティ API を移行する方法を示しています。

setUserId()

setUserId()はstartNewSessionを受け取らなくなり、現在はデフォルトの最小長は5となっています。このデフォルト値を上書きするには、初期化時にminIdLength設定オプションを設定してください。

識別子の最小長

メンテナンスSDKは、deviceIdおよびuserIdに長さ制限を課さない古いSDKエンドポイント（api2.amplitude.com）を使用します。最新のSDKはAmplitudeのHTTP V2 API（api2.amplitude.com/2/httpapi）を使用しており、デフォルトでは少なくとも5文字の識別子が必要です。最新のSDKに移行する際には、5文字未満の識別子を許可している場合は、config.minIdLengthをより小さい値に設定してください。

setDeviceId()

setDeviceId()の現在のデフォルト最小長は5です。このデフォルト値を上書きするには、初期化時にminIdLength設定オプションを設定してください。

識別子の最小長

regenerateDeviceId()

Flutter SDK 4.0はregenerateDeviceId()をサポートしていません。

clearUserProperties()

Flutter SDK 4.0ではclearUserPropertiesAPIが削除されています。ユーザープロパティを削除するには、統合されたidentifyAPIを使用します。

dart

amplitude.clearUserProperties();
final Identify identify = Identify()
  ..clearAll();
amplitude.identify(identify);

setUserProperties()

Flutter SDK 4.0ではsetUserPropertiesAPIが削除されています。ユーザープロパティを追加するには、統合されたidentifyAPIを使用します。

dart

- Map<String, dynamic> userProps = {
-   'gender': 'female',
-   'age': '20'
- };
- amplitude.setUserProperties(userProperties);
+ final Identify identify = Identify()
+                          ..set('gender','female')
+                          ..set('age',20);
+ amplitude.identify(identify);

identify()

instance()を呼び出さずにamplitudeでidentify呼び出しを実行できるようになりました。

dart

final Identify identify = Identify()
                          ..set('gender','female')
                          ..set('age',20);
Amplitude.getInstance().identify(identify);
amplitude.identify(identify);

グループプロパティを設定する

`setGroup()`

instance()を呼び出さずにamplitudeでidentify呼び出しを実行できるようになりました。

dart

// set group with a single group name
Amplitude.getInstance().setGroup("orgId", "15");
amplitude.setGroup("orgId", "15");
// set group with multiple group names
Amplitude.getInstance().setGroup("sport", ["tennis", "soccer"]);
amplitude.setGroup("sport", ["tennis", "soccer"]);

groupIdentify()

instance()を呼び出さずにamplitudeでidentify呼び出しを実行できるようになりました。

dart

final Identify identify = Identify()
                          ..set("gender", "female")
                          ..set("age", 20);
Amplitude.getInstance().groupIdentify("groupType", "groupValue", identify);
amplitude.groupIdentify("groupType", "groupValue", identify);

収益の追跡

revenue()APIは、logRevenue()およびlogRevenueAmount()の代わりとなるAPIです。

dart

String productId = "product001";
int quantity = 2;
double price = 20;
double amount = 35;
amplitude.logRevenue(productId, quantity, price);
amplitude.logRevenueAmount(amount);
final Revenue revenue = Revenue()
  ..price = 3.99
  ..quantity = 3
  ..productId = "com.company.productId";
amplitude.revenue(revenue);

Was this helpful?