実験 React Native SDK

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

インストール

実験 JavaScript Client SDKをインストールします。このライブラリは @react-native-async-storage/async-storage に依存しており、これもインストールする必要があります。

npm install @amplitude/experiment-react-native-client
npm install @react-native-async-storage/async-storage

iOSでSDKを実行するには、ネイティブモジュールをインストールする必要があります。

cd ios
pod install

import { Experiment } from '@amplitude/experiment-react-native-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
}

Amplitude Analytics プラグイン

@amplitude/analytics-react-nativeを使用している場合は、実験をプラグインとして統合するために@amplitude/plugin-experiment-react-nativeをインストールしてください。このプラグインは現在のアナリティクス・アイデンティティを読み取り、アナリティクスを通じてエクスポージャーイベントを送信します。

npm install @amplitude/plugin-experiment-react-native@1.0.0-beta.1

プラグインを追加し、アナリティクスを初期化してから、実験を開始し、バリアントにアクセスしてください。

import { add, init } from '@amplitude/analytics-react-native';
import { experimentPlugin } from '@amplitude/plugin-experiment-react-native';
const experiment = experimentPlugin({
  // Required unless Experiment and Analytics share the same project.
  deploymentKey: 'DEPLOYMENT_KEY',
});
await add(experiment).promise;
await init('AMPLITUDE_API_KEY').promise;
await experiment.experiment?.start();
const variant = experiment.experiment?.variant('FLAG_KEY');

プラグインは次のように動作します。

• experimentPlugin()は、そのsetup()関数内でExperiment.initializeWithAmplitudeAnalytics()を呼び出します。別々にExperiment.initializeWithAmplitudeAnalytics()を呼び出さないでください。
• 実験のデプロイメントキーにdeploymentKeyを設定します。実験とアナリティクスが同じ Amplitude プロジェクトを共有している場合、プラグインはデフォルトでアナリティクス API キーを使用します。
• 実験プラグインは、アナリティクスinit()の前または後に登録できます。この例では、パッケージのクイックスタートに合わせて、init()の前にこれを登録します。
• fetchOnStart が false でない限り、start()はデフォルトでバリアントを取得します。 start() が完了する前に、variant() はキャッシュされた割り当て、初期バリアント、またはフォールバックを返すことができます。アプリがスタートアップフェッチの完了を必要とする場合は、start()を待機します。
• automaticFetchOnAmplitudeIdentityChangeをtrueに設定すると、ログインやログアウトなど、アナリティクス・アイデンティティ情報が変更された後にフェッチされます。デフォルトは false です。

初期化する

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

initializeWithAmplitudeAnalytics(apiKey: string, config?: ExperimentConfig): ExperimentClient

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

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

設定

SDKクライアントの設定は、初期化時に実行されます。

統合

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

取得

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

fetch(user?: ExperimentUser): Promise<Client>

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

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>

| パラメータ | 要件 | 概要 | | --------- | ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- | | user | オプション | バリアントを取得するためのリクエストに渡す明示的なユーザー情報。 このユーザー情報は、ユーザープロバイダーを介したあらゆるインテグレーションからのユーザー情報と統合され、提供されたプロパティよりもfetch()に明示的に渡されたプロパティを優先します。また、SDK 内のユーザーを再利用できるように設定します。 | undefined |

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

SDK 設定で fetchOnStartを指定して start()の動作を設定し、アプリケーションのパフォーマンスを向上させます。

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

await experiment.start();

クライアントが initialVariantsまたは initialFlagsを使用してブートストラップされており、start() の結果を待つ必要がない場合は、非同期ストレージにバリアントとフラグがロードされていることを確認するために、cacheReady() を呼び出して await してください。

バリアント

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

variant(key: string, fallback?: string | Variant): Variant

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

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

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

const variant = experiment.variant('<FLAG_KEY>');
// Do other things...
experiment.exposure('<FLAG_KEY>');
if (variant === 'control') {
    // Control
} else if (variant === 'treatment') {
    // Treatment
}

プロバイダー

プロバイダーの実装により、ユーザー 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): void;
}

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

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

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

ブートストラップ

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

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

const experiment = Experiment.initialize('<DEPLOYMENT_KEY>', {
    initialVariants: { /* Flags and variants */ },
    source: Source.InitialVariants,
});

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-react-native-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-react-native-client';
// Implement the Logger interface
class CustomLogger implements Logger {
  error(message, ...optionalParams) {
    // Send errors to your logging service
    myLoggingService.error(message, ...optionalParams);
  }
  warn(message, ...optionalParams) {
    myLoggingService.warn(message, ...optionalParams);
  }
  info(message, ...optionalParams) {
    myLoggingService.info(message, ...optionalParams);
  }
  debug(message, ...optionalParams) {
    myLoggingService.debug(message, ...optionalParams);
  }
  verbose(message, ...optionalParams) {
    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
});