実験 iOS SDK

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

インストール

pod 'AmplitudeExperiment', '~> <VERSION>'

// (1) Initialize the experiment client with Amplitude Analytics
let experiment = Experiment.initializeWithAmplitudeAnalytics(
    apiKey: "DEPLOYMENT_KEY",
    config: ExperimentConfigBuilder().build()
)
// (2) Fetch variants
experiment.fetch(user: nil) { _, error in
    // (3) Lookup a flag's variant
    let variant = experiment.variant("FLAG_KEY")
    if variant.value == "on" {
        // Flag is on
    } else {
        // Flag is off
    }
}

初期化する

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

func initializeWithAmplitudeAnalytics(
    apiKey: String,
    config: ExperimentConfig
) -> ExperimentClient

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

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

let experiment = Experiment.initializeWithAmplitudeAnalytics(
    apiKey: "DEPLOYMENT_KEY",
    config: ExperimentConfigBuilder()
    .instanceName("myCustomInstance")  // case-sensitive name matching your Analytics instance
    .build()
)

設定

初期化時にSDKクライアントを設定します。

統合

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

取得

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

func fetch(user: ExperimentUser?, options: FetchOptions?, completion: ((ExperimentClient, Error?) -> Void)?)

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

let user = ExperimentUserBuilder()
    .userId("user@company.com")
    .userProperty("premium", value: true)
    .build()
experiment.fetch(user: user) { experiment, error in
    // Do something...
}

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

experiment.fetch(user: nil, completion: nil)

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

スタート

サーバーからフラグ設定を取得し、ユーザーのリモート評価バリアントを取得することにより、SDK を起動します。 完了コールバックが実行されると、SDK は準備が整います。

func start(_ user: ExperimentUser? = nil, completion: ((Error?) -> Void)? = nil)

ユーザー情報を利用してバリアントを評価または取得できるようになった後、アプリケーションの初期化時にstart()を呼び出します。完了ブロックは、SDK がローカル評価フラグ設定をロードし、リモート評価バリアントを取得した後に実行されます。

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

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

experiment.start() { error in
    // SDK Started
}

バリアント

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

func variant(_ key: String, fallback: Variant? = nil) -> Variant

ユーザーがどのバリアントに振り分けられたかを判断する際は、バリアント value を既知の文字列と比較することになります。

let variant = experiment.variant("<FLAG_KEY>")
if variant.value == "on" {
    // Flag is on
} else {
    // Flag is off
}

let variant = client.variant("<FLAG_KEY>")
if variant.value == "on" {
    if let payload = variant.payload as? [String:String] {
        let value = payload["key"]
    }
}

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

let variant = experiment.variant("<FLAG_KEY>", fallback: Variant("control"))
if variant.value == "control" {
    // Control
} else if variant.value == "treatment" {
    // Treatment
}

すべて

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

func all() -> [String:Variant]

クリア

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

func clear()

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

experiment.clear()

現在のユーザー

以降のfetch()およびstart()呼び出しで、クライアントが使用するユーザーを設定するか、クライアントに現在設定されているユーザーを取得します。

experiment.setUser(ExperimentUserBuilder()
    .userId("user@company.com")
    .deviceId("abcdefg")
    .build()
)
let currentUser = experiment.getUser()

空でないユーザーを直接 fetch() に渡すと、そのユーザーもクライアント上に設定されます。

停止

startによって開始されたローカル評価フラグのポーリングを停止します。 これにより、クライアントによってすでに保存されているバリアントは消去されません。

experiment.stop()

エクスポージャー

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

func exposure(key: String)

let variant = experiment.variant("<FLAG_KEY>")
// Do other things...
experiment.exposure(key: "<FLAG_KEY>")
if variant.value == "control" {
    // Control
} else if variant.value == "treatment" {
    // Treatment
}

割り当ての追跡

後続のリモート評価リクエストを割り当て追跡対象としてマークするかどうかを制御します。 この設定は、設定済みの実験インスタンスに対して保存されます。

experiment.setTracksAssignment(false) // Send no-track on later fetch requests.

プロバイダー

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

ユーザープロバイダー

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

protocol ExperimentUserProvider {
    func getUser() -> ExperimentUser
}

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

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

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

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

protocol ExposureTrackingProvider {
    func track(exposure: Exposure)
}

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

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

ExperimentConfig config = ExperimentConfigBuilder()
    .exposureTrackingProvider(CustomExposureTrackingProvider(analytics))
    .build()
let experiment = Experiment.initialize(apiKey: "<DEPLOYMENT_KEY>", config: 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)

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

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

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

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

カスタムログ記録

logLevel設定を使用してログの詳細さを制御するか、独自のログソリューションを統合するためにCoreLoggerプロトコルを実装してください。

ログレベル

• .off - ログ記録なし
• .error - エラーのみ
• .warn - エラーと警告（デフォルト）
• .log - エラー、警告、およびログ
• .debug - デバッグを含むすべてのメッセージ

// Only log errors
let config = ExperimentConfigBuilder()
    .logLevel(.error)
    .build()
let experiment = Experiment.initialize(apiKey: "<DEPLOYMENT_KEY>", config: config)

カスタムロガー

独自のログソリューションを使用するためにCoreLoggerプロトコルを実装してください。

// Implement the CoreLogger protocol
class CustomLogger: CoreLogger {
    func error(message: String) {
        // Send error logs to your logging service
        myLoggingService.error(message)
    }
    func warn(message: String) {
        myLoggingService.warn(message)
    }
    func log(message: String) {
        myLoggingService.log(message)
    }
    func debug(message: String) {
        myLoggingService.debug(message)
    }
}
// Initialize with custom logger
let config = ExperimentConfigBuilder()
    .loggerProvider(CustomLogger())
    .logLevel(.warn)
    .build()
let experiment = Experiment.initialize(apiKey: "<DEPLOYMENT_KEY>", config: config)