For AI agents: a documentation index is available at /docs/llms.txt. Append .md to any page URL for markdown, or send Accept: text/markdown.
Flutter SDK 3
これは、Amplitude Analytics Flutter SDKの公式ドキュメントです。
Flutter SDK 4.0 が利用可能になりました。
Amplitude Flutter SDK の改良版が利用可能になりました。 Amplitude Flutter SDK 4.0は、デフォルトのイベントトラッキング、改善されたマーケティングアトリビューショントラッキング、macOSサポートを特徴としています。 Amplitude は、プロダクト分析とマーケティング分析の両方のユースケースに Flutter SDK 4.0 を推奨しています。 最新の Flutter SDK 4.0にアップグレードしてください。 詳細については、『移行ガイド』を参照してください。
互換性
Amplitude Flutter v3.11.0以降、AmplitudeはKotlinバージョンをv1.7.10にアップグレードし、最新のGradleをサポートしました。 v6.7.1より前のバージョンのGradleについては、Amplitude Flutter v3.10.0を使用してください。 以下のマトリックスには、Amplitude Flutter SDKのバージョンごとの最低サポート要件が記載されています。
Amplitude Flutter 3.16.5以降、SDKはFlutter web用にpackage:js ^v0.6.3からdart:js_interopに切り替わりました。これにはDart 3.1以降が必要です。
| Amplitude Flutter | Dart | Gradle | Android Gradle プラグイン | Kotlin Gradle プラグイン |
|---|---|---|---|---|
| >= 3.16.5 | >= 3.1 | 6.7.1 | 3.6.4 | 1.7.10 |
| >= 3.11 <= 3.16.4 | >=2.12 | 6.7.1 | 3.6.4 | 1.7.10 |
SDKをインストールする
pubspec.yamlファイルに移動し、Amplitude SDKを依存関係として追加します。ymldependencies: amplitude_flutter: ^3.13.0ターミナルで
flutter pub getを実行して SDK をインストールします。
iOSのインストール
Podfileにplatform :ios, '10.0'を追加してください。
Bitcodeを有効にするには、Flutterのドキュメントに従ってください。
SDKの初期化
実装を行う前に、AmplitudeプロジェクトのAPIキーを使用してSDKを初期化してください。
import 'package:amplitude_flutter/amplitude.dart';
import 'package:amplitude_flutter/identify.dart';
class YourClass {
Future<void> exampleForAmplitude() async {
// Create the instance
final Amplitude analytics = Amplitude.getInstance(instanceName: "project");
// Initialize SDK
analytics.init(widget.apiKey);
// Log an event
analytics.logEvent('MyApp startup', eventProperties: {
'friend_num': 10,
'is_heavy_user': true
});
}
}
SDK を設定する
Amplitude Flutter SDKは、Amplitude Android Maintenance SDK、Amplitude iOS Maintenance SDK、およびAmplitude JavaScript Maintenance SDKの上で動作します。以下は、Dart の設定可能な設定オプションです。 その他のデフォルト設定の場合:
- Android の場合、Android 設定を参照してください。
- iOS の場合、iOS 設定を参照してください。
- ブラウザの場合、ブラウザの設定を参照してください。
| 名前 | 概要 | デフォルト値 |
|---|---|---|
enableCoppaControl() | IDFA、IDFV、都市、IPアドレス、位置情報の追跡に関するCOPPA (児童オンラインプライバシー保護法) の制限を有効にします。Flutter Web ではサポートされていません。 | Coppa制御はデフォルトで無効になっています。 |
disableCoppaControl() | IDFA、IDFV、都市、IPアドレス、位置情報の追跡に関するCOPPA(児童オンラインプライバシー保護法)の制限を無効にします。Flutter Web ではサポートされていません。 | Coppa制御はデフォルトで無効になっています。 |
setMinTimeBetweenSessionsMillis() | int。 フォアグラウンドトラッキングが無効になっている場合のセッションタイムアウト時間。たとえば、Amplitude.getInstance().setMinTimeBetweenSessionsMillis(100000)です。 入力パラメータはミリ秒単位です。 | 5 minutes |
setEventUploadThreshold() | int。 アップロードを強制する前にSDKがローカルに保存するイベントの最大数です。例:Amplitude.getInstance().setEventUploadThreshold(30)。 | 30 |
setEventUploadPeriodMillis() | int。 SDKが保留中のイベントをサーバーにアップロードするのを待機する時間 (ミリ秒単位)。例:Amplitude.getInstance().setEventUploadPeriodMillis(30000)。 | 30000 |
setServerZone() | String。 送信先のサーバーゾーン。 この設定に基づいてサーバのURLを調整します。例:Amplitude.getInstance().setServerZone(EU)。 | US |
setServerUrl() | String。 SDKがイベントを送信するAPIエンドポイントURLは、ServerZoneによって自動的に選択されます。例:Amplitude.getInstance().setServerUrl(https://www.your-server-url.com)。 | https://api2.amplitude.com/ |
setUseDynamicConfig() | bool。 ユーザーの地理的位置に基づいて最適なサーバー URL を自動的に検出します。 例:setUseDynamicConfig(true)。 | false |
setOptOut() | bool。 ユーザーを追跡から除外します。 例:Amplitude.getInstance().setOptOut(true)。 | false |
trackingSessionEvents() | bool。 ユーザーのセッションの開始と終了に対応する「[Amplitude] Session Start」および「[Amplitude] Session End」セッションイベントを自動的に記録するかどうか。 Flutter Web ではサポートされていません。 詳細はこちら。 | false |
useAppSetIdForDeviceId() | Androidのみです。 AndroidでアプリセットIDをデバイスIDとして使用するかどうか。必要なモジュールと権限については、「アプリケーション セット ID」セクションを参照してください。例:Amplitude.getInstance().useAppSetIdForDeviceId(true)。 | デフォルトでは、deviceIdはUUID+"R"です。 |
バッチ処理の動作を設定する
高パフォーマンス環境をサポートするために、SDK はイベントをバッチで送信します。 SDK は、logEvent メソッドによって記録されたすべてのイベントをメモリ内でキューイングします。SDKはバックグラウンドで、イベントをバッチ単位でフラッシュします。setEventUploadThresholdを使用してバッチ動作をカスタマイズできます。 デフォルトでは、serverUrlはhttps://api2.amplitude.com/です。このSDKはバッチモードまたはバッチAPIエンドポイントをサポートしていません。
// Events queued in memory will flush when number of events exceed upload threshold
// Default value is 30
Amplitude.getInstance().setEventUploadThreshold(1);
// Events queue will flush every certain milliseconds based on setting
// Default value is 30,000 milliseconds
Amplitude.getInstance().setEventUploadPeriodMillis(10000);
EU域内のデータレジデンシー
バージョン3.6.0以降では、クライアントを初期化した後にサーバーゾーンを設定してAmplitudeのEUサーバーにデータを送信できるようになりました。 SDKは、サーバーゾーンを設定した場合、サーバーゾーンに基づいてデータを送信します。サーバゾーン設定は、動的設定もサポートしています。
以前のバージョンの場合、クライアントを初期化した後にserverURLプロパティを設定してください。
EUデータレジデンシーについては、Amplitude EU内にプロジェクトを設定してください。 Amplitude EUから提供されたAPIキーを使用してSDKを初期化します。
// For versions starting from 3.6.0
// No need to call setServerUrl for sending data to Amplitude's EU servers
Amplitude.getInstance().setServerZone("EU");
// For earlier versions
Amplitude.getInstance().setServerUrl("https://api.eu.amplitude.com")
イベントを送信
イベントは、ユーザーがアプリケーションとどのように対話するかを表します。 たとえば、「ボタンのクリック」は、追跡したいアクションかもしれません。
Amplitude.getInstance().logEvent('BUTTON_CLICKED');
プロパティ付きのイベントを送信
イベントにはプロパティも含めることができます。 プロパティは、発生したイベントに関するコンテキストを提供します。 たとえば、「ホバー時間」は、「ボタンクリック」に関連するイベントプロパティである可能性があります。
Amplitude.getInstance().logEvent('BUTTON_CLICKED', {"Hover Time": "100ms"});
イベントをフラッシュする
SDK は通常、イベントをバッファに保存し、定期的にフラッシュします。 この動作は設定可能です。 イベントを手動でフラッシュすることもできます。
Amplitude.getInstance().uploadEvents();
ユーザープロパティ
ユーザープロパティは、ユーザーがアプリ内でアクションを実行した時点でのユーザーの状況を把握するのに役立ちます。たとえば、ユーザーのデバイスの詳細情報、環境設定、言語などです。
Amplitude Flutteridentifyメソッドはこの機能を管理します。使用する前にidentifyをインポートしてください。
import 'package:amplitude_flutter/identify.dart';
プライバシー規約に違反する可能性のあるユーザーデータを追跡しないでください。
セット
set は、ユーザー プロパティの値を設定します。 また、複数のidentifyコールを連結することもできます。
final Identify identify = Identify()
..set('gender','female')
..set('age',20);
Amplitude.getInstance().identify(identify);
一度だけ設定
setOnce は、ユーザープロパティの値を 1 回だけ設定します。 setOnceを使用した以降のコールは無視されます。
final Identify identify1 = Identify();
identify1.setOnce('sign_up_date', '2015-08-24');
Amplitude.getInstance().identify(identify1);
final Identify identify2 = Identify();
identify2.setOnce('sign_up_date', '2015-08-24');
Amplitude.getInstance().identify(identify2);// is ignored
追加する
add は、ユーザープロパティを何らかの数値で増分します。 ユーザープロパティに値がまだ設定されていない場合、Amplitudeは値を増やす前にプロパティを0に初期化します。
final Identify identify = Identify().add('karma', 0.123);
Amplitude.getInstance().identify(identify);
プレインサート
ユーザープロパティに値がまだ存在しない場合、そのユーザープロパティのリストの先頭に1つまたは複数の値を追加します。
ユーザープロパティに値がまだ設定されていない場合、Amplitudeは新しい値を事前に挿入する前にプロパティを空のリストに初期化します。 ユーザープロパティに既存の値がある場合、何も起こりません。
final Identify identify = Identify()
..preInsert('existing_list', 'some_property')
Amplitude.getInstance().identify(identify);
挿入後
ユーザープロパティに値がまだ存在しない場合、1つまたは複数の値をリストの最後に追加します。ユーザープロパティに値がまだ設定されていない場合、Amplitudeは新しい値を挿入する前にプロパティを空のリストに初期化します。 ユーザープロパティに既存の値がある場合、何も起こりません。
final Identify identify = Identify()
..postInsert('existing_list','some_property')
Amplitude.getInstance().identify(identify);
複数のユーザープロパティを設定する
複数のユーザープロパティを一度に設定するための短縮形として、setUserPropertiesを使用できます。このメソッドは、Identify.set および identifyのラッパーです。
Map<String, dynamic> userProps = {
'KEY': 'VALUE',
'OTHER_KEY': 'OTHER_VALUE'
};
Amplitude.getInstance().setUserProperties(userProperties);
ユーザープロパティ内の配列
配列をユーザープロパティとして使用できます。配列を直接設定することも、append を使用して配列を生成することもできます。
const colors = ["rose", "gold"];
const numbers = [4, 5];
final Identify identify = Identify()
..set("colors", colors)
..append("ab-tests", "campaign_a")
..prepend("existing_list", numbers);
Amplitude.getInstance().identify(identify);
先頭への追加と末尾への追加
prependは、ユーザープロパティの前に 1 つまたは複数の値を付加します。appendは、ユーザー プロパティ配列に 1 つまたは複数の値を追加します。
ユーザープロパティに値がまだ設定されていない場合、Amplitudeは新しい値を追加する前にプロパティを空のリストに初期化します。 ユーザープロパティにリスト以外の既存の値がある場合、Amplitudeはその値をリストに変換し、新しい値を追加します。
const array = ["some_string", 56];
final Identify identify = Identify()
..append("ab-tests", "new-user-test")
..prepend("some_list", array)
Amplitude.getInstance().identify(identify);
ユーザープロパティを削除する
clearUserPropertiesは、現在のユーザーのすべてのユーザープロパティをクリアします。
この結果は不可逆的です。 Amplitudeは、ユーザーのユーザープロパティ値をワイプ前の時点から将来のイベントに同期させることはできません。
Amplitude.getInstance().clearUserProperties();
削除する
removeは、ユーザープロパティから1つまたは複数の値を削除します。その項目がユーザープロパティに存在しない場合、何も起こりません。
const array = ["some_string", 56];
final Identify identify = Identify()
..remove("ab-tests", "new-user-test")
..remove("some_list",array);
Amplitude.getInstance().identify(identify);
unset
unset ユーザープロパティの設定を解除および削除します。
final Identify identify = Identify()
..unset("ab-tests", "new-user-test")
..unset("some_list",array);
Amplitude.getInstance().identify(identify)
ユーザーグループ
Amplitudeでは、ユーザーをグループに割り当てたり、それらのグループに対して「ユニーク数による集計」などのクエリを実行したりすることができます。 グループの少なくとも1人のメンバーが特定のイベントを実行した場合、そのグループはカウントに含まれます。
たとえば、「orgId」を使用して、ユーザーが所属する組織に基づいてユーザーをグループ化したい場合などです。 Joeは'orgId' '10'に属し、Sueは'orgId' '15'に属しています。SueとJoeはどちらも特定のイベントを実行します。 イベントセグメンテーションチャートでその組織をクエリできます。
グループを設定する際には、groupTypeとgroupNameを定義してください。前の例では、「orgId」はgroupTypeで、「10」と「15」はgroupNameの値です。 groupTypeのもう1つの例としては、「tennis」や「baseball」などのgroupName値を持つ「sport」があります。
グループを設定すると、groupType:groupNameもユーザープロパティとして設定され、そのユーザーのgroupTypeに設定されている既存のgroupNameの値と対応するユーザープロパティ値が上書きされます。groupTypeは文字列であり、groupNameはユーザーが複数のグループに属していることを示す文字列または文字列の配列のいずれかを指定できます。
Joe が 'orgId' の '15' にある場合、groupName は '15' になります。
// set group with a single group name
Amplitude.getInstance().setGroup("orgId", "15");
ジョーが「sport」の「tennis」と「soccer」に含まれている場合、groupNameは「["tennis", "soccer"]」になります。
// set group with multiple group names
Amplitude.getInstance().setGroup("sport", ["tennis", "soccer"]);
イベントレベルのグループは使用できません。また、その使用可能性については未定です。
収益の追跡
Amplitudeはユーザーが生み出した収益を追跡できます。 Amplitudeは、AmplitudeのイベントセグメンテーションとレベニューLTVチャートで使用される特別なフィールドを持つ個別の収益オブジェクトを通じて収益を追跡します。Amplitudeはプラットフォーム内の収益に関連するデータを自動的に表示します。
Amplitudeは通貨換算をサポートしていません。 すべての収益データを送信する前に、選択した通貨に正規化してください。
String productId = "product001";
int quantity = 2;
double price = 20;
double amount = 35;
Amplitude.getInstance().logRevenue(productId, quantity, price);
Amplitude.getInstance().logRevenueAmount(amount);
価格は負数にすることもできます。これは、損失した収益(払い戻しやコストなど)を追跡するのに役立ちます。
グループユーザープロパティ
Group Identify API を使用して、特定のグループのプロパティを設定または更新します。次の点に留意してください。
- 更新は将来のイベントにのみ影響を与え、過去のイベントを更新することはありません。
- 最大5つの固有のグループタイプと合計10のグループを追跡できます。
groupIdentifyメソッドは、グループタイプの文字列パラメータ、グループ名のオブジェクトパラメータ、およびAmplitudeがグループに適用するIdentifyオブジェクトを受け取ります。
final Identify identify = Identify()
..set("gender", "female")
..set("age", 20);
Amplitude.getInstance().groupIdentify("groupType", "groupValue", identify);
ユーザーセッション
セッションとは、ユーザーがアプリをフォアグラウンドに置いている期間のことです。 同じセッション内で記録されたイベントは、同じsession_idを共有します。 SDKはセッションを自動的に処理するため、startSession()またはendSession() などのAPIを手動で呼び出す必要はありません。
Amplitudeはイベントをセッションごとにグループ化します。 セッションは、開始時刻と終了時刻を持つユーザーのアクティビティの単一期間を表します。 プラットフォームの要件に応じて、SDK ごとにセッションの追跡方法が異なります。
Android と iOS では、ユーザーのセッションの開始と終了に対応するセッション開始と終了イベントを自動的に記録するように選択できます。 Flutter Web はこれをサポートしていません。
//Enable automatically log start and end session events
Amplitude.getInstance().trackingSessionEvents(true);
//Disable automatically log start and end session events
Amplitude.getInstance().trackingSessionEvents(false);
Flutter Web は trackingSessionEvents() をサポートしていません。
カスタムユーザーIDを設定する
アプリに独自のログインシステムがあり、ユーザーを追跡したい場合は、いつでもsetUserIdを呼び出してください。
Amplitude.getInstance().setUserId("test_user_id");
カスタムデバイスIDを設定する
デフォルトでは、AmplitudeはデバイスIDをランダムなUUIDとして生成します。setDeviceIdを呼び出すことでカスタムデバイスIDを定義できます。
Amplitude.getInstance().setDeviceId('test_device_id');
Amplitudeが使用するデバイスIDは、Amplitude.getInstance().getDeviceId().で取得できます。AmplitudeがまだdeviceIdを生成していない場合、このメソッドはnullを返すことがあります。
Amplitudeは、ユーザーデバイスを追跡するための独自のシステムがない限り、独自のデバイスIDを定義することを推奨しません。 Amplitudeデータ内の他のデバイスとの競合を防ぐために、設定するdeviceIdが一意であることを確認してください。
高度なトピック
COPPA制御
IDFA、IDFV、都市、IPアドレス、位置情報の追跡に関するCOPPA(児童オンラインプライバシー保護法)の制限をすべて一度に有効または無効にできます。
13 歳未満の子供から情報を求めるアプリは、COPPA に準拠する必要があります。
// Enable COPPA Control
Amplitude.getInstance().enableCoppaControl();
// Disable COPPA Control
Amplitude.getInstance().disableCoppaControl();
広告ID
広告主ID(IDFAとも呼ばれます)は、iOSおよびGoogle Playストアが提供する固有の識別子です。この情報はデバイスだけでなく、ユーザー一人ひとりに固有のものであるため、モバイルアトリビューションに役立ちます。モバイルアトリビューションとは、モバイルアプリのインストールが元のソース(広告キャンペーンやアプリストアの検索など)に帰属することです。
モバイルアプリはIDFAを要求するには権限を必要とし、子供をターゲットにしたアプリはまったく追跡できません。IDFAが利用できない場合は、代替手段としてIDFVやデバイスID、またはEメールログインシステムを検討してください。
詳細については、iOS広告IDまたはAndroid広告IDを参照してください。
追跡のオプトアウト
ユーザーはトラッキングを完全にオプトアウトしたい場合があります。つまり、Amplitudeはイベントを追跡したり、ユーザーの閲覧履歴を記録したりしません。setOptOutプライバシーに対するユーザーの要求に応える方法を提供します。
//Disables instrumentation
Amplitude.getInstance().setOptOut(true);
//Enables instrumentation
Amplitude.getInstance().setOptOut(false);
動的な設定
Flutter SDKを使用すると、ユーザーは動的設定を使用するようにアプリを設定できます。この機能は、アプリユーザーの所在地に基づいて最適なサーバー URL を自動的に検出します。
- 独自のプロキシサーバーを持ち、
setServerUrlAPI を使用している場合は、動的設定を使用しないでください。 - 中国本土にユーザーがいる場合、Amplitudeでは動的設定を使用することを推奨します。
- デフォルトでは、この機能はオフになっています。 使用するには、明示的に有効にする必要があります。
- デフォルトでは、この機能はAmplitudeの米国サーバーのサーバーURLを返します。 AmplitudeのEUサーバーにデータを送信する必要がある場合は、
setServerZoneを使用してEUゾーンに設定してください。
Amplitude.getInstance().setUseDynamicConfig(true);
Flutter Webサポート
Flutterウェブサポートは、ウェブ上でモバイル上と同様の体験を提供します。Amplitude Flutter SDKはv3.8.0以降でFlutter Webをサポートしています。
Flutter Web は以下の機能をサポートしていません:
enableCoppaControl。disableCoppaControl。trackingSessionEvents。 Flutter WebはStart SessionおよびEnd Sessionイベントの自動送信をサポートしていませんが、SDKは自動的にセッションIDを追跡します。この機能は、ユーザーセッションやパスファインダーチャートなどの一般的なセッションベースの分析に使用できます。 詳細については、Amplitudeでのセッションのトラッキングに関するヘルプドキュメントを参照してください。useAppSetIdForDeviceId。
用途
以下の Amplitude-JavaScript スニペットを Flutter プロジェクト内の web/index.html に追加してください。Amplitude-JavaScriptのバージョンはv8.12.0以降である必要があります。
<script type="text/javascript" defer>
(function (e, t) {
var n = e.amplitude || { _q: [], _iq: {} };
var r = t.createElement("script");
r.type = "text/javascript";
r.integrity =
"sha384-UcvEbHmT0LE2ZB30Y3FmY3Nfw6puAKXz/LpCFuoywywYikMOr/519Uu1yNq2nL9w";
r.crossOrigin = "anonymous";
r.async = true;
r.src = "https://cdn.amplitude.com/libs/amplitude-8.12.0-min.gz.js";
r.onload = function () {
if (!e.amplitude.runQueuedFunctions) {
console.log("[Amplitude] Error: could not load SDK");
}
};
var s = t.getElementsByTagName("script")[0];
s.parentNode.insertBefore(r, s);
function i(e, t) {
e.prototype[t] = function () {
this._q.push([t].concat(Array.prototype.slice.call(arguments, 0)));
return this;
};
}
var o = function () {
this._q = [];
return this;
};
var a = [
"add",
"append",
"clearAll",
"prepend",
"set",
"setOnce",
"unset",
"preInsert",
"postInsert",
"remove",
];
for (var c = 0; c < a.length; c++) {
i(o, a[c]);
}
n.Identify = o;
var u = function () {
this._q = [];
return this;
};
var l = [
"setProductId",
"setQuantity",
"setPrice",
"setRevenueType",
"setEventProperties",
];
for (var p = 0; p < l.length; p++) {
i(u, l[p]);
}
n.Revenue = u;
var d = [
"init",
"logEvent",
"logRevenue",
"setUserId",
"setUserProperties",
"setOptOut",
"setVersionName",
"setDomain",
"setDeviceId",
"enableTracking",
"setGlobalUserProperties",
"identify",
"clearUserProperties",
"setGroup",
"logRevenueV2",
"regenerateDeviceId",
"groupIdentify",
"onInit",
"logEventWithTimestamp",
"logEventWithGroups",
"setSessionId",
"resetSessionId",
"getDeviceId",
"getUserId",
"setMinTimeBetweenSessionsMillis",
"setEventUploadThreshold",
"setUseDynamicConfig",
"setServerZone",
"setServerUrl",
"sendEvents",
"setLibrary",
"setTransport",
];
function v(e) {
function t(t) {
e[t] = function () {
e._q.push([t].concat(Array.prototype.slice.call(arguments, 0)));
};
}
for (var n = 0; n < d.length; n++) {
t(d[n]);
}
}
v(n);
n.getInstance = function (e) {
e = (!e || e.length === 0 ? "$default_instance" : e).toLowerCase();
if (!Object.prototype.hasOwnProperty.call(n._iq, e)) {
n._iq[e] = { _q: [] };
v(n._iq[e]);
}
return n._iq[e];
};
e.amplitude = n;
})(window, document);
</script>
関連する互換性リソース
Android Gradleプラグインの互換性、Gradleの互換性、およびKotlinの互換性について詳しくはこちらをご覧ください。
トラブルシューティング
iOSでBitcodeを有効にすることに問題がある場合は、Flutterのドキュメントを参照してください。
Was this helpful?