このページでは

Flutter SDK 4

これは、Amplitude Analytics Flutter SDKの公式ドキュメントです。Flutter SDK を使用すると、Flutter アプリケーションから Amplitude にイベントを送信できます。

互換性

Amplitude Flutter v4では、最新のGradleをサポートするため、Kotlinのバージョンがv1.9.22にアップグレードされています。

以下のマトリックスには、Amplitude Flutter SDKのバージョンごとの最低サポート要件が記載されています。

SDK をインストールする

次のコマンドを実行して amplitude_flutterの最新バージョンを取得し、ITをpubspec.yaml に追加してから、依存関係を取得します。

bash
flutter pub add amplitude_flutter

iOSのインストール

Podfileに platform :ios, '13.0' を追加してください。 Flutterプロジェクトのiosディレクトリでpod install実行して、CocoaPodsの依存関係を更新します。

Bitcodeを有効にするには、Flutterのドキュメントに従ってください。

macOS のインストール

Podfileにplatform :osx, '10.15'を追加してください。 Flutterプロジェクトのmacosディレクトリでpod installを実行して、CocoaPodsの依存関係を更新します。 リクエストを送信できるように、アプリにcom.apple.security.network.client権限が設定されていることを確認してください。 macos/Runner/Release.entitlementsおよびmacos/Runner/DebugProfile.entitlementsファイルを手動で編集して、以下の項目を含めます:

xml
	<key>com.apple.security.network.client</key>
	<true/>

詳細については、Flutterのドキュメントを参照してください。

Webインストール(オプション)

Flutter SDKはDartのJavaScriptの相互運用性を使用して、Flutter Web向けブラウザSDK 2を有効にします。そのためには、グローバルなJavaScriptスコープ内でSDKを使用できるようにする必要があります。以下のブラウザSDK 2スニペットをFlutterプロジェクトのweb/index.htmlに追加してください:

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>

SDKの初期化

イベントの送信

この SDK は HTTP V2 API を使用しており、イベントについても同じ制約に従います。 SDKに記録されるすべてのイベントに、少なくとも1つdeviceId(デフォルトで含まれています)またはuserIdが含まれていることを確認し、これらのフィールドごとに、HTTP APIの制約に従ってください。

計装に関する問題を防ぐために、デバイスIDとユーザーIDは、5文字以上の文字列である必要があります。 イベントに短すぎるデバイスIDまたはユーザーIDが含まれている場合、AmplitudeはそのイベントからID値を削除します。イベントにdeviceIdまたはuserIdの値がない場合、Amplitudeはアップロードを400ステータスで拒否することがあります。 minIdLength設定オプションを設定することで、デフォルトの最小長である 5 文字を上書きできます。

アプリケーションをインストルメントする前に、AmplitudeプロジェクトのAPIキーを使用してSDKを初期化してください。

dart
import 'package:amplitude_flutter/amplitude.dart';
import 'package:amplitude_flutter/configuration.dart';
import 'package:amplitude_flutter/events/base_event.dart';
class YourClass {
  Future<void> exampleForAmplitude() async {
    // Create and initialize the instance
    final Amplitude amplitude = Amplitude(Configuration(
        apiKey: 'YOUR-API-KEY',
    ));
    // Wait until the SDK is initialized
    await amplitude.isBuilt;
    // Track an event
    amplitude.track(BaseEvent(
        eventType: 'BUTTON_CLICKED',
        eventProperties: {'Hover Time': '100ms'},
    ));
    // Send events to the server
    amplitude.flush()
  }
}

SDK を設定する

Android および iOS 用の設定

ウェブとAndroid用の設定

Android用の設定

Web 用の設定

  • appVersion
    • 説明String。 追跡されるイベントのアプリバージョンを設定します。 これは、アプリケーションのバージョンである可能性があります。 たとえば、「1.0.0」などです。
    • デフォルト値null
  • cookieOptions.domain
    • 説明String。 作成されるクッキーのドメインプロパティを設定します。
    • デフォルト値null
  • cookieOptions.expiration
    • 説明int。 作成されたクッキーの有効期限を日数で設定します。
    • デフォルト値: 365日
  • cookieOptions.sameSite
    • 説明String。 作成されるクッキーのSameSiteプロパティを設定します。
    • デフォルト値null
  • cookieOptions.secure
    • 説明bool。 作成されるクッキーのSecureプロパティを設定します。
    • デフォルト値null
  • cookieOptions.upgrade
    • 説明boolメンテナンスブラウザ SDK によって作成された Cookie からのアップグレードを設定します。 trueの場合、新しいブラウザSDKはメンテナンスブラウザSDKによって作成されたCookieを削除します。 falseの場合、ブラウザSDKはメンテナンスブラウザSDKによって作成されたCookieを保持します。
    • デフォルト値null
  • identityStorage
    • 説明String。 ユーザー ID 用のストレージ API を設定します。 オプションには、document.cookie向けのCookie、localStorage向けのlocalStorage、またはユーザーIDの保持をオプトアウトするための「なし」が含まれます。
    • デフォルト値cookie
  • userId
    • 説明String。 追跡対象のユーザーのIDを設定します。 minIdLength オプションで上書きされない限り、最小 5 文字の長さが必要です。
    • デフォルト値null
  • transport
    • 説明String。 名前で使用するリクエスト API を設定します。 オプションには、fetch向けのfetchXMLHTTPRequest向けのxhr、またはnavigator.sendBeacon向けのbeaconがあります。
    • デフォルト値fetch
  • fetchRemoteConfig
    • 説明bool。 SDK がリモート設定を取得するかどうか。 詳細については、ブラウザ SDK 2 を参照してください。 デフォルト値は、使用されているブラウザ SDK のバージョンによって異なります。 ブラウザSDK2.16.1以降の場合、デフォルトはtrueです。
    • デフォルト値false(ブラウザの場合 SDK = 2.16.1)

バッチ処理の動作を設定する

高パフォーマンス環境をサポートするために、SDK はイベントをバッチで送信します。 trackメソッドは、すべてのイベントをメモリにキューイングし、SDKはバックグラウンドでイベントをバッチ処理してフラッシュします。 flushQueueSizeおよびflushIntervalMillisを使用してバッチ動作をカスタマイズできます。 デフォルトでは、serverUrlhttps://api2.amplitude.com/2/httpapiです。

一度に大量のデータを送信する必要がある場合は、useBatchtrueに設定してください。 これはsetServerUrlをバッチイベントアップロードAPIに設定しますhttps://api2.amplitude.com/batch。 通常モードとバッチモードの両方で、同じイベントアップロードしきい値とフラッシュ時間間隔を使用します。

dart
final Amplitude analytics = Amplitude(Configuration(
    apiKey: 'YOUR-API-KEY',
    flushIntervalMillis: 50000,
    flushQueueSize: 20,
));

EU域内のデータレジデンシー

クライアントを初期化してAmplitudeのEUサーバーにデータを送信するときにサーバーゾーンを設定します。 SDKは、設定されている場合にサーバーゾーンに基づいてデータを送信します。

EUデータレジデンシーの場合、プロジェクトはAmplitude EU内に設定する必要があります。 SDKは、Amplitude EUから提供されたAPIキーを使用して初期化する必要があります。

dart
final Amplitude analytics = Amplitude(Configuration(
    apiKey: 'YOUR-API-KEY',
    serverZone: ServerZone.eu,
));

追跡

イベントは、ユーザーがアプリケーションとどのように対話するかを表します。 たとえば、「再生された曲」は、追跡したいアクションです。

dart
amplitude.track(BaseEvent('Song Played'));

オプションでイベントプロパティを含めることもできます。

dart
amplitude.track(BaseEvent('Song Played', eventProperties: {'title': 'Happy Birthday'}));

利用可能なすべてのフィールドについては、BaseEventインターフェイスを参照してください。

Identify

Identifyを使用すると、イベントを送信することなく特定のユーザーのユーザープロパティを設定できます。 SDKは、個々のユーザープロパティに対してsetsetOnceunsetaddappendprependpreInsertpostInsertremoveclearAllなどの操作をサポートしています。 指定された Identify インターフェイスを使用して操作を宣言します。 単一のIdentifyオブジェクトに複数の操作をチェーン化し、IdentifyオブジェクトをAmplitudeクライアントに渡してサーバーに送信することができます。

イベントのあとに Identify 呼び出しを送信した場合、操作の結果はすぐにダッシュボードのユーザーのプロフィール領域に表示されますが、SDK が Identify 呼び出しのあとに別のイベントを送信するまでチャート結果には表示されません。 その結果、Identify コールは将来のイベントにのみ影響します。 詳細については、「ユーザー プロパティとイベント」を参照してください。

identify メソッドを使用してユーザーの ID を処理できます。 これらのメソッドを適切に使用することで、ユーザーがデバイス、ブラウザ、その他のプラットフォームを移動する際にイベントを適切なユーザーに結びつけることができます。 これらのユーザープロパティ操作を含む identify コールを Amplitude サーバーに送信し、ユーザーのイベントを特定のユーザープロパティに関連付けます。

dart
final Identify identify = Identify()
    ..set('color', 'green')
amplitude.identify(identify)

すべてのユーザープロパティを消去する

ユーザーからすべてのユーザープロパティを削除する場合に使用します。clearAll この操作は元に戻すことができないため、clearAll注意して使用してください。

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

自動キャプチャ

SDKは、手動による計測を行うことなく、セッション、アプリライフサイクルイベント、ディープリンク、ページビュー、マーケティングアトリビューションを自動的に追跡します。AutocaptureDisabled()AutocaptureEnabled()またはAutocaptureOptions()を使用して、autocaptureパラメータでこの動作を設定します。

defaultTrackingおよびDefaultTrackingOptionsは非推奨です。代わりにautocaptureを使用してください。 defaultTrackingを渡す既存のコードは引き続き機能します。autocaptureを明示的に設定しない場合、SDKはdefaultTrackingから生成します。 両方を渡した場合、autocaptureが優先されます。

autocapturedefaultTrackingの両方を省略した場合、SDKはデフォルトでセッション追跡を有効にします。 ウェブ上では、ページビューとアトリビューション追跡も可能になります。

SDK は次の自動キャプチャ オプションをサポートしています。

自動キャプチャを有効にする

すべてのプラットフォームで自動キャプチャ機能をすべて有効にするには、次を使用してくださいAutocaptureEnabled()

dart
Amplitude(
  Configuration(
    apiKey: 'YOUR-API-KEY',
    autocapture: AutocaptureEnabled(),
  )
);

iOS および Android では、セッション、アプリのライフサイクル、ディープリンクを有効にします。 AutocaptureEnabled()ウェブ上では、ITはページビューとアトリビューションも有効にします。

自動キャプチャを無効にする

すべての自動キャプチャ機能を無効にするには、AutocaptureDisabled()を使用してください:

dart
Amplitude(
  Configuration(
    apiKey: 'YOUR-API-KEY',
    autocapture: AutocaptureDisabled(),
  )
);

自動キャプチャを設定する

きめ細かな制御を行うには、AutocaptureOptionsを使用してください:

dart
Amplitude(
  Configuration(
    apiKey: 'YOUR-API-KEY',
    autocapture: AutocaptureOptions(
      sessions: true,
      appLifecycles: true,
      deepLinks: true,
      pageViews: PageViewsOptions(
        trackHistoryChanges: 'pathOnly',
        eventType: '[Amplitude] Page Viewed',
      ),
      attribution: AttributionOptions(
        excludeReferrers: ['example.com'],
        initialEmptyValue: 'NONE',
        resetSessionOnNewCampaign: true,
      ),
    ),
  )
);

Amplitudeは将来のバージョンでより多くのイベントを自動キャプチャし、AutocaptureEnabled()それらのイベントの追跡を可能にする可能性があります。

セッションを追跡する

sessionstrueに設定すると、Amplitudeはセッション開始とセッション終了のイベントを追跡します。 sessionsfalseに設定した場合、AmplitudeはsessionIdのみを追跡します。

dart
Amplitude(
  Configuration(
    apiKey: 'YOUR-API-KEY',
    autocapture: AutocaptureOptions(
      sessions: true,
    )
  )
);

アプリケーションのライフサイクルを追跡

appLifecycles``trueに設定すると、AmplitudeはiOSとAndroid上のアプリケーションライフサイクルイベントを追跡します。

dart
Amplitude(
  Configuration(
    apiKey: 'YOUR-API-KEY',
    autocapture: AutocaptureOptions(
      appLifecycles: true,
    )
  )
);

この設定を有効にした後、Amplitudeは以下のイベントを追跡します。

  • [Amplitude] Application Installed:インストール直後にユーザーが初めてアプリケーションを開いたときに起動します。
  • [Amplitude] Application Updated: ユーザーがアプリケーションを更新した後にアプリケーションを開いたときに起動します。
  • [Amplitude] Application Opened: ユーザーがアプリケーションを起動するか、最初に開いた後にアプリケーションをフォアグラウンドに移動したときに発生します。
  • [Amplitude] Application Backgrounded: ユーザーがアプリケーションをバックグラウンドに移行したときに発生します。

追跡されるイベントプロパティには、[Amplitude] Version[Amplitude] Build[Amplitude] Previous Version[Amplitude] Previous Build[Amplitude] From Backgroundがあります。

ディープリンクを追跡する

ディープリンクトラッキングはAndroidでのみ利用できます。 iOS ネイティブ SDK はディープリンクを自動キャプチャオプションとして公開していないため、Flutter SDK は iOS 上のdeepLinksフラグを無視します。

deepLinks``trueに設定すると、AmplitudeはAndroidアプリケーション内のディープリンクに関連するイベントを追跡します。

dart
Amplitude(
  Configuration(
    apiKey: 'YOUR-API-KEY',
    autocapture: AutocaptureOptions(
      deepLinks: true,
    )
  )
);

この設定を有効にすると、AmplitudeはURLとリファラ情報を使用してその[Amplitude] Deep Link Openedイベントを追跡します。 追跡されるイベントプロパティには、[Amplitude] Link URL[Amplitude] Link Referrerがあります。

ページビュー数

ウェブ上でPageViewsOptionsを使用して、ページビューのトラッキングを設定します:

dart
autocapture: AutocaptureOptions(
  pageViews: PageViewsOptions(
    trackHistoryChanges: 'pathOnly',
    eventType: 'Page View',
  ),
)

ページビューのトラッキングを無効にするには、PageViewsDisabled()を使用してください:

dart
autocapture: AutocaptureOptions(
  pageViews: PageViewsDisabled(),
)

アトリビューション

AttributionOptionsを使用して、ウェブ上でマーケティングアトリビューションのトラッキングを設定します:

dart
autocapture: AutocaptureOptions(
  attribution: AttributionOptions(
    excludeReferrers: ['example.com', 'internal.com'],
    initialEmptyValue: 'NONE',
    resetSessionOnNewCampaign: true,
  ),
)

アトリビューションのトラッキングを無効にするには、AttributionDisabled()を使用してください:

dart
autocapture: AutocaptureOptions(
  attribution: AttributionDisabled(),
)

ユーザーグループ

Amplitudeでは、ユーザーをグループに割り当てたり、それらのグループに対して「ユニーク数による集計」などのクエリを実行したりすることができます。 グループの少なくとも1人のメンバーが特定のイベントを実行した場合、そのグループもカウントに含まれます。

たとえば、「orgId」を使用して、ユーザーが所属する組織ごとにユーザーをグループ化できます。 Joeは'orgId' '10'に属し、Sueは'orgId' '15'に属しています。SueとJoeはどちらも特定のイベントを実行します。 イベントセグメンテーションチャートでその組織をクエリできます。

グループを設定する際には、groupTypegroupNameを定義してください。 前の例では、「orgId」はgroupTypeで、「10」と「15」はgroupNameの値です。 groupTypeのもう1つの例としては、「tennis」や「baseball」などのgroupName値を持つ「sport」があります。

グループを設定すると、groupType:groupNameもユーザープロパティとして設定され、そのユーザーのgroupTypeに設定されている既存のgroupName値と対応するユーザープロパティ値が上書きされます。groupTypeは文字列であり、groupNameは文字列または文字列の配列のいずれかを指定できます。配列はユーザーが複数のグループに属していることを示します。

Joe が 'orgId' '15' にある場合、groupName は '15' です。

dart
// set group with a single group name
amplitude.setGroup('orgId', '15');

Joeが「sport」「tennis」「soccer」にいる場合、結果は「groupName「["tennis"、"soccer"]」です。

dart
// set group with multiple group names
amplitude.setGroup('sport', ['tennis', 'soccer']);

また、groupsを含むEventオブジェクトをtrackに渡すことで、イベントレベルのグループを設定することもできます。 イベントレベルのグループの場合、グループの指定は特定のログイベントにのみ適用され、setGroupを使用して明示的にグループを設定しない限り、ユーザーに保持されることはありません。

dart
amplitude.track(BaseEvent('event type',
    eventProperties: {'event property': 'event property value'},
    groups: {'ordId': '15'}));

グループ識別

Group Identify API を使用して、特定のグループのプロパティを設定または更新します。次の点に留意してください。

  • 更新は将来のイベントにのみ影響を与え、過去のイベントを更新することはありません。
  • 最大5つの固有のグループタイプと合計10のグループを追跡できます。

groupIdentifyメソッドは、グループタイプの文字列パラメータ、グループ名のオブジェクトパラメータ、およびAmplitudeがグループに適用するIdentifyオブジェクトを受け取ります。

dart
final groupType = 'plan';
final groupName = 'enterprise';
final identify = Identify().set('key', 'value');
amplitude.groupIdentify(groupType, groupName, identify);

収益の追跡

Amplitudeはユーザーが生み出した収益を追跡できます。 Amplitudeは、AmplitudeのイベントセグメンテーションとレベニューLTVチャートで使用される特別なフィールドを持つ個別の収益オブジェクトを通じて収益を追跡します。その後、Amplitudeはプラットフォームに収益データを自動的に表示します。 収益オブジェクトは、以下の特別なプロパティに加え、eventPropertiesフィールドを介したユーザー定義のプロパティもサポートしています。

dart
final revenue = Revenue()
  ..productId = 'com.company.productId'
  ..price = 3.99
  ..quantity = 3;
amplitude.revenue(revenue);

カスタムユーザーID

ユーザーを追跡するためのログインシステムがアプリに搭載されている場合は、いつでもsetUserIdにご連絡ください。

イベントの送信

この SDK は HTTP V2 API を使用しており、イベントについても同じ制約に従います。 SDKに記録されるすべてのイベントに、少なくとも1つdeviceId(デフォルトで含まれています)またはuserIdが含まれていることを確認し、これらのフィールドごとに、HTTP APIの制約に従ってください。

計装に関する問題を防ぐために、デバイスIDとユーザーIDは、5文字以上の文字列である必要があります。 イベントに短すぎるデバイスIDまたはユーザーIDが含まれている場合、AmplitudeはそのイベントからID値を削除します。イベントにdeviceIdまたはuserIdの値がない場合、Amplitudeはアップロードを400ステータスで拒否することがあります。 minIdLength設定オプションを設定することで、デフォルトの最小長である 5 文字を上書きできます。

dart
amplitude.setUserId('user@amplitude.com');

カスタムデバイスID

deviceIdを使用して、新しいデバイスIDを割り当てます。 カスタムデバイスIDを設定する際は、その値が十分に一意であることを確認してください。 AmplitudeはUUIDの使用を推奨しています。

イベントの送信

この SDK は HTTP V2 API を使用しており、イベントについても同じ制約に従います。 SDKに記録されるすべてのイベントに、少なくとも1つdeviceId(デフォルトで含まれています)またはuserIdが含まれていることを確認し、これらのフィールドごとに、HTTP APIの制約に従ってください。

計装に関する問題を防ぐために、デバイスIDとユーザーIDは、5文字以上の文字列である必要があります。 イベントに短すぎるデバイスIDまたはユーザーIDが含まれている場合、AmplitudeはそのイベントからID値を削除します。イベントにdeviceIdまたはuserIdの値がない場合、Amplitudeはアップロードを400ステータスで拒否することがあります。 minIdLength設定オプションを設定することで、デフォルトの最小長である 5 文字を上書きできます。

dart
amplitude.setDeviceId('your-unique-device-id');

ユーザーがログアウトしたときにリセットする

resetは、ログアウト後にユーザーを匿名化するためのショートカットです。 ITは次のことを行います:

  • userIdnullに設定します。
  • 現在の設定に基づいて、deviceIdを新しい値に設定します。

空のuserIdと新しいdeviceIdの場合、現在のユーザーはダッシュボードに新しいユーザーとして表示されます。

dart
amplitude.reset();

これは役に立ちましたか?