Experiment JVM SDK

mavenv1.8.3

Amplitude ExperimentのサーバーサイドJVM SDK実装に関する公式ドキュメントです。このSDKは、JavaまたはKotlinのサーバー側実装のいずれかで使用できます。

このドキュメントでは、リモート評価とローカル評価について別々のセクションで説明しています。

リモート評価

リモート評価を使用してユーザーのバリアントを取得する機能を実装しています。

インストール

Gradle を使用して JVM Server SDK をインストールします。

implementation "com.amplitude:experiment-jvm-server:<VERSION>"

リモートの初期化

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

fun initializeRemote(
    apiKey: String,
    config: RemoteEvaluationConfig = RemoteEvaluationConfig()
): RemoteEvaluationClient

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

val experiment = Experiment.initializeRemote("<DEPLOYMENT_KEY>")

設定

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

EUデータセンター

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

名前	概要	デフォルト値
`debug`	`true`に設定すると、デバッグログが有効になります。	`false`
`logLevel`	出力する最小ログレベル。オプション：`VERBOSE`、`DEBUG`、`INFO`、`WARN`、`ERROR`、`DISABLE`。カスタムログに移動します。	`ERROR`
`loggerProvider`	カスタムロガーの実装。使用しているログソリューションと統合するため、`LoggerProvider`インターフェースを実装します。カスタムログに移動します。	`DefaultLogger`これはstdoutに出力します
`serverZone`	使用するAmplitudeデータセンター。 `ServerZone.US`または`ServerZone.EU`のいずれかです。	`ServerZone.US`
`serverUrl`	フラグ設定を取得するホスト。	`https://api.lab.amplitude.com`
`fetchTimeoutMillis`	バリアントを取得するためのタイムアウト（ミリ秒単位）。	`500`
`fetchRetries`	バリアントを取得するリクエストが失敗した場合に試行するリトライ回数。	`1`
`fetchRetryBackoffMinMillis`	バリアント取得リクエストが失敗した後の最小（初期）バックオフです。 SDKは、この遅延を`fetchRetryBackoffScalar`でスケーリングします。	`0`
`fetchRetryBackoffMaxMillis`	再試行間の最大バックオフ値。スケール済みバックオフが最大値よりも大きくなった場合、SDK はその後のすべてのリクエストに対して最大値を使用します	`10000`
`fetchRetryBackoffScalar`	最小バックオフを指数関数的にスケールします。	`1`

CohortSyncConfig

名前	概要	デフォルト値
`apiKey`	実験デプロイメントキーではなく、アナリティクスAPIキー	必須
`secretKey`	アナリティクスの秘密鍵	必須
`maxCohortSize`	SDKがダウンロードするコホートの最大サイズです。このサイズより大きいコホートはダウンロードされません。	`2147483647`
`cohortPollingIntervalMillis`	コホート更新についてAmplitudeをポーリングするミリ秒単位での間隔（最小値は60,000）。	`60000`
`cohortServerUrl`	コホートデータを取得するコホートサーバーのエンドポイント。 EUのデータセンターにアクセスするには、`serverZone`を`ServerZone.EU`に設定します。この値を設定すると、デフォルト値が`serverZone`上書きされます。	`https://cohort-v2.lab.amplitude.com`

取得

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

fun fetch(user: ExperimentUser, fetchOptions: FetchOptions? = null): CompletableFuture<Map<String, Variant>>

パラメータ	要件	概要
`user`	必須	バリアントを取得する対象のユーザーです。
`fetchOptions`	オプション	フェッチ要求のオプションです。

FetchOptions

名前	概要	デフォルト値
`tracksExposure`	このフェッチ要求のエクスポージャーイベントを追跡するかどうかを指定します。`null`の場合、サーバーのデフォルト動作を使用します（露出の追跡なし）。	`null`
`tracksAssignment`	このフェッチ要求の割り当てイベントを追跡するかどうかを指定します。 `null`の場合、サーバーのデフォルト動作を使用します（割り当ての追跡あり）。	`null`

val user = ExperimentUser.builder()
    .userId("user@company.com")
    .deviceId("abcdefg")
    .userProperty("premium", true)
    .build()
val variants = try {
    experiment.fetch(user).get()
} catch (e: Exception) {
    e.printStackTrace()
    return
}

ユーザーのバリアントを取得した後、特定のフラグのバリアントにアクセスできます。

val variant = variants["<FLAG_KEY>"]
if (variant?.value == "on") {
    // Flag is on
} else {
    // Flag is off
}

ローカル評価

ローカル評価を使用して、ユーザーのバリアント評価を実装します。ローカル評価を使用する予定がある場合は、そのトレードオフを理解してください。

インストール

MavenまたはGradleを使用してJVM Server SDKをインストールします。

implementation "com.amplitude:experiment-jvm-server:<VERSION>"

クイックスタート

ローカル評価クライアントを初期化します。
ローカル評価クライアントを起動します。
ユーザーを評価します。

// (1) Initialize the local evaluation client with a server deployment key.
val experiment = Experiment.initializeLocal(
    "<DEPLOYMENT_KEY>",
    // (Recommended) Enable local evaluation cohort targeting.
    LocalEvaluationConfig.builder()
        .cohortSyncConfig(CohortSyncConfig("<API_KEY>", "<SECRET_KEY>"))
        .build()
)
// (2) Start the local evaluation client.
experiment.start()
// (3) Evaluate a user.
val user = ExperimentUser.builder()
    .userId("user@company.com")
    .deviceId("abcdefg")
    .userProperty("premium", true)
    .build()
val variants = experiment.evaluate(user)

ローカルを初期化する

ローカル評価クライアントを初期化します。

サーバーデプロイメントキー

ローカル評価フラグ設定にアクセスするには、サーバーデプロイメントキーを使用してローカル評価クライアントを初期化する必要があります。

fun initializeLocal(
    apiKey: String,
    config: LocalEvaluationConfig = LocalEvaluationConfig(),
): LocalEvaluationClient

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

フラグストリーミング

streamUpdatesの設定を使用すると、flagConfigPollingIntervalMillisミリ秒ごとにポーリングするのではなく、フラグ設定の更新をSDKにプッシュできます（デフォルトはfalse）。保存後にSDKが更新を受信するまでの時間は、通常1秒未満です。ストリーミングに失敗した場合、SDKはポーリングに戻ります。フラグ設定の変更が反映されるまでの時間（デフォルトは30秒）とフォールバックの動作を指定するには、flagConfigPollingIntervalMillisの設定を構成します。

設定

SDKクライアントは初期化時に設定できます。

EUデータセンター

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

LocalEvaluationConfig

名前	概要	デフォルト値
`debug`	`true`に設定すると、デバッグログが有効になります。	`false`
`logLevel`	出力する最小ログレベル。オプション：`VERBOSE`、`DEBUG`、`INFO`、`WARN`、`ERROR`、`DISABLE`。カスタムログに移動します。	`ERROR`
`loggerProvider`	カスタムロガーの実装。使用しているログソリューションと統合するため、`LoggerProvider`インターフェースを実装します。カスタムログに移動します。	`DefaultLogger`これはstdoutに出力します
`serverZone`	使用するAmplitudeデータセンター。 `ServerZone.US`または`ServerZone.EU`のいずれかです。	`ServerZone.US`
`serverUrl`	フラグ設定を取得するホスト。	`https://api.lab.amplitude.com`
`flagConfigPollingIntervalMillis`	`Start()`の呼び出し後に更新されたフラグ設定をポーリングする間隔	`30000`
`flagConfigPollerRequestTimeoutMillis`	フラグ設定ポーラーによる要求のタイムアウト	`10000`
`assignmentConfiguration`	廃止されました。ローカル評価の自動割り当て追跡を有効にします。	`null`
`exposureConfiguration`	ローカル評価における露出追跡を有効にします。	`null`
`streamUpdates`	ストリーミングを有効にすると、フラグ設定の更新を受信するためのポーリングに代わることができます。 Amplitudeサーバーは、毎秒ポーリングを行うのではなく、通常1秒以内にSDKにアップデートをプッシュします。何らかの理由でストリームに障害が発生した場合は、自動的にポーリングに戻り、一定の間隔を置いてストリーミングを再試行します。	`false`
`streamServerUrl`	ストリームサーバーの URL。	`https://stream.lab.amplitude.com`
`streamFlagConnTimeoutMillis`	有効なフラグ設定ストリームを確立するためのタイムアウト値です。これには、ストリームサーバーへの接続を確立するための時間と、初期フラグ設定を受信するための時間が含まれます。	`1500`
`cohortSyncConfig`	ローカル評価コホートターゲティングのために、コホートのダウンロードを有効にする設定。	`null`

割り当て設定

名前	概要	デフォルト値
`api_key`	実験デプロイメントキーではなく、アナリティクスAPIキー	必須
`cache_capacity`	割り当てキャッシュに保存される割り当ての最大数	`65536`
`eventUploadThreshold`	`setEventUploadThreshold()` 基盤となるアナリティクスSDK内で	`10`
`eventUploadPeriodMillis`	`setEventUploadPeriodMillis()` 基盤となるアナリティクスSDK内で	`10000`
`useBatchMode`	`useBatchMode()` 基盤となるアナリティクスSDK内で	`true`

ExposureConfiguration

名前	概要	デフォルト値
`api_key`	実験デプロイメントキーではなく、アナリティクスAPIキー	必須
`cache_capacity`	露出キャッシュに保存される露出の最大数	`65536`
`eventUploadThreshold`	`setEventUploadThreshold()` 基盤となるアナリティクスSDK内で	`10`
`eventUploadPeriodMillis`	`setEventUploadPeriodMillis()` 基盤となるアナリティクスSDK内で	`10000`
`useBatchMode`	`useBatchMode()` 基盤となるアナリティクスSDK内で	`true`

CohortSyncConfig

名前	概要	デフォルト値
`apiKey`	実験デプロイメントキーではなく、アナリティクスAPIキー	必須
`secretKey`	アナリティクスの秘密鍵	必須
`maxCohortSize`	SDKがダウンロードするコホートの最大サイズです。このサイズより大きいコホートはダウンロードされません。	`2147483647`
`cohortPollingIntervalMillis`	コホート更新についてAmplitudeをポーリングするミリ秒単位での間隔（最小値は60,000）。	`60000`

スタート

ローカル評価クライアントを起動し、評価用のローカル評価モードのフラグ設定を事前に取得し、設定された間隔でフラグ設定ポーラーを開始します。

fun start()

evaluate()を呼び出す前にstart()が戻るまで待機し、フラグ設定を評価時に確実に使用できるようにします。

停止

ローカル評価クライアントをシャットダウンし、フラグ設定とコホートを更新するためのバックグラウンドプロセスを停止します。

fun stop()

評価する

start()で事前に取得されたフラグを使用して、評価ロジックを実行します。ユーザーオブジェクト引数にevaluateを指定する必要があります。フラグバリアントの特定のサブセットのみが必要な場合は、オプションでフラグキーの配列を渡すことができます。

露出の追跡

露出の追跡を有効にするためにexposureConfigurationを設定します。次に、evaluate()を呼び出す際に、EvaluateOptionsの内のtracksExposureをtrueに設定します。

fun evaluate(user: ExperimentUser, flagKeys: List<String> = listOf(), evaluateOptions: EvaluateOptions? = null): Map<String, Variant>

パラメータ	要件	概要
`user`	必須	評価対象のユーザー。
`flagKeys`	オプション	評価すべき特定のフラグまたは実験。空の場合、SDKはすべてのフラグと実験を評価します。
`evaluateOptions`	オプション	評価リクエストのオプション。

// The user to evaluate
val user = ExperimentUser.builder()
    .userId("user@company.com")
    .deviceId("abcdefg")
    .userProperty("premium", true)
    .build()
// Evaluate all flag variants
val allVariants = experiment.evaluate(user)
// Evaluate a specific subset of flag variants
val specificVariants = experiment.evaluate(user, listOf(
    "<FLAG_KEY_1>",
    "<FLAG_KEY_2>",
))
// Access a variant
val variant = allVariants["<FLAG_KEY>"]
if (variant?.value == "on") {
    // Flag is on
} else {
    // Flag is off
}

EvaluateOptions

名前	概要	デフォルト値
`tracksExposure`	`true`の場合、SDKは評価されたバリアントの露出イベントを追跡します。	`false`

ローカル評価コホートターゲティング

1.4.0バージョン以降、ローカル評価SDKクライアントは、ローカル評価ターゲット設定用のコホートのダウンロードをサポートしています。このサポートを有効にするには、初期化時にアナリティクスapiKeyとsecretKeyを指定したcohortSyncConfigを使用してSDKを設定します。

val experiment = Experiment.initializeLocal(
    "<DEPLOYMENT_KEY>",
    // (Recommended) Enable local evaluation cohort targeting.
    LocalEvaluationConfig.builder()
        .cohortSyncConfig(CohortSyncConfig("<API_KEY>", "<SECRET_KEY>"))
        .build()
)

カスタムログ記録

ログの冗長性を調整するようにlogLevel設定を設定するか、独自のロガーを使用するようにLoggerProviderインターフェースを実装します。

ログレベル

VERBOSE：詳細なデバッグログ
DEBUG：開発およびトラブルシューティング用ログ
INFO：一般情報
WARN：警告
ERROR: エラーのみ (デフォルト)
DISABLE：ログなし

カスタムロガー

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

import com.amplitude.experiment.util.LogLevel
import com.amplitude.experiment.util.LoggerProvider
class MyCustomLogger : LoggerProvider {
    override fun verbose(msg: String) {
        // Implement verbose logging
    }
    override fun debug(msg: String) {
        // Implement debug logging
    }
    override fun info(msg: String) {
        // Implement info logging
    }
    override fun warn(msg: String) {
        // Implement warn logging
    }
    override fun error(msg: String) {
        // Implement error logging
    }
}
// Initialize with custom logger
val experiment = Experiment.initializeLocal(
    "<DEPLOYMENT_KEY>",
    LocalEvaluationConfig.builder()
        .logLevel(LogLevel.DEBUG)
        .loggerProvider(MyCustomLogger())
        .build()
)

下位互換性

debug設定フィールドは引き続きサポートされています。trueに設定されている場合、logLevelはDEBUGに上書きされます。

Was this helpful?

Experiment JVM SDK

リモート評価

インストール

クイックスタート

リモートの初期化

設定

取得

ローカル評価

インストール

ローカルを初期化する

設定

スタート

停止

評価する

アカウントレベルのバケット設定と分析（v1.3.0以降

ローカル評価コホートターゲティング

カスタムログ記録

ログレベル

カスタムロガー