Настройка отчетов об отладке для отчетов по атрибуции

Часть 2 из 3 по отладке Attribution Reporting. Настройте свои отладочные отчеты.

Глоссарий

  • Источник отчетов — это источник , который устанавливает источник отчетов об атрибуции и заголовки триггеров . Все отчеты, созданные браузером, отправляются в этот источник. В этом руководстве мы используем https://adtech.example в качестве примера источника сообщения.
  • Отчет об атрибуции (сокращенно отчет ) – это окончательный отчет (на уровне событий или агрегированный), содержащий запрошенные вами данные измерений.
  • Отчет об отладке содержит дополнительные данные об отчете об атрибуции или об источнике или событии-триггере. Получение отчета об отладке не обязательно означает, что что-то работает неправильно! Существует два типа отчетов об отладке.
  • Переходный отчет об отладке — это отчет об отладке, для создания и отправки которого требуется установка файла cookie. Отчеты о переходной отладке будут недоступны, если файл cookie не установлен, а также если сторонние файлы cookie устарели. Все отчеты об отладке, описанные в этом руководстве, являются отчетами об отладке переходного периода.
  • Отчеты об успешной отладке отслеживают успешное создание отчета об атрибуции . Они относятся непосредственно к отчету об атрибуции. Отчеты об успешной отладке доступны начиная с Chrome 101 (апрель 2022 г.).
  • Подробные отчеты об отладке позволяют отслеживать отсутствующие отчеты и помогают определить причину их отсутствия. Они указывают на случаи, когда браузер не записал событие источника или триггера (что означает, что он не будет генерировать отчет об атрибуции), а также случаи, когда отчет об атрибуции не может быть создан или отправлен по какой-либо причине. Подробные отчеты об отладке включают поле type , описывающее причину, по которой исходное событие, событие-триггер или отчет об атрибуции не был создан. Подробные отчеты об отладке доступны начиная с Chrome 109 ( стабильная версия — январь 2023 г. ).
  • Ключи отладки — это уникальные идентификаторы, которые вы можете установить как на стороне источника, так и на стороне триггера. Ключи отладки позволяют сопоставлять конверсии на основе файлов cookie и конверсии на основе атрибуции. Когда вы настроите свою систему для создания отчетов об отладке и установки ключей отладки, браузер будет включать эти ключи отладки во все отчеты об атрибуции и отчеты об отладке.

Дополнительные понятия и ключевые термины, используемые в нашей документации, см. в глоссарии Privacy Sandbox .

,
  • Источник отчетов — это источник , который устанавливает источник отчетов об атрибуции и заголовки триггеров . Все отчеты, созданные браузером, отправляются в этот источник. В этом руководстве мы используем https://adtech.example в качестве примера источника сообщения.
  • Отчет об атрибуции (сокращенно отчет ) – это окончательный отчет (на уровне событий или агрегированный), содержащий запрошенные вами данные измерений.
  • Отчет об отладке содержит дополнительные данные об отчете об атрибуции или об источнике или событии-триггере. Получение отчета об отладке не обязательно означает, что что-то работает неправильно! Существует два типа отчетов об отладке.
  • Переходный отчет об отладке — это отчет об отладке, для создания и отправки которого требуется установка файла cookie. Отчеты о переходной отладке будут недоступны, если файл cookie не установлен, а также если сторонние файлы cookie устарели. Все отчеты об отладке, описанные в этом руководстве, являются отчетами об отладке переходного периода.
  • Отчеты об успешной отладке отслеживают успешное создание отчета об атрибуции . Они относятся непосредственно к отчету об атрибуции. Отчеты об успешной отладке доступны начиная с Chrome 101 (апрель 2022 г.).
  • Подробные отчеты об отладке позволяют отслеживать отсутствующие отчеты и помогают определить причину их отсутствия. Они указывают на случаи, когда браузер не записал событие источника или триггера (что означает, что он не будет генерировать отчет об атрибуции), а также случаи, когда отчет об атрибуции не может быть создан или отправлен по какой-либо причине. Подробные отчеты об отладке включают поле type , описывающее причину, по которой исходное событие, событие-триггер или отчет об атрибуции не был создан. Подробные отчеты об отладке доступны начиная с Chrome 109 ( стабильная версия — январь 2023 г. ).
  • Ключи отладки — это уникальные идентификаторы, которые вы можете установить как на стороне источника, так и на стороне триггера. Ключи отладки позволяют сопоставлять конверсии на основе файлов cookie и конверсии на основе атрибуции. Когда вы настроите свою систему для создания отчетов об отладке и установки ключей отладки, браузер будет включать эти ключи отладки во все отчеты об атрибуции и отчеты об отладке.

Дополнительные понятия и ключевые термины, используемые в нашей документации, см. в глоссарии Privacy Sandbox .

Вопросы по реализации?

Если у вас возникли какие-либо проблемы при настройке отчетов об отладке, создайте проблему в нашем репозитории поддержки разработчиков , и мы поможем вам устранить неполадки.

Подготовка к настройке отладочных отчетов

Перед настройкой отладочных отчетов выполните следующие действия:

Убедитесь, что вы применили лучшие практики для интеграции 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: Подтвердите, что ваша установка будет генерировать подробные отладочные отчеты

Хотя существует множество типов подробных отчетов об отладке, достаточно проверить настройку подробных отчетов об отладке только с одним типом подробных отчетов об отладке. Если этот тип подробных отчетов об отладке правильно сгенерирован и получен, это означает, что все типы подробных отчетов об отладке будут также правильно сгенерированы и получены, поскольку все подробные отчеты об отладке используют одну и ту же конфигурацию и отправляются на одну и ту же конечную точку.

  1. Откройте chrome://attribution-internals в своем браузере.
  2. Запустите атрибуцию (конвертацию) на вашем сайте, настроенном с помощью Attribution Reporting. Учитывая, что до этой конверсии не было взаимодействия с рекламой (показа или клика), следует ожидать, что будет сгенерирован подробный отчет об отладке типа trigger-no-matching-source .
  3. В chrome://attribution-internals откройте вкладку Подробные отчеты отладки и убедитесь, что был создан подробный отчет отладки типа trigger-no-matching-source .
  4. На своем сервере убедитесь, что ваша конечная точка немедленно получила этот подробный отладочный отчет.

Шаг 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 ).

Далее

Часть 3: Рецепты отладки