Browser SDK 2 イベントを確認します
イベントは、track()SDK呼び出しとAmplitudeのサーバーの間で4つの段階を経ます。各ステージを順番に検証します。 イベントが間違っているように見える最初の段階は、問題が発生した場所です。
すべてのAmplitude SDKに共通する問題については、「SDKのトラブルシューティングとデバッグ」を参照してください。SDKのアップグレード後に動作が変更された場合は、Browser SDK 2のリリースノートを確認してください。
デバッグログを有効にする
検証中logLevelはDebugに設定します。デバッグログには、すべての公開メソッドの呼び出し、その前後の内部状態、最終イベント、サーバーの応答が含まれます。
amplitude.init("YOUR_API_KEY", {
logLevel: amplitude.Types.LogLevel.Debug,
});
Google Tag Managerなど、列挙型をインポートできない環境では、数値4を指定してください。レベルは、0None、1Error、2Warn(デフォルト)、3Verbose、および4Debugです。各メッセージは特定の文字列で始まります。Amplitude Loggerそのため、そのプレフィックスでコンソールをフィルタリングしてください。
Google Tag Managerでは数値を使用してください。
文字列などを渡さないでください"LogLevel.None"。SDKは値を数値として比較するため、logLevel数値以外の文字列を指定すると、Debugを含むすべてのレベルが有効になります。
出荷前にlogLevel返Warnします。デバッグ出力には、イベントのペイロードと識別子が含まれます。
SDKがキャプチャした内容を確認してください
デバッグログをオンにすると、各パブリックコールは次のようなブロックを出力します。
Amplitude Logger [Debug]: {
"type": "invoke public method",
"name": "track",
"args": ["Sign Up Clicked", { "plan": "starter" }],
"stacktrace": ["at handleClick (app.js:42:13)", "..."],
"time": { "start": "2026-10-26T12:00:11.402Z", "end": "2026-10-26T12:00:12.611Z" },
"states": {
"before": { "config.apiKey": "...", "timeline.queue.length": 0 },
"after": { "config.apiKey": "...", "timeline.queue.length": 0 }
}
}
Promiseを返すメソッド(track()、identify()、flush()、など)の場合、SDKはPromiseが解決された後にブロックをログに出力します。trackしたがって、ブロックはアップロードの試行後、つまり呼び出しの約1秒後に表示されます。
次の3つのことを確認します。
- 呼び出しは実行されました。
trackブロックが表示されます。 そうでない場合、コードが呼び出しに到達しなかったか、呼び出したインスタンスで実行されなかったかのいずれかですinit()。2番目のインスタンスには、createInstance()独自のインスタンスが必要ですinit()。ページがグローバルを公開するタイミングを確認するには(スクリプトローダーはamplitude)、ブラウザのコンソールでamplitude.init("YOUR_API_KEY")実行します。その後、キューに追加されたイベントがsendの場合、独自のinit()呼び出しは実行されなかったか、別のインスタンスで実行されました。 - 引数は正しいです。
argsSDKが受信したイベント名とプロパティを正確に表示します。 - SDKの準備が整いました。 完了前に
init()行われた呼び出しは失敗しません。これらはキューで待機し、init()の後に実行されるため、ログの早い部分に表示される呼び出しは、後で送信できます。
この段階では、SDKがすべてのイベントにアタッチする状態も読み取ることができます:
amplitude.getDeviceId(); // "f3b6c1e2-..."
amplitude.getUserId(); // "user-12345" or undefined
amplitude.getSessionId(); // 1761480000000
amplitude.getOptOut(); // false
getOptOut()がtrueを返す場合、SDKはプラグインが実行される前にすべてのイベントをドロップします。これにはgetOptOut()Browser SDK 2.18.0以降が必要です。
プラグインがイベントをどのように変換したかを確認してください。
キャプチャ後、各イベントは固定された順序でプラグインパイプラインを通過します。
- プラグインの前 (
type: "before"): 組み込みのコンテキストプラグインはdevice_id、user_id、session_id、time、event_id、insert_id、library、user_agent、platform、language、ipを追加します。ブラウザがオフラインの間、ネットワークチェッカーはアップロードを一時停止します。 - エンリッチメントプラグイン(
type: "enrichment"、デフォルト):Autocaptureプラグインはここにプロパティを追加します。 たとえば、ページURLエンリッチメントでは[Amplitude] Page URLおよび[Amplitude] Previous Page Locationが追加され、アトリビューションではキャンペーンパラメータが追加されます。 独自のエンリッチメントプラグインも、ここでは追加した順序で実行されます。 - 送信先プラグイン(
type: "destination"):組み込みの送信先プラグインは、アップロード用にイベントをamplitudeキューに入れます。
nullを返すbeforeまたはenrichmentプラグインは、イベントをドロップします。 変更またはドロップの原因となるプラグインを検索するには、logLevelまたはVerboseに設定しますDebug。 その後、SDKは各ステップを記録します。
Amplitude Logger [Log]: Timeline.apply: Event after enrichment plugin 'my-plugin', event: {...}
Amplitude Logger [Log]: Timeline.apply: Event filtered out by enrichment plugin 'my-plugin', event: {...}
Amplitude Logger [Log]: Timeline.apply: Final event before destinations, event: {...}
このFinal event before destinations行は、SDKが送信する正確なイベントです。 それを期待値と比較してください。
自動化されたテストなど、コード内のイベントを検査するには、各イベントを送信先に送信することなく記録する送信先プラグインを追加します。
const captured: amplitude.Types.Event[] = [];
amplitude.add({
name: "inspect-events",
type: "destination",
execute: async (event) => {
captured.push(structuredClone(event));
return { event, code: 200, message: "inspected" };
},
});
送信先プラグインは、すべてのbeforeプラグインおよびenrichmentプラグインが実行された後にイベントを受信します。完了したら、プラグインamplitude.remove("inspect-events")を削除します。
SDKが送信した内容を確認する
SDKはPOSTリクエストとともにイベントをアップロードします。 ブラウザのネットワークタブを開き、データセンターのホストでフィルタリングします。
| 設定 | リクエストURL |
|---|---|
| デフォルト(US) | https://api2.amplitude.com/2/httpapi |
serverZone: "EU" | https://api.eu.amplitude.com/2/httpapi |
useBatch: true (US) | https://api2.amplitude.com/batch |
useBatch: true(EU) | https://api.eu.amplitude.com/batch |
serverUrl 設定 | 設定したURL |
最初のイベントがキューに入った後、リクエストはブラウザを離れますflushIntervalMillis(デフォルトでは1秒)。 各リクエストは最大flushQueueSize(デフォルトで30)件のイベントを保持します。すぐに送信するには、await amplitude.flush().promiseを呼び出します。
リクエストボディは次の構造です:
{
"api_key": "YOUR_API_KEY",
"events": [
{
"event_type": "Sign Up Clicked",
"event_properties": { "plan": "starter" },
"device_id": "f3b6c1e2-...",
"session_id": 1761480000000,
"time": 1761480012345,
"event_id": 4,
"insert_id": "9c0e...",
"platform": "Web",
"language": "en-US",
"ip": "$remote",
"library": "amplitude-ts/2.49.3",
"user_agent": "Mozilla/5.0 ..."
}
],
"options": {},
"client_upload_time": "2026-10-26T12:00:12.400Z"
}
"ip": "$remote" AmplitudeにリクエストのIPアドレスを使用するように指示します。 trackingOptions.ipAddressをfalseに設定します。
DevToolsを開かずにイベントを確認するには、Amplitude Instrumentation エクスプローラー Chrome拡張機能をインストールします。ここには、ページが送信する各イベントを、そのプロパティとともにリストします。
圧縮済みのリクエストボディ
。Amplitude独自のエンドポイントの場合、SDKは、ブラウザがサポートしている場合に2KB以上のリクエストボディをgzip圧縮しますCompressionStream。これらのリクエストにはContent-Encoding: gzipヘッダーがあり、「ペイロード」タブにはバイナリデータが表示されます。 イベントを読み取るには、Final event before destinationsログ行または検査プラグインを使用してください。このデフォルトは2.42.0で変更されました。
リクエストが表示されない場合:
| 原因 | 確認方法 | 修正 |
|---|---|---|
| ブラウザがオフラインです | navigator.onLine は falseです。デバッグログには次のように表示されますSkipping flush while offline. | ブラウザが再接続されると、SDKは自動的にアップロードされます。 |
| 広告ブロッカーまたはプライバシー拡張機能がリクエストをブロックします。 | このリクエストには、Chromeで (blocked:other)またはnet::ERR_BLOCKED_BY_CLIENT が表示されます。Firefoxは、Transferred列にブロッキング拡張機能の名前を表示します。Safariはリクエストをリストしません。 | プロキシを介してイベントをルーティングします。 |
| コンテンツセキュリティポリシーがリクエストをブロックします。 | コンソールにはRefused to connect to ... が表示されます。 | https://*.amplitude.comをconnect-srcに追加してください。 |
| リクエストが完了する前にページがアンロードされました | このリクエストには(canceled) が表示されます。 | 「ページがアンロードされたときにイベントを送信」に移動します。 |
transport は "beacon" です | リクエストのタイプはpingであり、レスポンスは使用できません。 | 予期される動作です。sendBeaconはレスポンスを公開しません。検証中に"fetch"に切り替えます。 |
Amplitudeが何を受信したかを確認してください。
アップロード結果の読み取り
すべてのトラッキングメソッドは値を返します{ promise }。アップロード試行が完了すると、PromiseはResultに解決されます:
const { event, code, message } =
await amplitude.track("Sign Up Clicked").promise;
eventは、送信された最後のイベントです。codeサーバーの応答またはmessageSDKから来ます:
code | message | 意味 | SDKの機能 |
|---|---|---|---|
200 | Event tracked successfully | Amplitudeはイベントを受け入れました。 | キューからイベントを削除します。 |
400 | サーバーエラーテキスト(例:) Invalid API key: ... | Amplitudeは、イベントまたはリクエスト全体を拒否しました。 | サーバーが無効とマークしたイベントをドロップし、残りのイベントを再試行します。 |
400 | Event rejected due to missing API key | init() 空のAPIキーを受け取りました。 | イベントを破棄します。 |
413 | サーバーエラーテキスト | リクエストが大きすぎます。 | 半分に減らしてflushQueueSize再試行します。 まだ大きすぎる単一のイベントをDROPします。 |
429 | サーバーエラーテキスト | ユーザーまたはデバイスがレート制限を超えました。 | 毎日の割り当て量を超えたユーザーまたはデバイスのイベントをドロップします。 30秒後にスロットリングされたイベントを再試行します。 |
500 | Event rejected due to exceeded retry count | アップロードはflushMaxRetries(5)回数失敗しました。ネットワークエラー、ブロックされたリクエスト、サーバーエラーはここで終了します。 | イベントを破棄します。 |
0 | Event skipped due to optOut config | オプトアウトがオンになっています。 | イベントを送信しません。 |
0 | Event skipped due to empty event type | イベント名は空です。 | イベントを送信しません。 |
100 | Event not tracked, no destination plugins on the instance | amplitude送信先を削除しました。 | イベントを送信しません。 |
成功したレスポンスボディは次のようになります。
{
"code": 200,
"events_ingested": 1,
"payload_size_bytes": 412,
"server_upload_time": 1761480012612
}
200レスポンスは、Amplitudeのingestion APIがイベントを受け入れたことを意味します。 Amplitudeは、受け入れられたイベントを後で分析から除外できます。たとえば、ブロックフィルタが一致した場合などです。
手動フラッシュは、
amplitude.flush()キューイングされたすべてのイベントを一度だけ送信し、失敗の再試行を行いません。各イベントの promise は、レスポンスのステータスとボディをメッセージとして解決します(例:success: {"code": 200, ...}またはinvalid: {...})。 スケジュール済みのアップロードでは、再試行を行い、表内のメッセージを使用します。
Amplitudeでイベントを検索します。
- ユーザー検索を開き、イベントの
user_idを検索します。または、ユーザーが匿名である場合はdevice_idを検索します。 - アクティビティタブを選択し、ライブイベントの更新をオンにします。
- イベントを開き、そのプロパティを
Final event before destinationslog行と比較します。
多くのユーザーからのイベントについては、Ingestion Debuggerを使用して、プロジェクトに対して許可されたリクエストと拒否されたリクエストを確認します。 Amplitudeのチャートクエリに新しいイベントが含まれるまでに、ユーザー検索よりも数分長くかかることがあります。
これは役に立ちましたか?
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.