Browser Unified SDKのインスツルメンテーションと設定

このガイドでは、Browser Unified SDK(@amplitude/unified)に固有のタスクについて説明します:プロダクトの設定、Feature実験とセッションリプレイの使用、およびガイドとサーベイのオフ設定。イベントの追跡、ユーザーの識別、自動キャプチャ、アップロードの動作は、バンドルされているBrowser SDK 2から提供されており、同じように動作します。これらのタスクについては、Instrumentに移動し、Browser SDK 2を設定します。署名については、Browser Unified SDKリファレンスを参照してください。 バージョン間の変更点については、@amplitude/unifiedchangelogを参照してください。

各プロダクトを設定する

initAllが各プロダクトを設定する方法

initAll()これらのステップを順番に実行し、最後のステップの後に解決されます:

  1. analyticsオプションを使用して、分析(Browser SDK 2)を初期化します。
  2. セッションリプレイプラグインをsessionReplayオプションで追加します。
  3. experimentオプションを使用して、Feature実験プラグインを追加します。
  4. ガイドとサーベイのプラグインをengagementオプション付きで追加します。

すべてのステップで、initAll()は共有オプションとserverZoneおよびinstanceNameを、製品独自のオプションにマージします。共有値は、設定されていない場合でも常に優先されます。設定されていないトップレベルの serverZone は analytics.serverZone を undefined に置き換え、プロダクトはデフォルトの US にフォールバックします。

共有オプションを最上位レベルに設定

serverZoneとinstanceNameをoptionsオブジェクトの最上位レベルに設定し、プロダクトブロック内には設定しません:

ts
amplitude.initAll("YOUR_API_KEY", {
  serverZone: "EU",
  instanceName: "storefront",
});

最上位レベルで設定することserverZone: "EU"により、すべてのプロダクトがEUデータセンターを使用します。分析はapi.eu.amplitude.comにアップロードされます。セッションリプレイはsr-client-cfg.eu.amplitude.comから設定を読み取り、機能実験はapi.lab.eu.amplitude.comから取得します。

EUのプロジェクトは、分析内のデータセンター設定を失います。

initAll("KEY", { analytics: { serverZone: "EU" } }) 米国のデータセンターにイベントを送信します。serverZone最上位レベルに移動します。

各プロダクトにオプションを渡す

各プロダクトブロックは、そのプロダクトのオプションを受け入れます。

ts
amplitude.initAll("YOUR_API_KEY", {
  serverZone: "EU",
  analytics: {
    autocapture: { elementInteractions: true },
    identityStorage: "localStorage",
  },
  sessionReplay: {
    sampleRate: 0.1,
  },
  experiment: {
    deploymentKey: "YOUR_CLIENT_DEPLOYMENT_KEY",
  },
  engagement: {
    skip: true,
  },
});

Feature 実験を使用

フラグを取得し、バリアントを読み取る

Amplitude Feature 実験クライアントは、initAll()期間中にフラグを取得しません。バリアントを読み取る前にfetch()を呼び出して、その状態を待ちます。最初のフェッチが完了する前に、variant()は空のオブジェクトを返します。

ts
await amplitude.initAll("YOUR_API_KEY", {
  experiment: { deploymentKey: "YOUR_CLIENT_DEPLOYMENT_KEY" },
});
const experiment = amplitude.experiment();
await experiment?.fetch();
const variant = experiment?.variant("checkout-redesign");
if (variant?.value === "treatment") {
  // Show the new checkout.
}

fetch()は分析からユーザーIDとデバイスIDを送信します。そのため、ユーザーを認識している場合はsetUserId()をfetch()の前に呼び出します。クライアントの他のメソッド(exposure()、all()、clear()など)については、実験JavaScript SDKを参照してください。

デプロイメントキーを設定する

experiment.deploymentKeyを、Amplitude 実験のクライアントデプロイメントキーに設定します。これを省略した場合、プラグインはプロジェクトのAPIキーをデプロイメントキーとして使用します。

Unified SDK 1.1.43には、実験プラグインのベータ版リリースである@amplitude/plugin-experiment-browser1.0.0-beta.51が含まれています。

セッションリプレイを使用する

サンプルレートを選択します。

セッションリプレイはデフォルトでは何も記録しません。なぜならsessionReplay.sampleRateはデフォルトで0になるからです。0から1の間の値を設定してください。1はすべてのセッションを記録し、0.1は約10分の1のセッションを記録します。テスト中は使用し、本番環境に移行する前に値を下げてください1。

ts
amplitude.initAll("YOUR_API_KEY", {
  sessionReplay: { sampleRate: 0.1 },
});

Amplitudeのリモート設定でも、プロジェクトのキャプチャをオフにすることができます。 キャプチャがオフの場合、ログに以下のように表示されますSession ... not being captured due to capture being disabled for project or because the remote config could not be fetched.

コードから録画を制御

amplitude.sessionReplay() は、initAll() が解決した後にセッションリプレイクライアントを返します:

ts
await amplitude.initAll("YOUR_API_KEY", { sessionReplay: { sampleRate: 1 } });
const replay = amplitude.sessionReplay();
replay?.stop(); // Pause recording, for example on a page with sensitive data.
await replay?.flush(false); // Upload recorded data now, without retries.
replay?.start(); // Resume recording.

start()は、サンプルレート、ターゲティング、オプトアウトを依然として尊重します。ページの残りの部分の録画を停止し、セッションリプレイリスナーを削除するには、shutdown()を呼び出します。

マスキング、プライバシー、およびプラグインのその他のオプションについては、セッションリプレイプラグインを参照してください。

ガイドとサーベイをオフにする

ガイドとサーベイはデフォルトで初期化されます。 initAll()期間中、そのバンドルをcdn.amplitude.comからダウンロードし、gs.amplitude.comを呼び出します。ガイドとサーベイを使用していない場合は、skip: trueを渡してください:

ts
amplitude.initAll("YOUR_API_KEY", {
  engagement: { skip: true },
});

skip: trueを使用すると、ガイドとサーベイは何もダウンロードせず、リクエストも行わず、amplitude.engagement.*にlocalStorageキーを書き込みません。コンソールログ Engagement SDK init skipped via `skip: true`. The SDK bundle will not be loaded. The skip オプションには、Unified SDK 1.1.11以降が必要です。

ガイドとサーベイを有効にするには、initAll()の呼び出しからskip: trueを削除し、デプロイしてください。同じページで2回目にinitAll()を呼び出して有効にしないでください。2回目の呼び出しでは、分析が再度初期化され、すべてのプラグインが再インストールされ、別のページビューが追跡され、セッションリプレイが再起動されます。

複数のインスタンスを実行する

2番目のプロジェクトにデータを送信するには、createInstance()を使用してインスタンスを作成し、別のinstanceNameを指定します:

ts
await amplitude.initAll("PRODUCTION_API_KEY");
const marketing = amplitude.createInstance();
await marketing.initAll("MARKETING_API_KEY", {
  instanceName: "marketing",
});
amplitude.track("Signup Completed");
marketing.track("Signup Completed");

各インスタンスは、独自の分析、セッションリプレイ、機能実験を初期化します。 ガイドとサーベイは、initAll() が実行される最初のインスタンスに対して、ページごとに一度初期化されます。以降のインスタンスでは、engagementオプションは無視され、Engagement SDK has already been initialized. Ignoring additional init call.ログが記録されます。ガイドとサーベイのオプションは、最初に初期化されるインスタンスに指定してください。インスタンスがIDをどのように分離しているかについては、Browser SDK 2の複数のプロジェクトにイベントを送信を参照してください。

データ配信

コンテンツセキュリティポリシーでAmplitudeを許可する

サイトでContent-Security-Policyヘッダーを送信する場合は、Amplitude のドメインを許可してください:

text
script-src  https://*.amplitude.com;
connect-src https://*.amplitude.com;

npmからインストールされたBrowser SDK 2とは異なり、Unified SDKにはバンドルする場合でもscript-srcが必要です。これは、ガイドとサーベイがそのバンドルをcdn.amplitude.comからダウンロードするためです。engagement: { skip: true }を設定した場合、必要なのはconnect-srcのみです。

アップロード、バッチ処理、プロキシ、オフライン動作については、Browser SDK 2のデータ配信を参照してください。

これは役に立ちましたか?

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.

このページでは