Рецепты отладки отчетов об атрибуции

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

В этой кулинарной книге вы найдете инструкции по использованию отладочных отчетов для различных вариантов использования, описанных в Части 1: Введение в отладочные отчеты .

Глоссарий

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

Как: Проверьте свою интеграцию в режиме реального времени

  1. Настройте свою систему для генерации отчетов об успешной отладке . Смотрите, как это сделать в Части 2: Настройка отчетов об отладке .
  2. Всякий раз, когда вы развертываете код Attribution Reporting, проверяйте в реальном времени, получаете ли вы какие-либо отчеты об успешной отладке на вашей конечной точке. Если это так, ваша настройка Attribution Reporting работает.
  3. Отчеты об успешной отладке отправляются только при выполнении преобразования. Вместо этого вы можете проверить, что ваша интеграция настроена правильно независимо от преобразований, то есть вы хотите проверить, что источники успешно зарегистрированы. Для этого вы можете положиться на отчеты об успешной регистрации источника . Смотрите, как их настроить в Части 2: Настройка отчетов об отладке .

Как: Анализ потерь и устранение неполадок интеграции

Чтобы сравнить результаты измерения конверсий на основе cookie с отчетами Attribution Reporting, используйте ключи отладки и сопоставьте конверсии cookie с отчетами отладки. Помните, что отчеты отладки немедленно отправляются на вашу конечную точку.

Обзор

Шаги для анализа убытков
Шаги для анализа убытков

Используйте ключи отладки (пара <source_debug_key, trigger_debug_key> ) для сопоставления преобразований cookie с отчетами об успешной отладке. Для каждого преобразования cookie во время преобразования вы получили соответствующий отчет об успешной отладке?

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

Если нет : это означает, что преобразование не зарегистрировано в Attribution Reporting. Используйте пару <source_debug_key, trigger_debug_key> (или исходный ключ отладки, если ключ отладки триггера отсутствует) для сопоставления преобразований cookie с подробными отчетами отладки. Для каждого из этих преобразований вы в какой-то момент (время источника или триггера) получили соответствующий подробный отчет отладки?

  • Если вы не получили отчет отладки в словесном порядке: это может быть связано с поведением пользователя или проблемой интеграции. Просмотрите сценарий отчета об отсутствии отладки для получения подробной информации.

  • Если вы получили подробный отладочный отчет, проверьте его поле type .

    • Если его type — source-success : это означает, что источник был успешно зарегистрирован, но триггер — нет. Чтобы сузить причину отсутствия отчета об успешной отладке, найдите соответствующий подробный отчет об отладке любого другого типа⏤такой отчет укажет на проблему на стороне триггера.

    • Если его type какой-либо другой: источник или триггер не был зарегистрирован. type сообщает вам, почему. Соответствующий отчет об атрибуции (и отчет об успешной отладке) будет отсутствовать. В зависимости от type подробного отчета об отладке вы можете просто принять эту информацию как точку данных анализа потерь (другими словами, никаких действий с вашей стороны) или вы можете захотеть зарегистрировать ошибку или устранить неполадки в вашей реализации. Ознакомьтесь со сценарием подробного отчета об отладке для получения подробной информации.

Возможные сценарии

Отчет об успешной отладке

Если для определенного преобразования cookie вы получили отчет об успешной отладке, это означает, что данное преобразование было успешно зарегистрировано в Attribution Reporting.

Вы можете рассчитывать получить позже отчет об атрибуции для этой конверсии ⏤за некоторыми исключениями:

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

Подробный отладочный отчет типа source-success

Если для источника данного преобразования cookie вы получили подробный отладочный отчет типа source-success , это означает, что регистрация источника прошла успешно. В зависимости от того, будет ли регистрация триггера также впоследствии успешной, вы можете получить или не получить отчет для этого преобразования.

Но есть одно предостережение:

Подробный отладочный отчет любого другого типа

Если для данного преобразования cookie вы получили подробный отладочный отчет любого другого типа, вы не получите отладочный отчет об успешном завершении, и, следовательно, позже не получите отчет об атрибуции⏤, поскольку подробный отчет означает, что произошел отчетный сбой. Что-то помешало регистрации источника, регистрации триггера, генерации отчета или отправке отчета. Возможные причины:

  • Ограничения конфиденциальности
  • Ограничения по хранению
  • Пользовательские правила
  • Проблема реализации в вашем коде
  • Ошибка браузера

Некоторые из них ожидаемы! Какие действия следует предпринять, зависит от type каждого подробного отчета. Ознакомьтесь со справкой по подробным отчетам .

Нет отладочных отчетов

Если для данного преобразования cookie вы получили только отчет об атрибуции (отчет об успешной отладке и подробный отчет об отладке отсутствуют), это означает, что что-то помешало созданию отчетов об отладке. Возможные причины:

  • Настройки пользователя (пользователь отключил сторонние файлы cookie)
  • Отсутствует файл cookie или отсутствуют ключи отладки (ключ отладки очищен из-за отсутствующего файла cookie). В chrome://attribution-internals откройте вкладку Logs и проверьте, не обнаружена ли там какая-либо проблема.
  • Проблемы с сетью, возникшие в момент возникновения источника или срабатывания триггера, но не в момент отправки отчета об атрибуции.

Получаете ли вы отчеты об атрибуции?

Это подслучай неполучения отчета об отладке: если для определенного преобразования cookie вы не получили никаких отчетов (никакого отчета об отладке, никакого отчета об атрибуции), это означает, что произошел не подлежащий отчету сбой. Возможные причины:

Подробная справочная информация по отладочным отчетам

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

Успешная регистрация источника

Источник успешно зарегистрирован.

source-success
Подробности и текст отчета

Отчеты об ограничениях конфиденциальности

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

source-destination-limit
Подробности и текст отчета
source-noised
Подробности и текст отчета
trigger-attributions-per-source-destination-limit
Подробности и текст отчета
trigger-reporting-origin-limit
Подробности и текст отчета
trigger-event-noise
Подробности и текст отчета
trigger-event-excessive-reports
Это генерируется, если количество отчетов превышает лимит; вы можете зарегистрировать максимум одну конверсию для просмотров и три для кликов. Обратите внимание, что вы можете настроить, какие отчеты получать, установив приоритеты . Подробности и текст отчета

Отчеты об ограничениях хранения

Эти отчеты ожидаемы. Они указывают ограничения хранилища для предотвращения чрезмерного использования ресурсов.

source-storage-limit
Подробности и текст отчета
trigger-event-storage-limit
Подробности и текст отчета
trigger-aggregate-storage-limit
Подробности и текст отчета

Отчеты по пользовательским правилам

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

trigger-no-matching-filter-data
Подробности и текст отчета
trigger-event-no-matching-configuration
Подробности и текст отчета
trigger-event-deduplicated
Подробности и текст отчета
trigger-aggregate-deduplicated
Подробности и текст отчета
trigger-event-low-priority
Подробности и текст отчета
trigger-event-report-window-passed
Подробности и текст отчета
trigger-aggregate-report-window-passed
Подробности и текст отчета

Другие подробные отчеты

Эти отчеты могут указывать на потенциальные проблемы реализации вашего кода.

trigger-no-matching-source
Это может быть проблемой реализации. Проверьте, нет ли неправильной конфигурации в вашей настройке <reporting origin, destination> . Это также может быть ожидаемым поведением API. Например, пользователь очистил данные в какой-то момент после взаимодействия с рекламой и до конвертации, или пользователь совершил конвертацию, не увидев связанной рекламы. Подробности и текст отчета
trigger-aggregate-no-contributions
Это, скорее всего, не то поведение, которое вы хотели бы видеть в своем коде. Устраните неполадки в коде регистрации триггера; убедитесь, что конфигурация вашего вклада верна. Подробности и текст отчета
trigger-aggregate-insufficient-budget
Это, скорее всего, не то поведение, которое вы хотели бы видеть в своем коде. Дважды проверьте код регистрации триггера, чтобы убедиться, что сумма всех взносов не превышает бюджет взносов. Подробности и текст отчета

Неожиданные ошибки (потенциальные ошибки браузера)

Эти отчеты неожиданны . Они могут быть вызваны ошибкой браузера! Сообщите об ошибке и укажите в описании шаги для ее воспроизведения.

source-unknown-error
Подробности и текст отчета
trigger-unknown-error
Подробности и текст отчета

Пример анализа потерь

Шаг 1: Настройка и сопоставление с файлами cookie

Следуйте инструкциям в Части 2: Настройка отчетов об отладке, чтобы настроить систему на создание отчетов об успешном выполнении отладки и подробных отчетов об отладке .

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

Шаг 2: Определите успешные регистрации и недостающие отчеты

В этом примере предположим, что вы отследили 100 конверсий с помощью системы на основе cookie-файлов.

Каждый раз, когда вы регистрируете преобразование на основе cookie, ищите отчет об успешной отладке (отправляется немедленно), в котором указана та же пара <source_debug_key, trigger_debug_key> что и в этом преобразовании на основе cookie.

Предположим, вы получили отчет об успешной отладке для 70 из этих преобразований cookie-файлов.

  • Отчеты об успешном выполнении означают, что атрибуция была успешно зарегистрирована, поэтому вы можете с уверенностью предположить, что получите отчет об атрибуции, соответствующий каждому отчету об успешном выполнении — за некоторыми исключениями.
  • Вы можете принять решение о мониторинге этих исключений. Для этого, поскольку отчеты об атрибуции отправляются на вашу конечную точку в течение следующих дней или недель (в зависимости от срока действия), найдите отчеты об атрибуции, которые имеют ту же пару ключей отладки, что и каждый отчет об успешной отладке. Обязательно подождите немного: отчеты могут не отправляться немедленно в конце каждого окна. Предположим, что вы нашли только 60 отчетов об атрибуции. 10 отсутствующих отчетов об атрибуции могут быть связаны с поведением пользователя.

Шаг 3: Краткая оценка убытков

100-70 = 30 успешных отчетов об отладке отсутствуют. Это означает, что эти 30 конверсий (которые отслеживались в вашей реализации на основе cookie) не были зарегистрированы с помощью Attribution Reporting. Вы не будете получать для них отчеты об атрибуции.

Поскольку у вас 100 конверсий на основе cookie и только 70 конверсий на основе атрибуции, ваши потери составляют 30%. Теперь у вас есть краткая оценка потерь.

Шаг 4: Анализ причин

Чтобы выяснить, почему эти отчеты отсутствуют, найдите соответствующие подробные отчеты отладки, которые вы получили во время преобразования (регистрации триггера) или ранее во время регистрации источника. Используйте ключи преобразований на основе cookie, чтобы сопоставить их с подробными отчетами отладки.

  • Предположим, что есть 10 ключей, для которых нет подробного отладочного отчета. Проверьте, нет ли проблем с интеграцией. Если нет, это может быть связано с поведением пользователя.
  • У вас есть 20 подробных отчетов об отладке. Теперь вы можете уточнить свой анализ потерь. Проанализируйте поле type каждого подробного отчета. Например, вы можете обнаружить, что:
    • 10 (= 10% в нашем примере) отчетов отсутствуют из-за pending destination limit
    • 5 (= 5%) отчетов отсутствуют из-за trigger-aggregate-no-contributions .
    • 5 (= 5%) отчетов отсутствуют из-за unknown-error .

Шаг 5: Примите меры и устраните неполадки

Теперь, когда вы получили представление о причинах отсутствия отчетов, вы можете действовать на основе этих сведений.

Какие действия следует предпринять, зависит от type каждого подробного отчета. Ознакомьтесь со справкой по подробным отчетам для получения подробной информации. Например:

  • pending-destination-limit — это защита конфиденциальности. Никаких действий предпринимать не нужно. Используйте это число как точку данных для собственной видимости и мониторинга.
  • trigger-aggregate-no-contributions может быть признаком проблемы с реализацией на вашей стороне. Проанализируйте это подробнее. Используйте данные в тексте подробного отчета для устранения неполадок и исправления, если необходимо.
  • unknown-error может быть признаком ошибки браузера или сетевой ошибки. Если вы постоянно сталкиваетесь с этим, отправьте сообщение об ошибке разработчикам браузера.