Часть 2 из 3 по отладке Attribution Reporting. Настройте свои отладочные отчеты.
Глоссарий
- 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.exampleas 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
typefield 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 разрешен в контексте (странице), где выполняется проверка.
(Не требуется на этапе тестирования: проверьте, установлена ли политика разрешений )
Устранение фундаментальных проблем интеграции
Хотя отчеты об отладке полезны для обнаружения и анализа потерь в масштабе, некоторые проблемы интеграции можно обнаружить локально. Проблемы с неправильной конфигурацией заголовка источника и триггера, проблемы с анализом JSON, небезопасный контекст (не HTTPS) и другие проблемы, которые мешают функционированию API, будут отображены на вкладке «Проблемы» DevTools .
Проблемы DevTools могут быть разных типов. Если вы столкнулись с проблемой invalid header , скопируйте заголовок в инструмент проверки заголовка . Это поможет вам определить и исправить поле, вызывающее проблему.
Проверка заголовков отчетов об атрибуции
Вы можете использовать валидатор заголовков для проверки заголовков, связанных с API Attribution Reporting. Вы можете отслеживать ошибки валидации, возникающие в браузере, чтобы облегчить отладку 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
Обратите внимание, что отчеты об отладке можно включить для браузеров в режиме B , где сторонние файлы cookie отключены для упрощения тестирования и подготовки к устареванию сторонних файлов cookie. Для браузеров в режиме B вам не нужно устанавливать файл cookie отладки, чтобы включить отчеты об отладке. Перейдите к шагу 2, чтобы настроить ключи отладки для успешных отчетов об отладке.
Шаг 2: Установите ключи отладки
Каждый ключ отладки должен быть 64-битным целым числом без знака, отформатированным как строка с основанием 10. Сделайте каждый ключ отладки уникальным идентификатором. Отчет об успешной отладке будет создан только в том случае, если установлены ключи отладки.
- Сопоставьте ключ отладки на стороне источника с дополнительной информацией о времени источника, которая, по вашему мнению, важна для отладки.
- Сопоставьте ключ отладки на стороне триггера с дополнительной информацией о времени триггера, которая, по вашему мнению, важна для отладки.
Например, вы можете установить следующие ключи отладки:
- Идентификатор cookie-файла + временная метка источника в качестве ключа отладки источника (и захват этой же временной метки в вашей системе на основе cookie-файлов)
- Идентификатор cookie-файла + временная метка триггера в качестве ключа отладки триггера (и захват этой же временной метки в вашей системе на основе cookie-файлов)
С этим вы можете использовать информацию о конверсиях на основе cookie для поиска соответствующих отчетов об отладке или отчетов об атрибуции. Узнайте больше в Части 3: Cookbook .
Сделайте ключ отладки на стороне источника отличным от 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в своем браузере. - Убедитесь, что флажок «Показать отладочные отчеты» установлен на вкладках «Отчеты на уровне событий» и « Объединяемые отчеты» .
- Откройте сайты, на которых вы внедрили Attribution Reporting. Выполните шаги, которые вы используете для создания отчетов по атрибуции; эти же шаги сгенерируют отчеты об успешной отладке.
- В
chrome://attribution-internals:- Проверьте правильность формирования отчетов об атрибуции.
- На вкладке Event-Level Reports и вкладке Aggregatable Reports проверьте, что отчеты об успешной отладке также генерируются. Распознайте их в списке по синему пути
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в своем браузере. - Запустите атрибуцию (конвертацию) на вашем сайте, настроенном с помощью Attribution Reporting. Учитывая, что до этой конверсии не было взаимодействия с рекламой (показа или клика), следует ожидать, что будет сгенерирован подробный отчет об отладке типа
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).