Часть 2 из 3, посвященная отладке отчетов по атрибуции. Настройте отчеты об отладке.
Глоссарий
- 报告来源是用于设置归因报告来源和触发器标头的来源。浏览器生成的所有报告都会发送到此源。在本指南中，我们使用
https://adtech.example作为示例报告来源。 - 归因报告（简称“报告”）是包含您请求的衡量数据的最终报告（事件级报告或可汇总报告）。
- 调试报告包含有关归因报告或者来源或触发器事件的其他数据。收到调试报告并不一定表示存在问题！调试报告有两种
- 过渡调试报告是一种调试报告，需要设置 Cookie 才能生成和发送。如果 Cookie 未设置且第三方 Cookie 被弃用，过渡调试报告将不可用。本指南中描述的所有调试报告都是过渡性调试报告。
- 成功调试报告用于跟踪成功生成归因报告。它们与归因报告直接相关。从 Chrome 101（2022 年 4 月）开始，已提供成功调试报告。
- 详细调试报告可以跟踪缺失的报告，并帮助您确定缺失报告的原因。它们分别用于表明浏览器未记录来源或触发器事件（这意味着浏览器不会生成归因报告）以及由于某种原因无法生成或发送归因报告的情况。详细调试报告包含一个
type字段，用于说明未生成来源事件、触发器事件或归因报告的原因。从 Chrome 109（2023 年 1 月稳定版）开始提供详细调试报告。 - 调试键是您可以在来源端和触发器端设置的唯一标识符。通过调试键，您可以映射基于 Cookie 的转化和基于归因的转化。将系统设置为生成调试报告并设置调试密钥后，浏览器会将这些调试密钥添加到所有归因报告和调试报告中。
如需了解我们的文档中使用的更多概念和关键术语，请参阅 Privacy Sandbox 术语表。
Вопросы по реализации?
Если при настройке отчетов об отладке у вас возникнут какие-либо проблемы, создайте проблему в нашем репозитории поддержки разработчиков , и мы поможем вам устранить неполадки.
Подготовьтесь к настройке отчетов об отладке
Прежде чем настраивать отчеты об отладке, выполните следующие действия:
Убедитесь, что вы применили лучшие практики для интеграции API.
Убедитесь, что ваш код защищен обнаружением функций. Чтобы убедиться, что API не заблокирован политикой разрешений, запустите следующий код:
if (document.featurePolicy.allowsFeature('attribution-reporting')) { // the Attribution Reporting API is enabled }Если эта проверка обнаружения функции возвращает значение true, API разрешен в контексте (странице), где выполняется проверка.
(Не требуется на этапе тестирования: убедитесь, что вы установили политику разрешений )
Устранение фундаментальных проблем интеграции
Хотя отчеты об отладке полезны для обнаружения и анализа потерь в масштабе, некоторые проблемы интеграции можно обнаружить локально. Проблемы с неправильной конфигурацией заголовков источника и триггера, проблемы с анализом JSON, небезопасный контекст (не HTTPS) и другие проблемы, которые мешают функционированию API, будут отображаться на вкладке «Проблемы DevTools» .
Проблемы DevTools могут быть разных типов. Если вы столкнулись с проблемой invalid header , скопируйте его в инструмент проверки заголовков . Это поможет вам определить и исправить поле, вызывающее проблему.
Проверка заголовков отчетов об атрибуции
Вы можете использовать средство проверки заголовков для проверки заголовков, связанных с API отчетов по атрибуции. Вы можете отслеживать ошибки проверки, возникающие в браузере, чтобы облегчить отладку API.
Чтобы согласиться на получение отчетов об отладке, укажите в ответе report-header-errors как часть заголовка ответа Attribution-Reporting-Info.
Attribution-Reporting-Info: report-header-errors
Обратите внимание, что Attribution-Reporting-Info представляет собой словарный структурированный заголовок Attribution-Reporting-Info , поэтому предоставление логического ключа report-header-errors подразумевает истинное значение.
Отчеты об отладке немедленно отправляются в конечную точку отчетов:
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 присутствует оба раза.
Демо-код: отладочный файл cookie
Обратите внимание, что отчеты об отладке можно включить для браузеров в режиме B , где сторонние файлы cookie отключены, чтобы облегчить тестирование и подготовку к прекращению поддержки сторонних файлов cookie. Для браузеров в режиме B вам не нужно устанавливать файл cookie отладки, чтобы включить отчеты об отладке. Перейдите к шагу 2, чтобы настроить ключи отладки для отчетов об успешной отладке.
Шаг 2. Установите ключи отладки
Каждый ключ отладки должен представлять собой 64-битное целое число без знака, отформатированное как строка с основанием 10. Сделайте каждый ключ отладки уникальным идентификатором. Отчет об успешной отладке будет создан только в том случае, если установлены ключи отладки.
- Сопоставьте ключ отладки на стороне исходного кода с дополнительной информацией о времени исходного кода, которую вы считаете актуальной для отладки.
- Сопоставьте ключ отладки на стороне триггера с дополнительной информацией о времени триггера, которую вы считаете важной для отладки.
Например, вы можете установить следующие ключи отладки:
- Идентификатор файла cookie + временная метка источника в качестве ключа отладки источника (и сохранить эту же временную метку в вашей системе на основе файлов cookie).
- Идентификатор файла cookie + временная метка триггера в качестве ключа отладки триггера (и запись этой же временной метки в вашу систему на основе файлов cookie)
При этом вы можете использовать информацию о конверсиях на основе файлов cookie для поиска соответствующих отчетов об отладке или отчетов об атрибуции. Узнайте больше в Части 3: Поваренная книга .
Сделайте ключ отладки на стороне источника отличным от source_event_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. Включите подробную отладку в заголовках источника и триггера.
Установите для debug_reporting значение true как в Attribution-Reporting-Register-Source , так и в Attribution-Reporting-Register-Trigger .
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);
}
);
В отличие от отчетов об успешной отладке, для подробных отчетов существует только одна конечная точка. Подробные отчеты, относящиеся к уровням событий, и агрегированные отчеты будут отправляться в одну и ту же конечную точку.
Демонстрационный код: конечная точка подробных отчетов об отладке
Шаг 5. Убедитесь, что ваша установка будет генерировать подробные отчеты об отладке.
Хотя существует множество типов подробных отчетов об отладке, достаточно проверить настройку подробной отладки только с одним типом подробного отчета об отладке. Если этот тип подробного отчета об отладке правильно создан и получен, это означает, что все типы подробных отчетов об отладке также будут правильно созданы и получены, поскольку все подробные отчеты об отладке используют одну и ту же конфигурацию и отправляются в одну и ту же конечную точку.
- Откройте
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: Книга рецептов отладки .
Тело запроса будет содержать как минимум один и максимум два подробных отчета:
- Один подробный отчет, если сбой затрагивает только отчеты на уровне событий (или если он затрагивает только агрегированные отчеты). Ошибка регистрации источника или триггера имеет только одну причину; следовательно, для каждого сбоя и типа отчета (на уровне события или агрегируемого) может быть создан один подробный отчет.
- Два подробных отчета, если сбой затрагивает как отчеты на уровне событий, так и агрегированные отчеты, за исключением: если причина сбоя одинакова для отчетов на уровне событий и агрегированных отчетов, создается только один подробный отчет (пример:
trigger-no-matching-source)