実験 Go SDK

gomodvv1.13.1

Amplitude ExperimentのサーバーサイドGo SDK実装に関する公式ドキュメント。

このドキュメントは、リモートとローカルでの評価用に2つのセクションに分かれています。

リモート評価

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

インストール

go getを使用してGo Server SDKをインストールします。

bash

go get github.com/amplitude/experiment-go-server

クイックスタート

実験用クライアントを初期化する
ユーザーのバリアントを取得
フラグのバリアントにアクセスする

// (1) Initialize the local evaluation client with a server deployment key.
client := remote.Initialize("<DEPLOYMENT_KEY>", nil)
// (2) Fetch variants for a user
user := &experiment.User{
  UserId:   "user@company.com",
  DeviceId: "abcdefg",
  UserProperties: map[string]interface{}{
    "premium": true,
  },
}
variants, err := client.Fetch(user)
if err != nil {
  // Handle error
}
// (3) Access a flag's variant
variant := variants["<FLAG_KEY>"]
if variant.Value == "on" {
    // Flag is on
} else {
    // Flag is off
}

初期化する

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

func Initialize(apiKey string, config *Config) *Client

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

client := remote.Initialize("<DEPLOYMENT_KEY>", nil)

設定

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

EUデータセンター

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

名前	概要	デフォルト値
`Debug`	`true`に設定すると、デバッグログが有効になります。	`false`
`LogLevel`	出力する最小ログレベル。オプション：`Verbose`、`Debug`、`Info`、`Warn`、`Error`、`Disable`。カスタムログに移動します。	`Error`
`LoggerProvider`	カスタムロガーの実装。使用しているログソリューションと統合するため、`LoggerProvider`インターフェースを実装します。カスタムログに移動します。	`defaultLoggerProvider`これはstdoutに出力します
`ServerZone`	使用するAmplitudeデータセンター。 `USServerZone`または`EUServerZone`のいずれかです。	`USServerZone`
`ServerUrl`	フラグ設定を取得するホスト。	`https://api.lab.amplitude.com`
`FlagConfigPollingInterval`	バリアントを取得するためのタイムアウト（ミリ秒単位）。このタイムアウトは最初のリクエストにのみ適用され、その後の再試行には適用されません。	`500 * time.Millisecond`
`RetryBackoff.FetchRetries`	バリアントを取得するリクエストが失敗した場合に試行するリトライ回数。	`1`
`RetryBackoff.FetchRetryBackoffMin`	バリアント取得リクエストが失敗した後の最小（初期）バックオフです。 SDKは、この遅延を`RetryBackoff.FetchRetryBackoffScalar`でスケーリングします。	`0`
`RetryBackoff.FetchRetryBackoffMax`	再試行間の最大バックオフ値。スケール済みバックオフが最大値よりも大きくなった場合、SDK はその後のすべてのリクエストに対して最大値を使用します	`10 * time.Second`
`RetryBackoff.FetchRetryBackoffScalar`	最小バックオフを指数関数的にスケールします。	`1`
`RetryBackoff.FetchRetryTimeout`	バリアント取得を再試行するためのリクエストタイムアウトです。	`500 * time.Millisecond`

取得

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

func (c *Client) Fetch(user *experiment.User) (map[string]experiment.Variant, error)

パラメータ	要件	概要
`user`	必須	バリアントを取得する対象のユーザーです。

user := &experiment.User{
    UserId:   "user@company.com",
    DeviceId: "abcdefg",
    UserProperties: map[string]interface{}{
        "premium": true,
    },
}
variants, err := client.Fetch(user)
if err != nil {
    // Handle error
}

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

variant := variants["<FLAG_KEY>"]
if variant.Value == "on" {
    // Flag is on
} else {
    // Flag is off
}

オプション付きでV2を取得する

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

func (c *Client) FetchV2WithOptions(user *experiment.User, fetchOptions *experiment.FetchOptions) (map[string]experiment.Variant, error)

パラメータ	要件	概要
`user`	必須	バリアントを取得する対象のユーザーです。
`fetchOptions`	オプション	フェッチ要求のオプションです。 `nil`の場合、はサーバーのデフォルト動作を使用します（割り当てを追跡し、露出は追跡しない）。

user := &experiment.User{
    UserId:   "user@company.com",
    DeviceId: "abcdefg",
    UserProperties: map[string]interface{}{
        "premium": true,
    },
}
variants, err := client.FetchV2WithOptions(user, &experiment.FetchOptions{
    TracksAssignment: true,
    TracksExposure:   true,
})
if err != nil {
    // Handle error
}

FetchOptions

名前	概要	デフォルト値
`TracksExposure`	`true`の場合、SDKは取得されたバリアントの露出イベントを追跡します。	`false`
`TracksAssignment`	`true`の場合、SDK は取得されたバリアントの割り当てイベントを追跡します。	`true`

ローカル評価

ローカル評価を通じてユーザーのバリアントを評価することを実装します。ローカル評価を使用する予定がある場合は、そのトレードオフを理解しておく必要があります。

インストール

go getを使用してGo Server SDKをインストールします。

bash

go get github.com/amplitude/experiment-go-server

クイックスタート

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

// (1) Initialize the local evaluation client with a server deployment key.
client := local.Initialize("<DEPLOYMENT_KEY>", &local.Config{
 // (Recommended) Enable local evaluation cohort targeting.
 CohortSyncConfig: &local.CohortSyncConfig {
   ApiKey: "<API_KEY>",
   SecretKey: "<SECRET_KEY>"
 }
})
// (2) Start the local evaluation client.
err := client.Start()
if err != nil {
  panic(err)
}
  // (3) Evaluate a user.
user := &experiment.User{DeviceId: "abcdefg"}
variants, err := client.EvaluateV2(user, nil)
if err != nil {
  panic(err)
}

初期化する

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

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

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

func Initialize(apiKey string, config *Config) *Client

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

フラグストリーミング

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

設定

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

EUデータセンター

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

設定

名前	概要	デフォルト値
`Debug`	`true`に設定すると、デバッグログが有効になります。	`false`
`LogLevel`	出力する最小ログレベル。オプション：`Verbose`、`Debug`、`Info`、`Warn`、`Error`、`Disable`。カスタムログに移動します。	`Error`
`LoggerProvider`	カスタムロガーの実装。使用しているログソリューションと統合するため、`LoggerProvider`インターフェースを実装します。カスタムログに移動します。	`defaultLoggerProvider`これはstdoutに出力します
`ServerZone`	使用するAmplitudeデータセンター。 `USServerZone`または`EUServerZone`のいずれかです。	`USServerZone`
`ServerUrl`	フラグ設定を取得するホスト。	`https://api.lab.amplitude.com`
`FlagConfigPollingInterval`	`Start()`の呼び出し後に更新されたフラグ設定をポーリングする間隔	`30 * time.Second`
`FlagConfigPollerRequestTimeout`	フラグ設定ポーラーによる要求のタイムアウト	`10 * time.Second`
`AssignmentConfig`	廃止されました。評価後に割り当てイベントを自動的に追跡するための設定。	`nil`
`ExposureConfig`	評価後に曝露イベントを追跡するための設定。	`nil`
`StreamUpdates`	ストリーミングを有効にすると、フラグ設定の更新を受信するためのポーリングに代わることができます。 Amplitudeサーバーは毎秒ポーリングを行う代わりに、SDKにアップデートをプッシュします。通常は1秒以内です。何らかの理由でストリームに障害が発生した場合は、自動的にポーリングに戻り、一定の間隔を置いてストリーミングを再試行します。	`false`
`StreamServerUrl`	ストリームサーバーの URL。	`https://stream.lab.amplitude.com`
`StreamFlagConnTimeout`	有効なフラグ設定ストリームを確立するためのタイムアウト値です。これには、ストリームサーバーへの接続を確立するための時間と、初期フラグ設定を受信するための時間が含まれます。	`1500`
`CohortSyncConfig`	ローカル評価コホートターゲティングのために、コホートのダウンロードを有効にする設定。	`nil`

AssignmentConfig

名前	概要	デフォルト値
`CacheCapacity`	割り当てキャッシュに保存される割り当ての最大数	`524288`
`Config`	アサインメントイベントの追跡に使用される基盤となるAmplitude Analytics SDKを設定するためのオプション

ExposureConfig

名前	概要	デフォルト値
`CacheCapacity`	露出キャッシュに保存される露出の最大数	`524288`
`Config`	露出イベントの追跡に使用される基盤となるAmplitude Analytics SDKを設定するためのオプション

CohortSyncConfig

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

スタート

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

func (c *Client) Start() error

Evaluate()を呼び出す前に、Start()の結果を待ってフラグ設定の準備が完了していることを確認してください。

err := client.Start()
if err != nil {
    panic(err)
}

評価する

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

露出の追跡

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

func (c *Client) EvaluateV2(user *experiment.User, flagKeys []string) (map[string]experiment.Variant, error)

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

// The user to evaluate
user := &experiment.User{DeviceId: "abcdefg"}
// Evaluate all flag variants
allVariants, err := client.EvaluateV2(user, nil)
if err != nil {
    // Handle Error
}
// Evaluate a specific subset of flag variants
specificVariants, err := client.EvaluateV2(user, []string{
    "<FLAG_KEY_1>",
    "<FLAG_KEY_2>",
})
// Access a variant
variant := allVariants["<FLAG_KEY>"]
if variant.Value == "on" {
    // Flag is on
} else {
    // Flag is off
}

オプションを使用してV2を評価する

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

func (c *Client) EvaluateV2WithOptions(user *experiment.User, options *EvaluateOptions) (map[string]experiment.Variant, error)

パラメータ	要件	概要
`user`	必須	評価対象のユーザー。
`options`	オプション	評価のためのオプションです。

user := &experiment.User{DeviceId: "abcdefg"}
variants, err := client.EvaluateV2WithOptions(user, &local.EvaluateOptions{
    FlagKeys: []string{"flag-key-1", "flag-key-2"},
    TracksExposure: true,
})
if err != nil {
    // Handle Error
}

EvaluateOptions

名前	概要	デフォルト値
`FlagKeys`	評価すべき特定のフラグまたは実験。 nil または空の場合、SDK はすべてのフラグと実験を評価します。	`nil`
`TracksExposure`	`true`の場合、SDKは評価されたバリアントの露出イベントを追跡します。	`false`

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

1.7.0バージョン以降、ローカル評価SDKクライアントは、ローカル評価ターゲット設定用のコホートのダウンロードをサポートしています。このサポートを有効にするには、初期化時にアナリティクスApiKeyおよびSecretKeyでCohortSyncConfigオプションを設定する必要があります。

client := local.Initialize("<DEPLOYMENT_KEY>", &local.Config{
  // (Recommended) Enable local evaluation cohort targeting.
  CohortSyncConfig: &local.CohortSyncConfig {
    ApiKey: "<API_KEY>",
    SecretKey: "<SECRET_KEY>"
  }
})

カスタムログ記録

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

ログレベル

SDK は次のログレベルをサポートしています。

Verbose: ディープデバッグのための詳細なログ記録
Debug: 開発とトラブルシューティングのためのログ記録
Info：一般的な情報メッセージ
Warn：警告メッセージ
Error：エラーメッセージ（デフォルト）
Disable：ログ記録なし

カスタムロガー

使用しているログソリューションと統合するため、LoggerProviderインターフェースを実装します。

import "github.com/amplitude/experiment-go-server/logger"
type MyCustomLogger struct {
    // Your logger implementation
}
func (l *MyCustomLogger) Verbose(message string, args ...interface{}) {
    // Implement verbose logging
}
func (l *MyCustomLogger) Debug(message string, args ...interface{}) {
    // Implement debug logging
}
func (l *MyCustomLogger) Info(message string, args ...interface{}) {
    // Implement info logging
}
func (l *MyCustomLogger) Warn(message string, args ...interface{}) {
    // Implement warn logging
}
func (l *MyCustomLogger) Error(message string, args ...interface{}) {
    // Implement error logging
}
// Initialize with custom logger
client := local.Initialize("<DEPLOYMENT_KEY>", &local.Config{
    LogLevel: logger.Debug,
    LoggerProvider: &MyCustomLogger{},
})

下位互換性

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

Was this helpful?

実験 Go SDK

リモート評価

インストール

初期化する

設定

取得

アカウントレベルのバケット化分析（v1.7.0以降）

オプション付きでV2を取得する

ローカル評価

インストール

初期化する

設定

スタート

評価する

オプションを使用してV2を評価する

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

カスタムログ記録

ログレベル

カスタムロガー