実験Android SDK

Amplitude 実験のAndroid SDKは、バリアントを取得し、Androidアプリの機能フラグを評価します。

バージョン1.17.0では、分析プラグインとクライアント検索ヘルパーが追加されます。バージョン1.18.0では、プラグインに共有分析IDを使用しており、分析 Android 1.36.0以降が必要です。

Android

用Unified SDKをインストールすると、他のAmplitude製品(分析、セッションリプレイ)とともに実験 SDKにアクセスできます。Unified SDKは、すべてのAmplitude機能の単一エントリーポイントを提供し、すべてのコンポーネントの初期化と設定を処理することで連携プロセスを簡素化します。

インストール

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

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

クイックスタート

:分析 Kotlin の統合については、Amplitude アナリティクスプラグインを使用してください。このコールアウトの例では、コネクタベースのAmplitude連携とSegmentなどのサードパーティ製の分析について説明しています。1つの連携パスを選択します。

  1. 実験用クライアントを初期化する
  2. バリアントを取得
  3. フラグのバリアントにアクセスする
kotlin
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
        }
    }
}

Amplitude アナリティクス プラグイン

AmplitudeExperimentPluginを使用して、既存の分析 Kotlin SDKインスタンスに実験を追加します。com.amplitude:experiment-android-clientには、1.17.0以降のプラグインが含まれています。実験 1.18.0の場合は、com.amplitude:analytics-android:1.36.0または以降を使用します。

Unified SDK for Androidを使用している場合、Unified SDK はプラグインを登録します。 同じデプロイメントに別の実験プラグインを登録しないでください。

プラグインを使用してクライアントを作成します

アプリケーションのコンテキストとExperimentConfigをプラグインに渡します。 このプラグインはデフォルトで分析 APIキーを使用します。別の実験のデプロイメントを使用するには、そのデプロイメントキーを3番目のコンストラクタ引数として渡します。

import com.amplitude.android.Amplitude
import com.amplitude.android.AutocaptureOption
import com.amplitude.android.Configuration
import com.amplitude.experiment.AmplitudeExperimentPlugin
import com.amplitude.experiment.ExperimentConfig
import com.amplitude.experiment.experiment
val amplitude = Amplitude(Configuration(
    apiKey = "AMPLITUDE_API_KEY",
    context = applicationContext,
    autocapture = setOf(AutocaptureOption.SESSIONS),
))
val config = ExperimentConfig.builder()
    .automaticFetchOnAmplitudeIdentityChange(true)
    .build()
val plugin = AmplitudeExperimentPlugin(applicationContext, config)
amplitude.add(plugin)
// After plugin setup, access cached or locally evaluated variants.
val variant = amplitude.experiment?.variant("FLAG_KEY")

プラグインの登録は、最初のフェッチが完了するまで待機しません。 バリアントがロードされるまで、variant() はフォールバックを返すことができます。 インターフェイスで新しいリモートバリアントが必要な場合は、バックグラウンドスレッドに対するフェッチが完了するのを待ってから、レンダリングしてください。

プラグインは、作成するクライアントを管理します。

  • 分析がオプトアウトしていない限り、分析がデバイスIDとセッションIDを持っている場合に実験を開始します。
  • 分析のインスタンス名、サーバーゾーン、ユーザーID、デバイスID、およびユーザープロパティを使用します。このプラグインは、ユーザーとエクスポージャー追跡プロバイダーを提供します。
  • 分析を通じてエクスポージャーイベントを送信します。
  • automaticFetchOnAmplitudeIdentityChangeがtrueである場合のID変更に基づいて更新されたバリアントを取得します。デフォルトは false です。
  • オプトアウト時にフラグのポーリングを停止し、オプトイン時に実験を再起動します。 オプトアウトは、を通じたローカル評価を妨げるものではありませんvariant()。
  • 分析のリセット時にキャッシュされた割り当てをクリアし、プラグインのティアダウン時にポーリングを停止します。

実験1.18.0では、プラグインはユーザープロパティを分析のIDから直接読み取ります。空のプロパティマップは、以前のプロパティをクリアします。 自動フェッチでは、分析のアイデンティティコールバックを使用して、1つのID更新で重複したフェッチを避けます。

同じインスタンス名とAPIキーに対してExperiment.initialize()もまたはExperiment.initializeWithAmplitudeAnalytics()を呼び出さないでください。 これらの初期化子は、別のクライアントを作成し、フェッチ、ポーリング、エクスポージャー追跡を複製できます。

既存のクライアントをラップする

アプリケーションがすでに実験クライアントを管理している場合AmplitudeExperimentPlugin(existingClient)に使用します:

amplitude.add(AmplitudeExperimentPlugin(existingClient))

ラッピングを使用すると、既存のクライアントが分析経由で検出可能になります。アプリケーションは、その設定、開始と停止の呼び出し、ID、セッション、オプトアウト、リセットの処理に対する責任を保持します。 このプラグインはこれらの動作を変更しません。

登録済みのクライアントを検索します

Kotlinでは、正確に1つの実験プラグインが登録されている場合にクライアントを返します。 amplitude.experimentこの値は、プラグインが登録されていない場合、複数のプラグインが登録されている場合、またはプラグインの設定でクライアントがまだ作成されていない場合にnull返されます。Javaでは、ExperimentPluginHost.getExperiment(amplitude)を使用します。

複数のデプロイメントの場合は、プラグインの登録に使用されたデプロイメントキーを渡します:

val experiment = amplitude.experiment("DEPLOYMENT_KEY")

一致するクライアントが存在しない場合、キー付きルックアップは nullを返します。明示的なデプロイメントキーなしで分析 API キーを使用するプラグインの場合は、null を渡します。

初期化する

これらの初期設定子は、コネクタベースのAmplitude連携またはサードパーティ製分析に使用します。 AmplitudeExperimentPlugin によって作成されたクライアントの場合、プラグインが初期化を処理します。

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

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

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

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

設定

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

EUデータセンター

AmplitudeのEUデータセンターを使用している場合は、初期化時のserverZoneオプションを ServerZone.EUに設定してください。

統合

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

取得

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

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

Amplitude 実験は、ユーザーがアプリケーションセッションの最新のバリアントを取得できるように、アプリケーションの起動時に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);

ユーザーIDが変更されたときに取得

ユーザーの最新のバリアントを取得したい場合は、ユーザーの状態が意味のある方法で変化したときに必ずfetch()を呼び出すことをお勧めします。たとえば、ユーザーがログインしてユーザーIDを受け取った場合や、フラグや実験のターゲティングルールに影響を与える可能性のあるユーザープロパティを設定している場合などです。

ユーザープロパティの場合、Amplitudeはリモート評価の前にユーザーエンリッチメントに頼るのではなく、新しいユーザープロパティを明示的に渡すことを推奨していますfetch()。 別のシステムを介したリモートユーザープロパティ同期にはfetch()のタイミング保証がなく、競合状態が発生する可能性があります。

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

スタート

Fetch と start の比較

クライアント側のローカル評価を使用している場合は、start を使用してください。リモート評価のみを使用している場合は、start ではなく fetch を呼び出してください。

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

kotlin
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クライアントのローカルストアからフラグまたは実験のバリアントにアクセスします。

自動露出トラッキング

連携を使用する場合や、カスタム露出トラッキングプロバイダーを設定する場合、variant()はトラッキングプロバイダーを通じて露出イベントを追跡します。この機能を無効にするには、automaticExposureTracking を false に設定し、exposure() を使用して手動で露出を追跡します。

kotlin
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
}

バリアントのペイロードにアクセスします。

バリアントには、任意のデータの動的ペイロードも含めることができます。バリアントのvalueを確認した後、バリアントオブジェクトからpayloadフィールドにアクセスします。

Android 上の payload はタイプ Object (Any?) なので、ペイロードを想定したタイプにキャストする必要があります。JSON オブジェクトと配列のタイプをそれぞれ org.json.JSONObjectおよび org.json.JSONArrayとしてキャストします。

例えば、ペイロードが次の場合です{"key":"value"}。

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は、ユーザーに割り当てられたバリアントがないことを意味します。 組み込みのfallbackパラメータを使用して、ストアに指定されたフラグキーのバリアントが含まれていない場合に返されるバリアントを指定できます。

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

すべて

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

kotlin
fun all(): Map<String, Variant>
experiment.all();

クリア

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

kotlin
fun clear()

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

experiment.clear();

エクスポージャー

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

kotlin
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
}

プロバイダー

Integrations

実験 クライアント SDKと併せて Amplitude または Segment 分析 SDKを使用する場合、Amplitudeはカスタムプロバイダーを実装するのではなく、連携を使用することをお勧めします。

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

ユーザープロバイダー

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

kotlin
interface ExperimentUserProvider {
    fun getUser(): ExperimentUser
}

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

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

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

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

kotlin
interface ExposureTrackingProvider {
    fun track(exposure: Exposure)
}

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

カスタムユーザープロバイダーを使用するには、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クライアントは同じフラグに対して以前に取得および保存されたバリアントよりもブートストラップされたバリアントを優先します。

swift
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を使用してください

swift
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()
)

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

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.

このページでは