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

Часть 2 из 3, посвященная отладке отчетов по атрибуции. Настройте отчеты об отладке.

Глоссарий

  • Источник отчетов — это источник , который устанавливает источник отчетов об атрибуции и заголовки триггеров . Все отчеты, созданные браузером, отправляются в этот источник. В этом руководстве мы используем 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 не заблокирован политикой разрешений, запустите следующий код:

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

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

  1. Откройте chrome://attribution-internals в своем браузере.
  2. Запустите атрибуцию (конверсию) на своем сайте, настроенном с помощью отчетов об атрибуции. Учитывая, что до этой конверсии не было взаимодействия с рекламой (показа или клика), следует ожидать, что будет создан подробный отчет об отладке типа 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. Отладка кулинарной книги