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

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

Глоссарий

  • 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 не заблокирован политикой разрешений, запустите следующий код:

    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. Отладка кулинарной книги