実験 JavaScript SDK
Amplitude 実験のクライアントサイドJavaScript SDK実装に関する公式ドキュメントです。
インストール
インストールする前に、連携サーフェスに適切なパッケージを選択してください:
| 連携 | パッケージ | メモ |
|---|---|---|
| 新しいブラウザ連携:分析、セッションリプレイ、機能実験 | @amplitude/unified (npm) | すべてのAmplitudeブラウザ製品の単一のエントリーポイント。機能実験が含まれます。 |
| 既存のBrowser SDK 2連携:機能実験を追加 | @amplitude/experiment-js-client (npm) | @amplitude/analytics-browserを保持し、Experiment.initializeWithAmplitudeAnalytics()で初期化します。 |
| ブラウザ:Feature Experimentのみ | @amplitude/experiment-js-client (npm) | 分析またはセッションリプレイのデータをAmplitudeに送信しない場合に使用します。エクスポージャートラッキングプロバイダーを設定します。 |
| サーバー | @amplitude/experiment-node-server (npm) | 実験 Node.js SDKを参照してください。 |
| Script Tag(CDN) | 個別@amplitude/experiment-js-clientに追加 | Unified Scriptにはウェブ実験が含まれますが、機能実験は含まれません。 このパッケージを機能実験用のUnified Scriptと一緒に追加します。 |
機能実験とウェブ実験
- Feature Experiment(
@amplitude/experiment-js-client):コードベースの機能フラグと、実行時に評価されるA/Bテスト。@amplitude/unifiednpmパッケージにはこれが含まれています。 Unified Script(CDN)にはこの値は含まれていません。 - Web Experiment (
@amplitude/experiment-tag):ウェブページで A/B テストを行うためのノーコードビジュアルエディタです。Unified Script(CDN)にはこれが含まれています。@amplitude/unifiednpmパッケージにはこの値は含まれていません。
詳細については、インストール方法別のプロダクトサポートを参照してください。
複数製品ブラウザ連携用 Unified SDK
新しいブラウザ連携を開始する予定で、Feature 実験と併用して分析とセッションリプレイが必要な場合、これらのパッケージを別々にインストールするのではなく、Browser Unified SDK (@amplitude/unified) をインストールしてください。同じページに@amplitude/unifiedおよび@amplitude/analytics-browserを読み込まないでください。1つを選択してください。
すでに @amplitude/analytics-browserを実行している場合、これと併用して @amplitude/experiment-js-clientを追加することはサポートされている設定です。Unified SDKに移行する必要はありません。
# New browser integration: Analytics + Session Replay + Feature Experiment
npm install @amplitude/unified
# Feature Experiment on its own, or alongside an existing @amplitude/analytics-browser integration
npm install --save @amplitude/experiment-js-client
クイックスタート
実験SDKを初期化する正しい方法は、Amplitude SDKをアナリティクスに使用しているか、サードパーティ(例:Segment)を使用しているかによって異なります。
import { Experiment } from '@amplitude/experiment-js-client';
// (1) Initialize the experiment client with Amplitude Analytics.
const experiment = Experiment.initializeWithAmplitudeAnalytics(
'DEPLOYMENT_KEY'
);
// (2) Fetch variants and await the promise result.
await experiment.fetch();
// (3) Lookup a flag's variant.
const variant = experiment.variant('FLAG_KEY');
if (variant.value === 'on') {
// Flag is on
} else {
// Flag is off
}
初期化する
スタートアップにアプリケーションでSDKを初期化します。apiKeyパラメータに渡すデプロイメントキー引数は、イベントの送信先である同じAmplitudeプロジェクト内に存在する必要があります。
initializeWithAmplitudeAnalytics(apiKey: string, config?: ExperimentConfig): ExperimentClient
| パラメータ | 概要 |
|---|---|
apikey | 必須です。 フェッチ要求を承認し、ユーザーに対してどのフラグを評価するかを決定するデプロイメントキー |
config | SDKクライアントの動作をカスタマイズするためのクライアント設定。 |
初期化子はシングルトンインスタンスを返すため、同じインスタンス名に対する後続の初期化は常に最初のインスタンスを返します。複数のインスタンスを作成するには、instanceName 設定を使用します。
import { Experiment } from '@amplitude/experiment-js-client';
const experiment = initializeWithAmplitudeAnalytics('DEPLOYMENT_KEY');
Angularアプリ
Zone.js を使用する Angular アプリでは、クライアントを初期化し、Angular ゾーンの外側(main.ts例:bootstrapApplication の前start()や fetch()の中など)で または NgZone.runOutsideAngularを呼び出します。start() の後、クライアントは、pollOnStart が有効true(デフォルト)である場合、繰り返しタイマーでフラグ設定の更新をポーリングします。Amplitude アナリティクス連携により、クライアントは露出イベントをフラッシュするための繰り返しタイマーも実行します。Angularゾーン内で開始される繰り返しタイマーは、アプリが安定した状態になるのを防ぎます。これは、AngularのデフォルトregisterWhenStable戦略によるサービスワーカーの登録など、安定した状態を待つすべての動作を遅延します。
variant() はクライアントのローカルストアから読み込み、ネットワークリクエストを一切行わないため、コンポーネントから呼び出すことができます。 ゾーンの外で開始されたfetch()promiseが解決されるときにコンポーネントがそのstateを更新する場合、NgZone.run内で更新を行い、Angularがchange detectionを実行するようにします。
設定
初期化時にSDKクライアントを設定します。
統合
AmplitudeまたはSegment アナリティクス SDKのいずれかを使用してAmplitudeへのイベントをトラッキングしている場合は、初期化時に連携を設定してください。連携はプロバイダーインターフェイスを自動的に実装し、ユーザーIDの管理やエクスポージャーイベントの追跡を容易にすることで、より合理化された開発者体験を実現します。
ユーザー同意を管理する
実験 SDK は同意 API を公開していません。consentOptions設定、ConsentStatusタイプ、setConsentStatus()メソッドはありません。
GDPRスタイルの同意フローをサポートするために、同意管理プラットフォーム(CMP)からの信号に基づいて、Amplitudeの初期化とバリアントのフェッチを制御してください。ユーザーが同意を与えるまで、アナリティクス SDK の初期化や、fetch() または start()の呼び出しを行わないでください。
import * as amplitude from '@amplitude/analytics-browser';
import { Experiment } from '@amplitude/experiment-js-client';
// Call this only after your CMP reports that the user granted consent.
async function onConsentGranted() {
amplitude.init('API_KEY');
const experiment = Experiment.initializeWithAmplitudeAnalytics('DEPLOYMENT_KEY');
await experiment.fetch();
}
ユーザーが同意を取り消した場合は、fetch()の呼び出しを停止し、clear()を使用して保存されているバリアントをすべてクリアしてください。
取得
ユーザーのバリアントを取得し、高速アクセスのために結果をクライアントに保存します。 この関数は、SDKクライアントの初期化に使用されたデプロイメントに関連付けられているフラグについて、ユーザーを リモートで評価します。
ユーザー ID の変更時に取得
ユーザーにとって最新のバリアントが必要な場合は、ユーザーの状態が意味のある形で変化したときに必ず fetch()を呼び出すことをお勧めします。たとえば、ユーザーがログインしてユーザーIDを受け取った場合や、フラグや実験のターゲティングルールに影響を与える可能性のあるユーザープロパティを設定している場合などです。
リモート評価の前にユーザーエンリッチメントに頼るのではなく、新しいユーザープロパティを明示的にfetch()に渡します。別のシステムを介したリモートユーザープロパティ同期にはfetch()のタイミング保証がなく、競合状態が発生する可能性があります。
fetch(user?: ExperimentUser, options?: FetchOptions): Promise<Client>
| パラメータ | 要件 | 概要 |
|---|---|---|
user | オプション | 評価要求とともに渡す明示的なユーザー情報。 SDK は、このユーザー情報と、ユーザープロバイダーを通じてインテグレーションから提供されたユーザー情報をマージします。その際、提供されたプロパティよりもfetch()に明示的に渡されたプロパティが優先されます。 |
options | オプション | 取得する明示的なフラグキー。 |
const user = {
user_id: 'user@company.com',
device_id: 'abcdefg',
user_properties: {
'premium': true,
},
};
await experiment.fetch(user);
連携またはカスタムユーザープロバイダーを使用している場合は、ユーザーを入力せずに取得できます。
await experiment.fetch();
fetch()がタイムアウト(デフォルトは10秒)した場合や何らかの理由で失敗した場合、SDKクライアントは制御を戻し、バックオフを使用してバックグラウンドで再試行します。SDKクライアントの初期化時に設定オプションでタイムアウトを設定したり、再試行を無効にしたりできます。
スタート
サーバーからフラグ設定を取得し、ユーザーのリモート評価バリアントを取得することにより、SDK を起動します。 返された promise が解決されると、SDK は準備が整います。
start(user?: ExperimentUser): Promise<void>
アプリケーションの初期化時、ユーザー情報がバリアントの評価または取得に利用可能になった後に、start()を呼び出してください。プロミスはローカル評価フラグ設定をロードし、リモート評価バリアントを取得した後に解決されます。
アプリケーションのニーズに基づいてパフォーマンスを向上させるため、初期化時の SDK 設定で fetchOnStart を設定して start() の動作を構成します。
- アプリケーションがリモート評価に依存しない場合は、リモート評価によるスタートアップ遅延の増加を避けるために、
fetchOnStartをfalseに設定してください。 - アプリケーションがリモート評価に依存しているものの、スタートアップ直後ではない場合は、
fetchOnStartをfalseに設定し、別途fetch()を呼び出して Promise を待機するようにできます。
await experiment.start();
バリアント
SDKクライアントのローカルストアからフラグまたは実験のバリアントにアクセスします。
自動露出トラッキング
連携を使用する場合や、カスタム露出トラッキングプロバイダーを設定する場合、variant()はトラッキングプロバイダーを通じて露出イベントを自動的に追跡します。この機能を無効にするには、automaticExposureTracking を false に 設定し、exposure() を使用して露出を手動で追跡します。
variant(key: string, fallback?: string | Variant): Variant
| パラメータ | 要件 | 概要 |
|---|---|---|
key | 必須 | バリアントにアクセスするためのフラグまたは実験を識別するためのフラグキーです。 |
fallback | オプション | 指定された flagKey に対してバリアントが見つからなかった場合に返される値です。 |
ユーザーがどのバリアントに振り分けられたかを判断する際は、バリアント value を既知の文字列と比較することになります。
const variant = experiment.variant('<FLAG_KEY>');
if (variant.value === 'on') {
// Flag is on
} else {
// Flag is off
}
バリアントのペイロードへのアクセス
バリアントは、任意のデータの動的ペイロードを使用して構成することもできます。バリアントのvalueを確認した後、バリアントオブジェクトからpayloadフィールドにアクセスします。
const variant = experiment.variant('<FLAG_KEY>');
if (variant.value === 'on') {
const payload = variant.payload;
}
nullバリアントvalueとは、ユーザーがバリアントに割り当てられていないことを意味します。 組み込みのフォールバックパラメータを使用して、ストアに指定されたフラグキーのバリアントがない場合に返すバリアントを指定できます。
const variant = experiment.variant('<FLAG_KEY>', { value: 'control' });
if (variant.value === 'control') {
// Control
} else if (variant.value === 'treatment') {
// Treatment
}
すべて
SDKクライアントによって保存されているすべてのバリアントにアクセスできます。
all(): Variants
クリア
キャッシュとストレージ内のすべてのバリアントをクリアします。
clear(): void
ユーザーのログアウト後に clear を呼び出して、キャッシュとストレージ内のバリアントをクリアできます。
experiment.clear();
エクスポージャー
設定済みの連携またはカスタムエクスポージャー追跡プロバイダーを通じて、指定されたフラグキーの現在のバリアントに対するエクスポージャーイベントを手動で追跡します。一般的に、automaticExposureTracking 構成のオプションを false に設定することと併せて使用されます。
exposure(key: string): void
| パラメータ | 要件 | 概要 |
|---|---|---|
key | 必須 | エクスポージャーイベントを追跡するためのフラグまたは実験バリアントを識別するためのフラグキーです。 |
const variant = experiment.variant('<FLAG_KEY>');
// Do other things...
experiment.exposure('<FLAG_KEY>');
if (variant.value === 'control') {
// Control
} else if (variant.value === 'treatment') {
// Treatment
}
プロバイダー
連携
実験 Client SDKと併せてAmplitudeまたはSegmentアナリティクスSDKを使用する場合、Amplitudeはカスタムプロバイダーを実装するのではなく連携を使用することをお勧めします。
プロバイダーの実装により、ユーザー ID の管理やエクスポージャー イベントの追跡が容易になるため、開発者のエクスペリエンスがより合理化されます。
ユーザープロバイダー
SDKクライアントは、必要な場合(たとえば、fetch()が呼び出されたとき)にのみ、ユーザープロバイダーを使用して最新のユーザー情報にアクセスします。ユーザープロバイダはオプションですが、アプリケーションにユーザー情報ストアがすでに設定されている場合に役立ちます。 ユーザープロバイダーを使用すると、2 つの別々のユーザー情報ストアを並行して管理する必要はありません。 アプリケーションのユーザーストアが更新されていても実験が更新されていない場合(またはその逆の場合)に、個別のストアが異なるユーザー状態を作成することがあります。
interface ExperimentUserProvider {
getUser(): ExperimentUser;
}
カスタムユーザープロバイダーを使用するには、SDK の初期化時にカスタム実装のインスタンスを使用してuserProviderの設定オプションを指定してください。
const experiment = Experiment.initialize('<DEPLOYMENT_KEY>', {
userProvider: new CustomUserProvider(),
});
エクスポージャー追跡プロバイダー
Amplitudeは露出追跡プロバイダーを実装することを強く推奨しています。 露出追跡は実験結果の正確性と信頼性を高め、ユーザーがどのフラグや実験にさらされているかをより明確に把握できるようにします。
export interface ExposureTrackingProvider {
track(exposure: Exposure, groups?: Record<string, string[]>): void;
}
track()の実装は、Exposure引数から、2つのイベントプロパティを持つ$exposure型flag_keyのイベントを追跡する必要がありますvariant。オプションの2番目の引数には、評価ユーザーのグループが含まれています。 これらをイベントプロパティではなく、イベントレベルのグループとして転送します。 SDKは、ユーザーのグループが欠落しているか空白である場合、エクスポージャーにバリアントがない場合、またはユーザーのグループ値が10個を超える場合、この引数なしでSDKtrack()を呼び出します。このイベントは、SDKクライアントの初期化に使用された[デプロイメント]と同じプロジェクトのAmplitude アナリティクスに到達し、バリアントが取得されたのと同じユーザーである必要があります。
import * as amplitude from '@amplitude/analytics-browser';
import type { ExposureTrackingProvider } from '@amplitude/experiment-js-client';
const exposureTrackingProvider: ExposureTrackingProvider = {
track: (exposure, groups) => {
amplitude.track('$exposure', exposure, { groups });
},
};
カスタムユーザープロバイダーを使用するには、SDK の初期化時にカスタム実装のインスタンスを使用してexposureTrackingProviderの設定オプションを指定してください。
const experiment = Experiment.initialize('<DEPLOYMENT_KEY>', {
exposureTrackingProvider: new CustomExposureTrackingProvider(),
});
ブートストラップ
バリアントが外部ソースから提供される場合(たとえば、SDKクライアントでfetch()を呼び出すことによるものではない場合)、初期のフラグまたはバリアントのセットを使用して実験クライアントをブートストラップしたい場合があります。ユースケースには、ローカル評価、サーバー側レンダリング、特定のバリアントに対する連携テストなどがあります。
ブートストラップのバリアント
事前定義されたバリアントのセットを使用してクライアントをブートストラップするには、initialVariantsの設定オブジェクトにフラグとバリアントを設定し、source をSource.InitialVariants に設定します。これにより、SDKクライアントは同じフラグに対して以前に取得および保存されたバリアントよりもブートストラップされたバリアントを優先します。
const experiment = Experiment.initialize('<DEPLOYMENT_KEY>', {
// Map flag keys to variant objects. The variant object may either be
// pre-evaluation (SSR) or input manually in for testing.
initialVariants: {
"<FLAG_KEY>": {
"value": "<VARIANT>"
}
},
source: Source.InitialVariants,
});
ブートストラップフラグの設定
initialFlags 設定により、ローカル評価フラグ設定の初期セットを使用して SDK をブートストラップすることを選択できます。SDKはvariantが呼び出されたときにこれらのフラグ設定を評価します。ただし、更新されたフラグ設定またはvariantがstartまたはfetchでロードされている場合を除きます。
初期フラグをダウンロードするには、評価フラグAPIを使用してください
const experiment = Experiment.initialize('<DEPLOYMENT_KEY>', {
initialFlags: "<FLAGS_JSON>",
});
HTTPクライアント
カスタムHTTPクライアント実装を提供して、SDKによって行われたネットワーク要求を処理できます。これは、特定のネットワーク要件を持つ環境や、リクエスト処理をカスタマイズする必要がある場合に役立ちます。
export interface SimpleResponse {
status: number;
body: string;
}
export interface HttpClient {
request(
requestUrl: string,
method: string,
headers: Record<string, string>,
data: string,
timeoutMillis?: number,
): Promise<SimpleResponse>;
}
カスタムHTTPクライアントを使用するには、SDKの初期化時に実装のインスタンスを使用してhttpClientの設定オプションを指定してください。
const experiment = Experiment.initialize('<DEPLOYMENT_KEY>', {
httpClient: new CustomHttpClient(),
});
カスタムログ記録
logLevel設定を使用してログの詳細さを制御するか、独自のログソリューションを統合するためにLoggerインターフェイスを実装してください。
ログレベル
LogLevel.Disable- ログ記録なしLogLevel.Error- エラーのみ (デフォルト)LogLevel.Warn- エラーと警告LogLevel.Info- エラー、警告、および情報メッセージLogLevel.Debug- エラー、警告、情報、およびデバッグメッセージLogLevel.Verbose- 詳細な内容を含むすべてのメッセージ
import { Experiment, LogLevel } from '@amplitude/experiment-js-client';
// Only log errors
const experiment = Experiment.initialize('<DEPLOYMENT_KEY>', {
logLevel: LogLevel.Error
});
// Log errors and warnings
const experiment = Experiment.initialize('<DEPLOYMENT_KEY>', {
logLevel: LogLevel.Warn
});
// Log everything (verbose)
const experiment = Experiment.initialize('<DEPLOYMENT_KEY>', {
logLevel: LogLevel.Verbose
});
カスタムロガー
独自のロギングソリューションを使用できるように、Loggerインターフェースを実装します。
import { Experiment, Logger, LogLevel } from '@amplitude/experiment-js-client';
// Implement the Logger interface
class CustomLogger implements Logger {
error(message?: any, ...optionalParams: any[]): void {
// Send errors to your logging service
myLoggingService.error(message, ...optionalParams);
}
warn(message?: any, ...optionalParams: any[]): void {
myLoggingService.warn(message, ...optionalParams);
}
info(message?: any, ...optionalParams: any[]): void {
myLoggingService.info(message, ...optionalParams);
}
debug(message?: any, ...optionalParams: any[]): void {
myLoggingService.debug(message, ...optionalParams);
}
verbose(message?: any, ...optionalParams: any[]): void {
myLoggingService.verbose(message, ...optionalParams);
}
}
// Initialize with custom logger
const experiment = Experiment.initialize('<DEPLOYMENT_KEY>', {
loggerProvider: new CustomLogger(),
logLevel: LogLevel.Warn
});
デバッグフラグ (非推奨)
このdebug設定フラグは非推奨です。 代わりにlogLevelを使用してください。
// Deprecated: Sets logLevel to Debug
const experiment = Experiment.initialize('<DEPLOYMENT_KEY>', {
debug: true
});
// Preferred: Use logLevel instead
const experiment = Experiment.initialize('<DEPLOYMENT_KEY>', {
logLevel: LogLevel.Debug
});
これは役に立ちましたか?
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.