実験 Flutter SDK

Amplitude ExperimentのクライアントサイドFlutter SDKに関する公式ドキュメントです。

インストール

amplitude_experimentパッケージをpubspec.yamlに追加してください：

dependencies:
  amplitude_experiment: ^1.0.0

次に実行します:

flutter pub get

Webインストール（オプション）

Flutter 実験 SDKは、DartのJavaScript相互運用性を使用して、Flutter Web向けに実験 JavaScript SDKを有効にします。そのためには、グローバルなJavaScriptスコープ内でSDKを使用できるようにする必要があります。Flutter プロジェクトの web/index.html に次のスクリプトタグを追加してください。

<script src="https://unpkg.com/@amplitude/experiment-js-client@1.21.3/dist/experiment.umd.js"></script>

import 'package:amplitude_flutter/amplitude.dart';
import 'package:amplitude_flutter/configuration.dart';
import 'package:amplitude_experiment/amplitude_experiment.dart';
// (1) Initialize the Amplitude Analytics SDK.
final amplitude = Amplitude(Configuration(apiKey: 'API_KEY'));
await amplitude.isBuilt;
// (2) Initialize the experiment client with Amplitude Analytics.
final experiment = await Experiment.initializeWithAmplitude(
  'DEPLOYMENT_KEY',
  ExperimentConfig(),
);
// (3) Fetch variants and await the result.
await experiment.fetch();
// (4) Look up a flag's variant.
final variant = await experiment.variant('FLAG_KEY');
if (variant.value == 'on') {
  // Flag is on
} else {
  // Flag is off
}

初期化する

スタートアップ時にアプリケーション内のSDKクライアントを初期化します。apiKeyパラメーターに渡すデプロイメントキー引数は、アナリティクスイベントの送信先となるプロジェクトと同じプロジェクト内に存在する必要があります。

static Future<ExperimentClient> initializeWithAmplitude(String apiKey, ExperimentConfig config)

初期化子はシングルトンインスタンスを返すため、同じインスタンス名に対する後続の初期化は常に最初のインスタンスを返します。複数のインスタンスを作成するには、instanceNameの設定を使用します。

import 'package:amplitude_flutter/amplitude.dart';
import 'package:amplitude_flutter/configuration.dart';
import 'package:amplitude_experiment/amplitude_experiment.dart';
final amplitude = Amplitude(Configuration(apiKey: 'API_KEY'));
await amplitude.isBuilt;
final experiment = await Experiment.initializeWithAmplitude(
  'DEPLOYMENT_KEY',
  ExperimentConfig(),
);

設定

SDKクライアントの設定は、初期化時に実行されます。

• logLevel
  • 説明：出力する最低ログレベルです。 オプション：LogLevel.none、LogLevel.error、LogLevel.warn、LogLevel.info、LogLevel.debug、LogLevel.verbose。
  • デフォルト値：LogLevel.warn
• fallbackVariant
  • 説明： 指定されたキーのバリアントが存在しない場合にフォールバックするデフォルトのバリアントです。
  • デフォルト値：null
• initialVariants
  • 説明： アクセスするためのバリアントの初期セットです。このフィールドは、サーバー側レンダリング (SSR) を使用してサーバーによりレンダリングされた値でクライアントSDKをブートストラップするのに役立ちます。
  • デフォルト値：{}
• source
  • 説明：バリアントの主なソースです。 値を Source.initialVariants に設定し、SSR またはテスト目的で SDK をブートストラップするために initialVariants を構成します。
  • デフォルト値：Source.localStorage
• serverZone
  • 説明：フラグとバリアントを取得する Amplitude データセンターを、us または eu から選択してください。
  • デフォルト値：ServerZone.us
• serverUrl
  • 説明：リモート評価バリアントを取得するホストです。 EU のデータセンターにアクセスするには、serverZone を使用します。
  • デフォルト値：https://api.lab.amplitude.com
• flagsServerUrl
  • 説明：ローカル評価フラグを取得するホストです。 EU のデータセンターにアクセスするには、serverZone を使用します。
  • デフォルト値：https://flag.lab.amplitude.com
• fetchTimeoutMillis
  • 説明：バリアントを取得するためのタイムアウト（ミリ秒単位）。
  • デフォルト値：10000
• retryFetchOnFailure
  • 説明：リクエストが成功しなかった場合に、バックグラウンドでバリアントの取得を再試行するかどうか。
  • デフォルト値：true
• automaticExposureTracking
  • 説明：true の場合、variant() を呼び出すと、設定済みの trackingProvider を通じて露出イベントが追跡されます。トラッキング プロバイダーが設定されていない場合、この設定オプションは何も行われません。
  • デフォルト値：true
• fetchOnStart
  • 説明: true の場合、起動時に常にリモート評価バリアントを取得します。 false の場合、開始時に決して取得を行いません。
  • デフォルト値：true
• pollOnStart
  • 説明：起動時にローカル評価フラグ設定の更新をポーリングします。 ポーリング間隔を flagConfigPollingIntervalMillis で設定します。
  • デフォルト値：true
• flagConfigPollingIntervalMillis
  • 説明：pollOnStart を有効にした場合のフラグ設定ポーリングの間隔（ミリ秒単位）。 SDKは、60000未満の値をすべて60000に上げます。
  • デフォルト値：300000
• automaticFetchOnAmplitudeIdentityChange
  • 説明: initializeWithAmplitudeを使用する場合にのみ重要です。 trueの場合、アナリティクスによるユーザー ID、デバイス ID、ユーザープロパティの変更により、実験 SDK はバリアントを取得し、そのキャッシュを更新します。
  • デフォルト値：false
• userProvider
  • 説明：呼び出されたときにユーザー オブジェクトを提供するインターフェイスですfetch()。ユーザープロバイダーに移動します。
  • デフォルト値：null
• trackingProvider
  • 説明: このインターフェイスを実装および設定して、実験用SDKを通じて露出イベントを自動的にまたは明示的に追跡してください。 露出追跡プロバイダーに移動します。
  • デフォルト値：null
• instanceName
  • 説明：実験用SDKインスタンスのカスタムインスタンス名です。 このフィールドの値は大文字と小文字を区別します。
  • デフォルト値：$default_instance
• initialFlags
  • 説明：ローカル評価に使用するフラグ設定の初期セットを表す JSON 文字列です。
  • デフォルト値：null

統合

Amplitude Analytics SDKを使用してAmplitudeへのイベントをトラッキングする場合、Amplitudeは初期化時に連携を設定することをお勧めします。連携はプロバイダーインターフェイスを実装することで、ユーザーIDの管理やエクスポージャーイベントの追跡を容易にし、より合理化された開発者体験を実現します。

取得

ユーザーのバリアントを取得し、高速アクセスのために結果をクライアントに保存します。 この関数は、SDKクライアントの初期化に使用されたデプロイメントに関連付けられているフラグについて、ユーザーを リモートで評価します。

Future<void> fetch([ExperimentUser? user, FetchOptions? options])

Amplitude Experimentは、ユーザーがアプリケーションセッションの最新のバリアントを取得できるように、アプリケーションの起動時にfetch()を呼び出すことを推奨しています。ユーザーエクスペリエンスをレンダリングする前に、フェッチリクエストの結果が返されるのを待ち、インターフェイスの「ちらつき」を回避してください。

final user = ExperimentUser(
  userId: 'user@company.com',
  deviceId: 'abcdefg',
  userProperties: {'premium': true},
);
await experiment.fetch(user);

連携またはカスタムユーザープロバイダーを使用している場合は、ユーザーを入力せずに取得できます。

await experiment.fetch();

fetch()がタイムアウト（デフォルトは10秒）した場合や何らかの理由で失敗した場合、SDKクライアントは制御を戻し、バックオフを使用してバックグラウンドで再試行します。SDKクライアントの初期化時に設定オプションでタイムアウトを設定したり、再試行を無効にしたりできます。

スタート

実験 SDK を起動してサーバーからフラグ設定を取得し、ユーザー用にリモート評価バリアントを取得します。返された Future が完了すると、SDK は準備が整います。

Future<void> start(ExperimentUser? user)

アプリケーションの初期化時、ユーザー情報がバリアントの評価または取得に利用可能になった後に、start()を呼び出してください。Future は、ローカル評価フラグ設定をロードし、リモート評価バリアントを取得した後に完了します。

SDK 設定で fetchOnStart を設定して start() の動作を制御し、アプリケーションのパフォーマンスを向上させます。

• アプリケーションがリモート評価に依存しない場合は、リモート評価によるスタートアップ遅延の増加を避けるために、fetchOnStart を false に設定してください。
• アプリケーションがリモート評価に依存しているものの、スタートアップ直後には必要ない場合は、fetchOnStart をfalse に設定し、fetch() を呼び出して別途 Future を待機させることができます。

await experiment.start(null);

バリアント

SDKクライアントのローカルストアからフラグまたは実験のバリアントにアクセスします。

Future<Variant> variant(String flagKey, [Variant? fallbackVariant])

ユーザーがどのバリアントに割り当てられているかを判断する際には、そのバリアントvalueを既知の文字列と比較してください。

final variant = await experiment.variant('FLAG_KEY');
if (variant.value == 'on') {
  // Flag is on
} else {
  // Flag is off
}

final variant = await experiment.variant('FLAG_KEY');
if (variant.value == 'on') {
  final payload = variant.payload;
}

nullバリアントvalueとは、ユーザーがバリアントに割り当てられていないことを意味します。 組み込みのフォールバックパラメータを使用して、ストアに指定されたフラグキーのバリアントがない場合に返すバリアントを指定できます。

final variant = await experiment.variant(
  'FLAG_KEY',
  Variant(value: 'control'),
);
if (variant.value == 'control') {
  // Control
} else if (variant.value == 'treatment') {
  // Treatment
}

すべて

SDKクライアントによって保存されているすべてのバリアントにアクセスできます。

Future<Map<String, Variant>> all()

クリア

キャッシュとストレージ内のすべてのバリアントをクリアします。

Future<void> clear()

ユーザーのログアウト後に clear を呼び出して、キャッシュとストレージ内のバリアントをクリアできます。

await experiment.clear();

エクスポージャー

設定済みの連携またはカスタムエクスポージャー追跡プロバイダーを通じて、指定されたフラグキーの現在のバリアントに対するエクスポージャーイベントを手動で追跡します。一般的に、automaticExposureTracking 構成オプションを falseに設定するときに使用されます。

Future<void> exposure(String flagKey)

final variant = await experiment.variant('FLAG_KEY');
// Do other things...
await experiment.exposure('FLAG_KEY');
if (variant.value == 'control') {
  // Control
} else if (variant.value == 'treatment') {
  // Treatment
}

プロバイダー

プロバイダーの実装は、ユーザーIDの管理やエクスポージャーイベントの追跡を容易にすることで、より合理化された開発者体験を実現します。

ユーザープロバイダー

SDKクライアントは、必要な場合（たとえば、fetch()が呼び出されたとき）にのみ、ユーザープロバイダーを使用して最新のユーザー情報にアクセスします。ユーザープロバイダはオプションですが、アプリケーションにユーザー情報ストアがすでに設定されている場合に役立ちます。 ユーザープロバイダーを使用すると、2 つの別々のユーザー情報ストアを並行して管理する必要はありません。 アプリケーションのユーザーストアが更新されていても実験が更新されていない場合（またはその逆の場合）に、個別のストアが異なるユーザー状態を作成することがあります。

abstract interface class UserProvider {
  ExperimentUser getUser();
}

カスタムユーザープロバイダーを使用するには、SDK の初期化時にカスタム実装のインスタンスを使用してuserProviderの設定オプションを指定してください。

class CustomUserProvider implements UserProvider {
  @override
  ExperimentUser getUser() {
    // Return the current user from your app's user store
    return ExperimentUser(userId: 'user@company.com');
  }
}
final experiment = await Experiment.initialize(
  'DEPLOYMENT_KEY',
  ExperimentConfig(
    userProvider: CustomUserProvider(),
  ),
);

エクスポージャー追跡プロバイダー

Amplitudeは露出追跡プロバイダーを実装することを強く推奨しています。 露出追跡は実験結果の正確性と信頼性を高め、ユーザーがどのフラグや実験にさらされているかをより明確に把握できるようにします。

abstract interface class ExposureTrackingProvider {
  void track(Exposure exposure);
}

track()の実装では、Exposureオブジェクト引数の2つのフィールドに対応する2つのイベントプロパティ、flag_keyおよびvariantを使用して、タイプ$exposure（別名：名前）のイベントを追跡する必要があります。最後に、追跡されたイベントは、SDKクライアントの初期化に使用されたデプロイメントが存在するのと同じプロジェクトについて、そしてバリアントが取得されたのと同じユーザーについて、最終的にAmplitude Analyticsに記録される必要があります。

カスタム露出トラッキングプロバイダーを使用するには、SDK の初期化時にカスタム実装のインスタンスを使用してtrackingProviderの設定オプションを設定してください。

class CustomExposureTracker implements ExposureTrackingProvider {
  @override
  void track(Exposure exposure) {
    // Track the exposure event to your analytics provider
    analytics.track('\$exposure', {
      'flag_key': exposure.flagKey,
      'variant': exposure.variant,
    });
  }
}
final experiment = await Experiment.initialize(
  'DEPLOYMENT_KEY',
  ExperimentConfig(
    trackingProvider: CustomExposureTracker(),
  ),
);

ブートストラップ

バリアントが外部ソースから来た場合（たとえば、SDKクライアントへの呼び出しからfetch()ではない場合など）、実験用クライアントを初期のフラグとバリアントセットでブートストラップすることが望ましい場合があります。ユースケースには、ローカル評価、サーバー側レンダリング、特定のバリアントに対する連携テストなどがあります。

初期バリアント

クライアントをブートストラップするには、initialVariantsの設定オプションでフラグとバリアントを設定し、source をSource.initialVariants に設定します。これにより、SDKクライアントは同じフラグに対して以前に取得および保存されたバリアントよりもブートストラップされたバリアントを優先します。

final experiment = await Experiment.initialize(
  'DEPLOYMENT_KEY',
  ExperimentConfig(
    initialVariants: {
      'flag-key-1': Variant(value: 'on'),
      'flag-key-2': Variant(value: 'treatment'),
    },
    source: Source.initialVariants,
  ),
);

初期フラグ

ローカル評価用に一連のフラグ設定を使用してクライアントをブートストラップするには、フラグ設定のJSON文字列を使用して設定initialFlagsオプションを指定します。

final experiment = await Experiment.initialize(
  'DEPLOYMENT_KEY',
  ExperimentConfig(
    initialFlags: '{"flag-key-1": ...}',
  ),
);