Browser Unified SDKのインスツルメンテーションと設定
このガイドでは、Browser Unified SDK(@amplitude/unified)に固有のタスクについて説明します:プロダクトの設定、Feature実験とセッションリプレイの使用、およびガイドとサーベイのオフ設定。イベントの追跡、ユーザーの識別、自動キャプチャ、アップロードの動作は、バンドルされているBrowser SDK 2から提供されており、同じように動作します。これらのタスクについては、Instrumentに移動し、Browser SDK 2を設定します。署名については、Browser Unified SDKリファレンスを参照してください。 バージョン間の変更点については、@amplitude/unifiedchangelogを参照してください。
各プロダクトを設定する
initAllが各プロダクトを設定する方法
initAll()これらのステップを順番に実行し、最後のステップの後に解決されます:
analyticsオプションを使用して、分析(Browser SDK 2)を初期化します。- セッションリプレイプラグインを
sessionReplayオプションで追加します。 experimentオプションを使用して、Feature実験プラグインを追加します。- ガイドとサーベイのプラグインを
engagementオプション付きで追加します。
すべてのステップで、initAll()は共有オプションとserverZoneおよびinstanceNameを、製品独自のオプションにマージします。共有値は、設定されていない場合でも常に優先されます。設定されていないトップレベルの serverZone は analytics.serverZone を undefined に置き換え、プロダクトはデフォルトの US にフォールバックします。
共有オプションを最上位レベルに設定
serverZoneとinstanceNameをoptionsオブジェクトの最上位レベルに設定し、プロダクトブロック内には設定しません:
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最上位レベルに移動します。
各プロダクトにオプションを渡す
各プロダクトブロックは、そのプロダクトのオプションを受け入れます。
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,
},
});
| ブロック | 許可 |
|---|---|
analytics | Amplitude Browser SDK 2のすべてのオプション。 |
sessionReplay | セッションリプレイプラグインのオプション。共有オプションを除きます。 |
experiment | 実験JavaScript SDKのオプション、プラスdeploymentKey。 |
engagement | ガイドとサーベイのオプション、プラスskip。 |
Feature 実験を使用
フラグを取得し、バリアントを読み取る
Amplitude Feature 実験クライアントは、initAll()期間中にフラグを取得しません。バリアントを読み取る前にfetch()を呼び出して、その状態を待ちます。最初のフェッチが完了する前に、variant()は空のオブジェクトを返します。
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。
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() が解決した後にセッションリプレイクライアントを返します:
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を渡してください:
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を指定します:
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 のドメインを許可してください:
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.