Browser Unified SDKの利用を開始する
このガイドでは、Browser Unified SDK(@amplitude/unified)をインストールし、そのSDKに含まれるすべてのプロダクトを1回の呼び出しで初期化し、Amplitudeに1つのカスタムイベントを送信する方法について説明します。完全なオプションリストについては、UnifiedOptionsを参照してください。バージョン間の変更点については、@amplitude/unifiedchangelogを参照してください。
Unified SDKでは、Browser SDK 2 (@amplitude/analytics-browser)をセッションリプレイ、実験、ガイドとサーベイとバンドルしています。すべての分析のメソッドとオプションは、Browser SDK 2と同じように機能します。分析のみが必要な場合は、Browser SDK 2をインストールしてください。同じページに両方のパッケージをインストールしないでください。 npm、Unified Script、およびGoogle Tag Managerを比較するには、「ブラウザのインストールを選択する」を参照してください。
前提条件
- AmplitudeプロジェクトとそのAPIキー。 キーを見つけるには、_設定 > プロジェクト_に移動し、プロジェクトを選択して「一般」を開きます。
- 組織が使用しているデータセンター:米国(デフォルト)またはEU。
- webpack、Vite、esbuildなどのJavaScriptバンドラ。 Unified SDKはnpmからのみインストールされます。 スクリプトタグの場合は、Unified Scriptを使用します。
- ページは
http://またはhttps://を使用して提供されます。file://から開かれたページはクッキーを設定できないため、SDKはロードの間でIDを永続化することはできません。
SDKをインストールする
npm install @amplitude/unified
次に、パッケージをインポートします:
import * as amplitude from "@amplitude/unified";
インストールに関する問題を修正
| 症状 | 原因 | 修正 |
|---|---|---|
amplitude.init is not a function | Unifiedパッケージはinit()をエクスポートしません。 | 代わりにinitAll()を呼び出してください。 |
| 2つのAmplitudeインスタンス、または2回送信されたイベント | このページには、@amplitude/analytics-browser、スクリプトローダー、またはUnified Scriptもロードされます。 | 1ページにつき、Amplitudeのエントリポイントを1つ保持してください。 |
| バンドルサイズが予想以上に増加しました | このパッケージにはすべてのプロダクトが含まれており、実行時にCDNからガイドとサーベイのバンドルをロードします。 | Browser SDK 2をインストールし、必要なプロダクトのみを追加します。ブラウザのインストールを選択に移動します。 |
SDKの初期化
initAll()できるだけ早く、一度呼び出してください。この操作はまず分析を初期化し、次にセッションリプレイ、実験(機能)、ガイドとサーベイをプラグインとして追加します。SDKは、initAll()が完了する前にあなたが作成したすべての呼び出しをキューに格納し、完了後に実行します。
amplitude.initAll("YOUR_API_KEY", {
serverZone: "EU", // Omit for US projects.
analytics: { autocapture: true },
sessionReplay: { sampleRate: 1 }, // Records every session. Lower this before production.
});
最上位レベルでserverZoneを設定してください(analytics内ではありません)。initAll()は、トップレベルの値をすべてのプロダクトに渡し、トップレベルの値を未設定のままにした場合でも、プロダクトごとの値を上書きします。
セッションリプレイは、sessionReplay.sampleRateを0より上に設定するまで何も記録しません。
initAll() はユーザーID引数を受け入れません。その後にamplitude.setUserId()呼び出します。
初期化に関する問題を修正
| 症状 | 原因 | 修正 |
|---|---|---|
EUプロジェクトだが、イベントは米国のデータセンターに到達するか、Invalid API keyで失敗する | serverZone: "EU"はanalytics内にあります。未設定のトップレベルのserverZoneがこれを上書きします。 | serverZoneをinitAll()オプションの最上位レベルに移動します。 |
コンソールの警告:Plugin with name @amplitude/unified-library-plugin already exists, skipping registration | initAll()が同じインスタンスで2回目に実行されました。2回目の呼び出しでは、分析が再度初期化され、すべてのプラグインが再起動されます。 | ページ読み込みごとにinitAll()を1回呼び出してください。 |
ログ:Session ... not being captured due to capture being disabled for project or because the remote config could not be fetched. | セッションリプレイのキャプチャがプロジェクトでオフになっているか、APIキーが間違っています。 | APIキーとserverZoneを確認し、プロジェクトでセッションリプレイが有効になっていることを確認します。 |
| リプレイなし、キャプチャログなし | sessionReplay.sampleRateは0、デフォルトです。 | sampleRateを0の上に設定します。 |
Angularアプリでクリックや入力がinitAll()機能しなくなります | initAll()はBrowser SDK 2のinit()を呼び出し、Zone.jsはautocaptureがパッチを当てるDOM APIもラップします。 | initAll()のmain.ts内のbootstrapApplicationの前、またはNgZone.runOutsideAngular()の内で呼び出します。 |
| サーバー側のレンダリング期間中のエラー | initAll()サーバー上で実行されます(Next.js、Nuxt、SvelteKit、Remix)。 | ブラウザコードでのみinitAll()呼び出します。Next.jsインストールガイドを参照してください。 |
クッキーや自動キャプチャの警告などの分析の初期化エラーについては、「ブラウザSDK 2の初期化問題を修正する」を参照してください。
最初のイベントを送信する
1つのカスタムイベントを追跡し、アップロード結果を待機します。track()は、アップロードの試行後にpromiseが解決されるオブジェクトを返します。
const result = await amplitude.track("Sign Up Clicked", {
plan: "starter",
}).promise;
console.log(result.code, result.message);
// 200 "Event tracked successfully"
アップロードに関する問題を修正
Unified SDKはバンドルされているBrowser SDK 2を通じてイベントをアップロードするため、結果コードはBrowser SDK 2と一致します。各エラーresult.codeおよびresult.messageステータスについては、「Browser SDK 2のアップロード問題の修正」を参照してください。
Amplitudeでイベントを確認する
- Amplitudeで、ユーザー検索を開き、
amplitude.getDeviceId()デバイスIDを検索します。 - アクティビティタブを開き、ライブイベントの更新をオンにします。
Sign Up Clickedがplanプロパティと一緒に表示されることを確認します。
イベントが1分以内に表示されない場合は、「イベントの確認」に従ってください。
次のステップ
- 共有オプションとプロダクトごとのオプションを設定します。各プロダクトを設定に移動します。
- フラグを取得し、バリアントを読み取ります。「機能実験を使用 (Use Feature Experiment)」へ移動します。
- ガイドとサーベイを使用しない場合は、オフにしてください。「ガイドとサーベイをオフにする (Turn off Guides and Surveys)」へ移動します。
- カスタムイベントを追跡し、ユーザーを識別し、自動キャプチャイベントを選択します。 Instrument に移動し、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.