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

Часть 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, будут отображаться на вкладке «Проблемы» в инструментах разработчика .

Проблемы в инструментах разработчика могут быть разных типов. Если вы столкнулись с проблемой 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 подразумевает значение true.

Отладочные отчеты немедленно отправляются на конечную точку формирования отчетов:

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-битное беззнаковое целое число, отформатированное как десятичная строка. Каждый отладочный ключ должен иметь уникальный идентификатор. Отчет об успешной отладке будет сгенерирован только в том случае, если отладочные ключи установлены.

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

Например, вы можете установить следующие отладочные клавиши:

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

// 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 запроса на эту конечную точку. Ваш серверный код для обработки входящих подробных отладочных отчетов может выглядеть следующим образом (здесь на конечной точке Node): 

// 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: Отладка по книге рецептов