On this page

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.

実験 JavaScript SDK

npmv1.23.120.5 kB gzip

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

インストール

次の3つの方法のいずれかを使用して、実験JavaScriptクライアントSDKをインストールします。

Unified SDK

ブラウザ向け統合SDKをインストールすると、Experiment SDKに加えて他のAmplitude製品（アナリティクス、セッションリプレイ）も利用できます。Unified SDKは、すべてのAmplitude機能の単一エントリーポイントを提供し、すべてのコンポーネントの初期化と設定を処理することで連携プロセスを簡素化します。

# Install Experiment SDK only
npm install --save @amplitude/experiment-js-client
# Or install Unified SDK to get access to all Amplitude products
npm install @amplitude/unified

クイックスタート

実験SDKを初期化する正しい方法は、Amplitude SDKをアナリティクスに使用しているか、サードパーティ（例：Segment）を使用しているかによって異なります。

  1. 実験用クライアントを初期化する
  2. バリアントを取得
  3. フラグのバリアントにアクセスする
typescript
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必須です。 フェッチ要求を承認し、ユーザーに対してどのフラグを評価するかを決定するデプロイメントキー
configSDKクライアントの動作をカスタマイズするためのクライアント設定。

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

import { Experiment } from '@amplitude/experiment-js-client';
const experiment = initializeWithAmplitudeAnalytics('DEPLOYMENT_KEY');

設定

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

統合

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

ユーザー同意を管理する

実験 SDK は同意 API を公開していません。consentOptions設定、ConsentStatusタイプ、setConsentStatus()メソッドはありません。

GDPRスタイルの同意フローをサポートするために、同意管理プラットフォーム（CMP）からの信号に基づいて、Amplitudeの初期化とバリアントのフェッチを制御してください。ユーザーが同意を与えるまで、アナリティクス SDK の初期化や、fetch() または start()の呼び出しを行わないでください。

typescript
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() のタイミング保証がありません。そのため、競合状態が発生する可能性があります。

typescript
fetch(user?: ExperimentUser, options?: FetchOptions): Promise<Client>
パラメータ要件概要
userオプション評価要求とともに渡す明示的なユーザー情報。 SDK は、このユーザー情報と、ユーザープロバイダーを通じてインテグレーションから提供されたユーザー情報をマージします。その際、提供されたプロパティよりもfetch()に明示的に渡されたプロパティが優先されます。
optionsオプション取得する明示的なフラグキー。

typescript
const user = {
    user_id: 'user@company.com',
    device_id: 'abcdefg',
    user_properties: {
        'premium': true,
    },
};
await experiment.fetch(user);

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

typescript
await experiment.fetch();

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

スタート

Fetch と start の比較

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

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

typescript
start(user?: ExperimentUser): Promise<void>
パラメータ要件概要
userオプションバリアントを取得するためのリクエストに渡す明示的なユーザー情報。 SDK は、ユーザープロバイダーを通じて統合から提供されたユーザー情報とこのユーザー情報を統合し、提供されたプロパティよりも明示fetch()的に渡されたプロパティを優先します。また、SDK 内のユーザーを再利用できるように設定します。

アプリケーションの初期化時、ユーザー情報がバリアントの評価または取得に利用可能になった後に、start()を呼び出してください。プロミスはローカル評価フラグ設定をロードし、リモート評価バリアントを取得した後に解決されます。

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

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

バリアント

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

自動露出トラッキング

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

typescript
variant(key: string, fallback?: string | Variant): Variant
パラメータ要件概要
key必須バリアントにアクセスするためのフラグまたは実験を識別するためのフラグキーです。
fallbackオプション指定された flagKey に対してバリアントが見つからなかった場合に返される値です。

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

typescript
const variant = experiment.variant('<FLAG_KEY>');
if (variant.value === 'on') {
    // Flag is on
} else {
    // Flag is off
}

バリアントのペイロードへのアクセス

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

typescript
const variant = experiment.variant('<FLAG_KEY>');
if (variant.value === 'on') {
    const payload = variant.payload;
}

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

typescript
const variant = experiment.variant('<FLAG_KEY>', { value: 'control' });
if (variant.value === 'control') {
    // Control
} else if (variant.value === 'treatment') {
    // Treatment
}

すべて

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

typescript
all(): Variants

クリア

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

typescript
clear(): void

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

typescript
experiment.clear();

エクスポージャー

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

typescript
exposure(key: string): void
パラメータ要件概要
key必須エクスポージャーイベントを追跡するためのフラグまたは実験バリアントを識別するためのフラグキーです。
typescript
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 つの別々のユーザー情報ストアを並行して管理する必要はありません。 アプリケーションのユーザーストアが更新されていても実験が更新されていない場合（またはその逆の場合）に、個別のストアが異なるユーザー状態を作成することがあります。

typescript
interface ExperimentUserProvider {
  getUser(): ExperimentUser;
}

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

typescript
const experiment = Experiment.initialize('<DEPLOYMENT_KEY>', {
    userProvider: new CustomUserProvider(),
});

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

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

typescript
export interface ExposureTrackingProvider {
  track(exposure: Exposure): void;
}

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

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

typescript
const experiment = Experiment.initialize('<DEPLOYMENT_KEY>', {
    exposureTrackingProvider: new CustomExposureTrackingProvider(),
});

ブートストラップ

バリアントが外部ソースから提供される場合（たとえば、SDKクライアントでfetch()を呼び出すことによるものではない場合）、初期のフラグまたはバリアントのセットを使用して実験クライアントをブートストラップしたい場合があります。ユースケースには、ローカル評価、サーバー側レンダリング、特定のバリアントに対する連携テストなどがあります。

ブートストラップのバリアント

事前定義されたバリアントのセットを使用してクライアントをブートストラップするには、initialVariantsの設定オブジェクトにフラグとバリアントを設定し、source をSource.InitialVariants に設定します。これにより、SDKクライアントは同じフラグに対して以前に取得および保存されたバリアントよりもブートストラップされたバリアントを優先します。

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

typescript
const experiment = Experiment.initialize('<DEPLOYMENT_KEY>', {
    initialFlags: "<FLAGS_JSON>",
});

HTTPクライアント

カスタムHTTPクライアント実装を提供して、SDKによって行われたネットワーク要求を処理できます。これは、特定のネットワーク要件を持つ環境や、リクエスト処理をカスタマイズする必要がある場合に役立ちます。

typescript
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の設定オプションを指定してください。

typescript
const experiment = Experiment.initialize('<DEPLOYMENT_KEY>', {
    httpClient: new CustomHttpClient(),
});

カスタムログ記録

logLevel設定を使用してログの詳細さを制御するか、独自のログソリューションを統合するためにLoggerインターフェイスを実装してください。

ログレベル

  • LogLevel.Disable - ログ記録なし
  • LogLevel.Error - エラーのみ （デフォルト）
  • LogLevel.Warn - エラーと警告
  • LogLevel.Info - エラー、警告、および情報メッセージ
  • LogLevel.Debug - エラー、警告、情報、およびデバッグメッセージ
  • LogLevel.Verbose - 詳細な内容を含むすべてのメッセージ
typescript
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インターフェースを実装します。

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

typescript
// 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
});

Was this helpful?