このページは Cloud Translation API によって翻訳されました。

Attribution Reporting のデバッグレポートを設定する

アトリビューションレポートのデバッグに関する 3 部構成のパート 2。デバッグレポートを設定します。

用語集

The reporting origin is the origin that sets the Attribution Reporting source and trigger headers. All reports generated by the browser are sent to this origin. In this guidance, we use https://adtech.example as the example reporting origin.
An attribution report (report for short) is the final report (event-level or aggregatable) that contains the measurement data you've requested.
A debug report contains additional data about an attribution report, or about a source or trigger event. Receiving a debug report does not necessarily mean that something is working incorrectly! There are two types of debug reports
A transitional debug report is a debug report that requires a cookie to be set in order to be generated and sent. Transitional debug reports will be unavailable if a cookie is not set, and once third-party cookies are deprecated. All debug reports described in this guide are transitional debug reports.
Success debug reports track successful generation of an attribution report. They relate directly to an attribution report. Success debug reports have been available since Chrome 101 (April 2022).
Verbose debug reports can track missing reports and help you determine why they're missing. They indicate cases where the browser did not record a source or trigger event, (which means it will not generate an attribution report), and cases where an attribution report can't be generated or sent for some reason. Verbose debug reports include a type field that describes the reason why a source event, trigger event or attribution report was not generated. Verbose debug reports are available starting in Chrome 109 (Stable in January 2023).
Debug keys are unique identifiers you can set on both the source side and the trigger side. Debug keys enable you to map cookie-based conversions and attribution-based conversions. When you've set up your system to generate debug reports and set debug keys, the browser will include these debug keys in all attribution reports and debug reports.

For more concepts and key terms used throughout our documentation, refer to the Privacy Sandbox glossary.

実装に関する質問

デバッグレポートの設定中に問題が発生した場合は、デベロッパーサポートリポジトリで問題を作成してください。トラブルシューティングをお手伝いいたします。

デバッグレポートの設定の準備

デバッグレポートを設定する前に、次の手順を行います。

API 統合のベストプラクティスが適用されていることを確認する

コードが機能検出によって制限されていることを確認します。API が Permissions-Policy によってブロックされていないことを確認するには、次のコードを実行します。
```
if (document.featurePolicy.allowsFeature('attribution-reporting')) {
// the Attribution Reporting API is enabled
}
```
この機能検出チェックが true を返した場合、チェックが実行されるコンテキスト（ページ）で API が許可されます。
（テストフェーズ中は不要: Permissions-Policy が設定されていることを確認してください）

統合に関する基本的な問題を解決する

デバッグレポートは、大規模な損失を検出して分析するのに役立ちますが、一部の統合の問題はローカルで検出できます。ソースとトリガーヘッダーの構成ミス、JSON 解析の問題、安全でないコンテキスト（HTTPS 以外）、API の機能の妨げとなるその他の問題は、DevTools の [問題] タブに表示されます。

DevTools の問題にはさまざまな種類があります。invalid header の問題が発生した場合は、ヘッダーをヘッダー検証ツールにコピーします。これにより、問題の原因となっているフィールドを特定して修正できます。

アトリビューションレポートのヘッダーを検証する

ヘッダーバリデータを使用して、Attribution Reporting API に関連するヘッダーを検証できます。ブラウザから発生した検証エラーをモニタリングして、API のデバッグを容易にできます。

デバッグレポートの受信を有効にするには、Attribution-Reporting-Info レスポンスヘッダーの一部として report-header-errors を返します。

Attribution-Reporting-Info: report-header-errors

Attribution-Reporting-Info は辞書構造のヘッダーAttribution-Reporting-Info であるため、ブール値 report-header-errors キーを指定すると、true 値が暗黙的に指定されます。

デバッグレポートは、レポートエンドポイントにすぐに送信されます。

https://<reporting origin>/.well-known/attribution-reporting/debug/verbose

レポートデータは、次の形式のオブジェクトの JSON リストとしてリクエスト本文に含まれます。

[{
  "type": "header-parsing-error",
  "body": {
    "context_site": "https://source.example",
    "header": "Attribution-Reporting-Register-Source",
    "value": "!!!", // header value received in the response
    "error": "invalid JSON" // optional error details that may vary across browsers or different versions of the same browser
  }
}]

デバッグレポートを設定する: 成功レポートと詳細レポートに共通の手順

レポート送信元に次の Cookie を設定します。

Set-Cookie: ar_debug=1; SameSite=None; Secure; Path=/; HttpOnly

ブラウザは、ソースとトリガーの登録の両方でこの Cookie の存在を確認します。成功デバッグレポートは、両方のタイミングで Cookie が存在する場合にのみ生成されます。

デモコード: デバッグクッキー

デバッグレポートは、モード B のブラウザで有効にできます。このモードでは、サードパーティ Cookie のサポート終了に向けたテストと準備を容易にするために、サードパーティ Cookie が無効になっています。モード B のブラウザの場合、デバッグレポートを有効にするためにデバッグ Cookie を設定する必要はありません。ステップ 2 に進んで、成功デバッグレポートのデバッグキーを設定します。

ステップ 2: デバッグキーを設定する

各デバッグキーは、10 進数文字列としてフォーマットされた 64 ビットの符号なし整数である必要があります。各デバッグキーに一意の ID を設定します。成功デバッグレポートは、デバッグキーが設定されている場合にのみ生成されます。

ソースサイドのデバッグキーを、デバッグに関連すると思われる追加のソース時間情報にマッピングします。
トリガー側のデバッグキーを、デバッグに関連すると思われる追加のトリガー時間情報にマッピングします。

たとえば、次のデバッグキーを設定できます。

Cookie ID + ソースタイムスタンプをソースのデバッグキーとして使用（Cookie ベースのシステムで同じタイムスタンプをキャプチャ）
Cookie ID とトリガータイムスタンプをトリガーデバッグキーとして使用（Cookie ベースのシステムで同じタイムスタンプをキャプチャ）

これにより、Cookie ベースのコンバージョン情報を使用して、対応するデバッグレポートまたはアトリビューションレポートを検索できます。詳しくは、パート 3: レシピをご覧ください。

ソースサイドのデバッグキーを source_event_id と異なるものにして、同じソースイベント ID を持つ個々のレポートを区別できるようにします。

Attribution-Reporting-Register-Source:
{
// … Usual fields for Attribution-Reporting-Register-Source
"debug_key":"647775351539539"
}

Attribution-Reporting-Register-Trigger:
{
// … Usual fields for Attribution-Reporting-Register-Trigger
"debug_key":"938321351539743"
}

デモコード: ソースのデバッグキー デモコード: トリガーのデバッグキー

成功デバッグレポートを設定する

このセクションのサンプルコードは、イベントレベルと集計可能なレポートの両方の成功デバッグレポートを生成します。イベントレベルレポートと集計可能レポートでは同じデバッグキーが使用されます。

ステップ 3: 成功デバッグレポートを収集するエンドポイントを設定する

デバッグレポートを収集するエンドポイントを設定します。このエンドポイントは、メインのアトリビューションエンドポイントに似ていますが、パスに debug 文字列が追加されています。

イベントレベルの成功デバッグレポートのエンドポイント: https://adtech.example/.well-known/attribution-reporting/debug/report-event-attribution
- 成功のデバッグレポートの集約可能エンドポイント: https://adtech.example/.well-known/attribution-reporting/debug/report-aggregate-attribution

アトリビューションがトリガーされると、ブラウザは POST リクエストを使用してデバッグレポートをこのエンドポイントにすぐに送信します。受信した成功デバッグレポートを処理するサーバーコードは、次のように記述できます（ここではノードエンドポイントを使用しています）。

// Handle incoming event-Level Success Debug reports
adtech.post(
  '/.well-known/attribution-reporting/debug/report-event-attribution',
  async (req, res) => {
    // Debug report is in req.body
    res.sendStatus(200);
  }
);

// Handle incoming aggregatable Success Debug reports
adtech.post(
  '/.well-known/attribution-reporting/debug/report-aggregate-attribution',
  async (req, res) => {
    // Debug report is in req.body
    res.sendStatus(200);
  }
);

デモコード: イベントレベルのデバッグレポートエンドポイント

デモコード: 集計可能なデバッグレポートエンドポイント

ステップ 4: 設定で成功デバッグレポートが生成されることを確認する

ブラウザで chrome://attribution-internals を開きます。
[イベントレベルレポート] タブと [集計可能レポート] タブの両方で、[デバッグレポートを表示] チェックボックスがオンになっていることを確認します。
アトリビューションレポートを実装したサイトを開きます。アトリビューションレポートの生成手順を完了します。この手順と同じ手順で、成功デバッグレポートが生成されます。
chrome://attribution-internals で以下を実行します。
- アトリビューションレポートが正しく生成されていることを確認します。
- [イベントレベルレポート] タブと [集計可能なレポート] タブで、成功したデバッグレポートも生成されていることを確認します。リスト内の青い debug パスで認識できます。

サーバー上で、エンドポイントがこれらの成功デバッグレポートを直ちに受信することを確認します。イベントレベルと集計可能な成功デバッグレポートの両方を確認してください。

ステップ 5: 成功のデバッグレポートを確認する

成功デバッグレポートはアトリビューションレポートと同じで、ソースサイドとトリガーサイドのデバッグキーの両方が含まれます。

{
  "attribution_destination": "https://advertiser.example",
  "randomized_trigger_rate": 0.0000025,
  "report_id": "7d76ef29-d59e-4954-9fff-d97a743b4715",
  "source_debug_key": "647775351539539",
  "source_event_id": "760938763735530",
  "source_type": "event",
  "trigger_data": "0",
  "trigger_debug_key": "156477391437535"
}

{
  "aggregation_service_payloads": [
    {
      "debug_cleartext_payload": "omRkYXRhgqJldmFsdWVEAACAAGZidWNrZXRQPPhnkD+7c+wm1RjAlowp3KJldmFsdWVEAAARMGZidWNrZXRQJFJl9DLxbnMm1RjAlowp3GlvcGVyYXRpb25paGlzdG9ncmFt",
      "key_id": "d5f32b96-abd5-4ee5-ae23-26490d834012",
      "payload": "0s9mYVIuznK4WRV/t7uHKquHPYCpAN9mZHsUGNiYd2G/9cg87Y0IjlmZkEtiJghMT7rmg3GtWVPWTJU5MvtScK3HK3qR2W8CVDmKRAhqqlz1kPZfdGUB4NsXGyVCy2UWapklE/r7pmRDDP48b4sQTyDMFExQGUTE56M/8WFVQ0qkc7UMoLI/uwh2KeIweQCEKTzw"
    }
  ],
  "shared_info": "{\"api\":\"attribution-reporting\",\"attribution_destination\":\"https://advertiser.example\",\"debug_mode\":\"enabled\",\"report_id\":\"4a04f0ff-91e7-4ef6-9fcc-07d000c20495\",\"reporting_origin\":\"https://adtech.example\",\"scheduled_report_time\":\"1669888617\",\"source_registration_time\":\"1669852800\",\"version\":\"0.1\"}",
  "source_debug_key": "647775351539539",
  "trigger_debug_key": "156477391437535"
}

詳細なデバッグレポートを設定する

ステップ 3: ソースとトリガーヘッダーで詳細なデバッグを有効にする

Attribution-Reporting-Register-Source と Attribution-Reporting-Register-Trigger の両方で debug_reporting を true に設定します。

Attribution-Reporting-Register-Source:
{
// … Usual fields for Attribution-Reporting-Register-Source
"debug_key":"938321351539743",
"debug_reporting": true // defaults to false if not present
}

Attribution-Reporting-Register-Trigger:
{
// … Usual fields for Attribution-Reporting-Register-Trigger
"debug_key":"938321351539743",
"debug_reporting": true // defaults to false if not present
}

デモコード: ソースヘッダー

デモコード: トリガーヘッダー

ステップ 4: 詳細なデバッグレポートを収集するエンドポイントを設定する

デバッグレポートを収集するエンドポイントを設定します。このエンドポイントは、メインのアトリビューションエンドポイントに似ていますが、パスに debug/verbose 文字列が追加されています。

https://adtech.example/.well-known/attribution-reporting/debug/verbose

詳細なデバッグレポートが生成される場合（ソースまたはトリガーが登録されていない場合）、ブラウザは POST リクエストを使用して詳細なデバッグレポートをすぐにこのエンドポイントに送信します。受信した詳細なデバッグレポートを処理するサーバーコードは、次のようになります（ここではノードエンドポイント）。

// Handle incoming verbose debug reports
adtech.post(
  '/.well-known/attribution-reporting/debug/verbose',
  async (req, res) => {
    // List of verbose debug reports is in req.body
    res.sendStatus(200);
  }
);

成功デバッグレポートとは異なり、詳細レポートのエンドポイントは 1 つだけです。イベントレベルレポートと集計レポートに関連する詳細レポートはすべて、同じエンドポイントに送信されます。

デモコード: 詳細なデバッグレポートエンドポイント

ステップ 5: 設定で詳細なデバッグレポートが生成されることを確認する

詳細デバッグレポートには多くの種類がありますが、詳細デバッグレポートの1 種類だけで詳細デバッグ設定を確認できます。この 1 種類の詳細なデバッグレポートが正しく生成されて受信された場合、すべての種類の詳細なデバッグレポートも正しく生成されて受信されます。これは、すべての詳細なデバッグレポートが同じ構成を使用し、同じエンドポイントに送信されるためです。

キーポイント: テストが容易な詳細なデバッグレポートを選択します。trigger-no-matching-source は、変換によって生成できるため、適切な候補です。トリガーイベントに関連する詳細レポートは、より適切な候補です。ソースイベントに関連する詳細レポートタイプは、意図的に生成するのが面倒です。

ブラウザで chrome://attribution-internals を開きます。
アトリビューションレポートで設定されているサイトでアトリビューション（コンバージョン）をトリガーします。このコンバージョンの前に広告エンゲージメント（インプレッションまたはクリック）がなかったため、trigger-no-matching-source タイプの詳細なデバッグレポートが生成されます。
chrome://attribution-internals で [詳細なデバッグレポート] タブを開き、trigger-no-matching-source タイプの詳細なデバッグレポートが生成されていることを確認します。
サーバーで、エンドポイントがこの詳細なデバッグレポートをすぐに受け取ったことを確認します。

ステップ 6: 詳細なデバッグレポートを確認する

トリガー時に生成される詳細なデバッグレポートには、ソースサイドとトリガーサイドのデバッグキーの両方が含まれます（トリガーに一致するソースがある場合）。ソース時生成の詳細なデバッグレポートには、ソースサイドのデバッグキーが含まれます。

ブラウザから送信された、詳細なデバッグレポートを含むリクエストの例:

[
  {
    "body": {
      "attribution_destination": "http://arapi-advertiser.localhost",
      "randomized_trigger_rate": 0.0000025,
      "report_id": "92b7f4fd-b157-4925-999e-aad6361de759",
      "source_debug_key": "282273499788483",
      "source_event_id": "480041649210491",
      "source_type": "event",
      "trigger_data": "1",
      "trigger_debug_key": "282273499788483"
    },
    "type": "trigger-event-low-priority"
  },
  {
    "body": {
      "attribution_destination": "http://arapi-advertiser.localhost",
      "limit": "65536",
      "source_debug_key": "282273499788483",
      "source_event_id": "480041649210491",
      "source_site": "http://arapi-publisher.localhost",
      "trigger_debug_key": "282273499788483"
    },
    "type": "trigger-aggregate-insufficient-budget"
  }
]

各詳細レポートには、次のフィールドが含まれています。

Type: レポートが生成された原因。すべての詳細レポートの種類と、各種類に応じた対処方法については、パート 3: デバッグレシピの詳細レポートの参照をご覧ください。
Body: レポートの本文。タイプによって異なります。パート 3: デバッグクックブックの詳細レポートリファレンスを確認する。

リクエストの本文には、少なくとも 1 つ、最大 2 つの詳細レポートが含まれます。

エラーがイベントレベルレポートにのみ影響する場合（または集計可能レポートにのみ影響する場合）は、詳細レポートが 1 つ生成されます。ソースまたはトリガーの登録エラーの原因は 1 つだけであるため、エラーとレポートタイプ（イベントレベルまたは集計可能）ごとに詳細レポートを 1 つ生成できます。
2 つの詳細レポート（例: trigger-no-matching-source）: 障害がイベントレベルレポートと集計可能レポートの両方に影響する場合。ただし、イベントレベルレポートと集計可能レポートの障害理由が同じ場合は、詳細レポートが 1 つだけ生成されます。

次の動画

パート 3: デバッグクックブック

Attribution Reporting のデバッグ レポートを設定する コレクションでコンテンツを整理 必要に応じて、コンテンツの保存と分類を行います。

用語集

実装に関する質問

デバッグ レポートの設定の準備

アトリビューション レポートのヘッダーを検証する

デバッグ レポートを設定する: 成功レポートと詳細レポートに共通の手順

成功デバッグ レポートを設定する

詳細なデバッグ レポートを設定する