Browser SDK 2を使用開始する
このガイドでは、Browser SDK 2(@amplitude/analytics-browser)をインストールし、初期化し、Amplitudeに1つのカスタムイベントを送信する方法について説明します。 各ステップで問題を引き起こす一般的なブラウザ条件がリストされているため、問題が発生した時点で修正できます。完全なオプションリストについては、設定オプションを参照してください。
Browser SDK 2は、アナリティクス専用パッケージです。 セッションリプレイ、機能実験、またはガイドとサーベイも必要な場合は、代わりにBrowser Unified SDK(@amplitude/unified)をインストールしてください。 このパッケージにはBrowser SDK 2が含まれているため、両方のパッケージを同じページにインストールしないでください。
前提条件
- AmplitudeプロジェクトとそのAPIキー。 設定 > プロジェクト > _一般_でキーを見つけます。
- 組織が使用しているデータセンター:米国(デフォルト)またはEU。
- 最新のBrowser SDK 2リリース、または使用している機能のBrowser SDK 2リリースノートと比較して確認したピン留めバージョン。
http://またはhttps://を使用して提供されるページ。file://から開かれたページはクッキーを設定できないため、SDKはロード間隔でIDを永続化することはできません。
SDKをインストールする
インストール方法を1つ選択します。 JavaScriptをバンドルしている場合は、npmまたはyarnを使用してください。直接、またはタグマネージャー経由でHTMLにタグを追加する場合は、スクリプトローダーを使用します。
npm install @amplitude/analytics-browser
import * as amplitude from "@amplitude/analytics-browser";
代わりにUnified SDKを使用するには、@amplitude/unifiedまたはnpm install @amplitude/unifiedを使用してyarn add @amplitude/unifiedインストールし、同じ方法でインポートします:
import * as amplitude from "@amplitude/unified";
Unifiedパッケージは、同様のトラッキングtrack()および ID メソッドsetUserId()をエクスポートしますが、一部はエクスポートしませんinit()。代わりにanalyticsメソッドinitAll()を呼び出し、このガイドの分析オプションを以下の通り渡します:
amplitude.initAll("YOUR_API_KEY", {
serverZone: "EU", // Omit for US projects.
analytics: { autocapture: true },
});
initAll() はユーザーID引数を受け入れません。 その後にsetUserId()呼び出します。
インストールに関する問題を修正
| 症状 | 原因 | 修正 |
|---|---|---|
amplitude is not defined コンソール(スクリプトローダー) | このスニペットは、コードの実行後にロードされます。または、コンテンツセキュリティポリシーによってスニペットがブロックされます。 | amplitudeを呼び出す任意のコードの前に、スニペットを配置します。 https://*.amplitude.comをscript-srcに追加してください。 |
net::ERR_BLOCKED_BY_CLIENT SDKスクリプトの場合 | 広告ブロッカーまたはプライバシー拡張機能は、CDNをブロックします。 | npmからインストールし、SDKをコードにバンドルするか、拡張機能なしのプロファイルでテストします。 |
2つのamplitudeグローバル変数、または2回送信されたイベント | このページはこのスニペットとUnified Scriptまたは@amplitude/unifiedの両方をロードします。 | Amplitudeのエントリポイントは、1ページにつき1つにしてください。 |
SDKの初期化
既知のユーザーIDなど、アプリに必要なコンテキストが用意され次第、なるべく早くinit()一度だけ呼び出します。完了前にinit()行った呼び出しは、キューで待機し、完了後に順番に実行されます。
amplitude.init("YOUR_API_KEY", {
autocapture: true,
});
すでに知っている場合は、ユーザーIDを2番目の引数として渡します。
amplitude.init("YOUR_API_KEY", "user-12345", {
autocapture: true,
});
プロジェクトでEUデータセンターを使用している場合は、以下serverZoneを設定します:
amplitude.init("YOUR_API_KEY", {
serverZone: "EU",
autocapture: true,
});
autocapture: trueは、SDKがブール値を使用して有効にするすべての自動キャプチャ機能をオンにします。これには、要素のクリック、フラストレーションのインタラクション、失敗したネットワークリクエスト、Web Vitalsなどが含まれます。デフォルトのセット(ページビュー、セッション、アトリビューション、フォーム、ファイルのダウンロード)のみから始めるには、autocaptureを省略するか、オブジェクトを渡します。選択肢については、自動キャプチャを参照してください。
初期化に関する問題を修正
| 症状 | 原因 | 修正 |
|---|---|---|
コンソールの警告: `options.defaultTracking` is set to undefined | autocaptureを設定していません(または非推奨のdefaultTracking)。 | エラーではありません。 autocapture明示的に設定すると、それを沈黙させます。 |
| サーバー側のレンダリング期間中にエラーが発生した、またはサーバー側でレンダリングされたページからイベントが発生しなかった | init() サーバー上で実行されます(Next.js、Nuxt、SvelteKit、Remix)。 | ブラウザコードでのinit()み呼び出されます。たとえば、クライアントコンポーネントやなどですuseEffect。 Next.jsインストールガイドを参照してください。 |
Angularアプリでクリックや入力が動作しなくなりますinit() | Zone.jsは、自動キャプチャもパッチを適用するDOM APIをラップします。 | init()のmain.ts前bootstrapApplication、または内でを呼び出しますNgZone.runOutsideAngular()。 |
| Chrome拡張機能には、ページビュー、セッション、アトリビューションはありません。 | Chrome拡張機能では、SDKは各機能を有効にしない限り、デフォルトの自動キャプチャをオフにします。 このデフォルトは2.42.1で変更されました。 | 各機能を明示的に設定します(例:autocapture: { pageViews: true, sessions: true })。 |
| IDはページ読み込みごとにリセットされます。 | ブラウザがクッキーをブロックしている(プライベートモード、厳密なトラッキング保護、またはサンドボックス化されたiframe)、あるいはページがfile://上で実行されています。 | HTTP(S)経由でページを配信します。クッキーがブロックされたままの場合は、identityStorage: "localStorage"を設定します。 |
イベントが間違ったリージョンに送信されるか、取り込みからエラーが返されます。Invalid API key | serverZone プロジェクトのデータセンターと一致しません。 | EUプロジェクト用serverZone: "EU"に設定してください。米国のプロジェクトの場合は省略します。 |
最初のイベントを送信する
1つのカスタムイベントを追跡し、アップロード結果が返されるのを待ちます。track()は、SDKがアップロード試行を完了した後にpromise解決されるオブジェクトを返します。
const result = await amplitude.track("Sign Up Clicked", {
plan: "starter",
}).promise;
console.log(result.code, result.message);
// 200 "Event tracked successfully"
SDKは、最初のイベントがキューに入ってから約1秒後に、最大30個のイベントをまとめてリクエストとしてアップロードします。そのアップロード後にはpromise解決されるため、約1秒の遅延が予想されます。
アップロードに関する問題を修正
result.codeおよびresult.message | 原因 | 修正 |
|---|---|---|
0, Event skipped due to optOut config | このブラウザでは、オプトアウトが有効になっています。 SDKはオプトアウトをクッキーに保存するため、ロード後も継続します。 | amplitude.setOptOut(false)を呼び出すか、ドメインのAMP_クッキーを消去します。 |
0, Event skipped due to empty event type | イベント名が空であるか、文字列ではありません。 | 最初の引数として空でない文字列を渡します。 |
400, Event rejected due to missing API key | init() 空のAPIキーを受け取りました。 | キーを保持している変数を確認します。 ビルドツールは、環境変数が不足している場合、しばしば空の値をインラインします。 |
400, Invalid API key: ... | キーが間違っているか、または別のデータセンター内のプロジェクトに属しています。 | キーをもう一度コピーし、serverZoneをチェックします。 |
500、Event rejected due to exceeded retry count、約10秒後 | リクエストはAmplitudeに到達せず、SDKは5回の試行後に処理を終了しました。広告ブロッカー、コンテンツセキュリティポリシー、プロキシ上のCORS、またはサーバーエラーが、この原因です。 | ブラウザのネットワークタブを開き、api2.amplitude.com(またはapi.eu.amplitude.com)へのリクエストをチェックします。 https://*.amplitude.comをconnect-srcに追加してください。広告ブロッカーがリクエストをブロックした場合は、トラフィックをプロキシ経由でルーティングしてください。 |
| promiseは決して解決されません | このインスタンスでは実行されていないため、呼び出しは引き続きinit()キューに残っています。 | init()が同じインスタンスの呼び出しの前または後に実行されていること、およびそれがスキップされたブランチ内ではないことを確認してください。 |
ページがその直後に移動すると、このイベントは消えます。track() | ページがアンロードされたときに、ブラウザはリクエストをキャンセルしました。 | デフォルトのfetchトランスポートを維持します。これはkeepaliveを使用して送信します。ペイロードが大きい場合は、「ページがアンロードされたときにイベントを送信」に移動してください。 |
Amplitudeでイベントを確認する
- Amplitudeで、ユーザー検索を開き、渡したユーザーID、または
amplitude.getDeviceId()からのデバイスIDを検索します。 - アクティビティタブを開き、ライブイベントの更新をオンにします。
planがSign Up Clickedプロパティと一緒に表示されることを確認します。
イベントが1分以内に表示されない場合は、Verify eventsに従ってください。このプロセスは、track()とAmplitudeのサーバー間の各段階を経由します。
次のステップ
setUserId()を使用して、サインイン済みのユーザーを識別し、サインアウトしたらreset()を呼び出します。- 保持するAutocaptureイベントを選択します。
- トラッキングプランに必要なカスタムイベントとプロパティを追加します。イベントの追跡に移動します。
これは役に立ちましたか?
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.