実験Android SDK

Amplitude Experimentのクライアント側Android SDK実装に関する公式ドキュメントです。

インストール

Androidプロジェクトのbuild.gradle ファイルに依存関係を追加します。

dependencies {
  implementation 'com.amplitude:experiment-android-client:<VERSION>'
}

class MyApplication : Application() {
    override fun onCreate() {
        super.onCreate()
        // (1) Initialize the experiment client
        val client = Experiment.initializeWithAmplitudeAnalytics(
            this, "DEPLOYMENT_KEY", ExperimentConfig()
        )
        // (2) Fetch variants
        try {
            // NOTE: The future returned resolves after a network call. Do not
            //       wait for this future on the main application thread in
            //       production applications to avoid ANR if the user has a poor
            //       network connection.
            client.fetch().get()
        } catch (e: Exception) {
            e.printStackTrace()
        }
        // (3) Lookup a flag's variant
        val variant = client.variant("<FLAG_KEY>")
        if (variant.value == "on") {
            // Flag is on
        } else {
            // Flag is off
        }
    }
}

初期化する

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

fun initializeWithAmplitudeAnalytics(
    application: Application, apiKey: String, config: ExperimentConfig
)

• application
  • 要件: 必須
  • 説明：Android Applicationコンテキストです。セッション間でバリアントを保持するために使用されます。
• apiKey
  • 要件: 必須
  • 説明: フェッチリクエストを承認し、SDKがユーザーに対してどのフラグを評価するかを決定するデプロイメントキーです。
• config
  • 要件: オプション
  • 説明：SDKクライアントの動作をカスタマイズするために使用されるクライアント設定です。

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

val experiment = Experiment.initializeWithAmplitudeAnalytics(
    context,
    "DEPLOYMENT_KEY",
    ExperimentConfig().apply {
        // must match the name you used for your Amplitude Analytics instance
        instanceName = "myCustomInstance"
    }
)

設定

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

統合

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

取得

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

fun fetch(user: ExperimentUser? = null, options: FetchOptions? = null): Future<ExperimentClient>

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

try {
    ExperimentUser user = ExperimentUser.builder()
        .userId("user@company.com")
        .userProperty("premium", true)
        .build();
    experiment.fetch(user).get();
} catch (Exception e) {
    e.printStackTrace();
}

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

experiment.fetch(null);

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

スタート

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

fun start(user: ExperimentUser? = null): Future<ExperimentClient>

| パラメータ | 要件 | 概要 | | --------- | ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------ | | user | オプション | バリアントを取得するためのリクエストに渡す明示的なユーザー情報。 SDK は、ユーザープロバイダーを通じて統合から提供されたユーザー情報とこのユーザー情報を統合し、提供されたプロパティよりも明示fetch()的に渡されたプロパティを優先します。また、SDK 内のユーザーを再利用できるように設定します。 | null |

アプリケーションの初期化時に呼び出してください。これは、ユーザー情報がバリアントを取得できる状態になった後に実行されます。start() Future は、ローカル評価フラグ設定をロードし、リモート評価バリアントを取得した後に解決されます。

アプリケーションのニーズに基づいてパフォーマンスを向上させるため、初期化時の SDK 設定で fetchOnStart を設定して start() の動作を構成します。

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

try {
    experiment.start().get();
} catch (e: Exception) {
    e.printStackTrace();
}

バリアント

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

fun variant(key: String, fallback: Variant? = null): Variant

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

Variant variant = client.variant("<FLAG_KEY>");
if (variant.is("on")) {
    // Flag is on
} else {
    // Flag is off
}

Variant variant = experiment.variant("<FLAG_KEY>");
if (variant.is("on") && variant.payload != null) {
    try {
        String value = ((JSONObject) variant.payload).getString("key");
    } catch (Exception e) {
        e.printStackTrace();
    }
}

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

Variant variant = experiment.variant("<FLAG_KEY>", new Variant("control"));
if (variant.is("control")) {
    // Control
} else if (variant.is("treatment")) {
    // Treatment
}

すべて

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

fun all(): Map<String, Variant>

experiment.all();

クリア

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

fun clear()

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

experiment.clear();

エクスポージャー

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

fun exposure(key: String)

Variant variant = experiment.variant("<FLAG_KEY>");
// Do other things...
experiment.exposure("<FLAG_KEY>");
if (variant.is("control")) {
    // Control
} else if (variant.is("treatment")) {
    // Treatment
}

プロバイダー

プロバイダーの実装により、ユーザー ID の管理やエクスポージャー イベントの追跡が容易になるため、開発者のエクスペリエンスがより合理化されます。

ユーザープロバイダー

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

interface ExperimentUserProvider {
    fun getUser(): ExperimentUser
}

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

ExperimentConfig config = ExperimentConfig.builder()
    .userProvider(new CustomUserProvider())
    .build();
ExperimentClient experiment = Experiment.initialize(
    context, "<DEPLOYMENT_KEY>", config);

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

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

interface ExposureTrackingProvider {
    fun track(exposure: Exposure)
}

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

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

ExperimentConfig config = ExperimentConfig.builder()
    .exposureTrackingProvider(new CustomExposureTrackingProvider())
    .build();
ExperimentClient experiment = Experiment.initialize(
    context, "<DEPLOYMENT_KEY>", config);

ブートストラップ

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

ブートストラップのバリアント

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

let config = ExperimentConfigBuilder()
    .initialVariants(["<FLAG_KEY>": Variant("<VARIANT>")])
    .source(Source.InitialVariants)
    .build()
let experiment = Experiment.initialize(apiKey: "<DEPLOYMENT_KEY>", config: config)

ExperimentConfig config = ExperimentConfig.builder()
    .initialVariants(Map.of("<FLAG_KEY>", new Variant("<VARIANT>")))
    .source(Source.INITIAL_VARIANTS)
    .build();
ExperimentClient experiment = Experiment.initialize(
    context, "<DEPLOYMENT_KEY>", config);

ブートストラップフラグの設定

initialFlags 設定により、ローカル評価フラグ設定の初期セットを使用して SDK をブートストラップすることを選択できます。実験は、startまたはfetchを使用して更新されたフラグ設定やvariantをロードしない限り、variantを呼び出すときにこれらを評価します。

初期フラグをダウンロードするには、評価フラグAPIを使用してください

let config = ExperimentConfigBuilder()
    .initialFlags("<FLAGS_JSON>")
    .build()
let experiment = Experiment.initialize(apiKey: "<DEPLOYMENT_KEY>", config: config)

ExperimentConfig config = ExperimentConfig.builder()
    .initialFlags("<FLAGS_JSON>")
    .build();
ExperimentClient experiment = Experiment.initialize(
    context, "<DEPLOYMENT_KEY>", config);

カスタムログ記録

logLevel設定を使用してログの冗長性を制御するか、独自のロガーを統合するためのLoggerProviderインターフェイスを実装してください。

ログレベル

• LogLevel.DISABLE - ログはありません。
• LogLevel.ERROR - エラーのみ（デフォルト）。
• LogLevel.WARN - エラーと警告。
• LogLevel.INFO - エラー、警告、および情報。
• LogLevel.DEBUG - エラー、警告、情報、およびデバッグ。
• LogLevel.VERBOSE - 詳細な内容を含むすべてのメッセージ。

// Set log level to debug
val experiment = Experiment.initialize(
    context,
    "<DEPLOYMENT_KEY>",
    ExperimentConfig.builder()
        .logLevel(LogLevel.DEBUG)
        .build()
)

カスタムロガー

独自のロギングソリューションを使用できるようにLoggerProviderインターフェイスを実装してください。

// Implement the LoggerProvider interface
class CustomLoggerProvider : LoggerProvider {
    override fun verbose(msg: String) {
        // Send verbose logs to your logging service
        myLoggingService.verbose(msg)
    }
    override fun debug(msg: String) {
        myLoggingService.debug(msg)
    }
    override fun info(msg: String) {
        myLoggingService.info(msg)
    }
    override fun warn(msg: String) {
        myLoggingService.warn(msg)
    }
    override fun error(msg: String) {
        myLoggingService.error(msg)
    }
}
// Initialize with custom logger
val experiment = Experiment.initialize(
    context,
    "<DEPLOYMENT_KEY>",
    ExperimentConfig.builder()
        .loggerProvider(CustomLoggerProvider())
        .logLevel(LogLevel.WARN)
        .build()
)

デバッグフラグ （非推奨）

このdebug設定フラグは非推奨です。 代わりにlogLevelを使用してください。

// Deprecated: Sets logLevel to Debug
val experiment = Experiment.initialize(
    context,
    "<DEPLOYMENT_KEY>",
    ExperimentConfig.builder()
        .debug(true)
        .build()
)
// Preferred: Use logLevel instead
val experiment = Experiment.initialize(
    context,
    "<DEPLOYMENT_KEY>",
    ExperimentConfig.builder()
        .logLevel(LogLevel.DEBUG)
        .build()
)