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

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

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

Инструкция: Анализ потерь и устранение неполадок в вашей интеграции.

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

Обзор

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

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

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

Вы получаете отчеты об атрибуции?

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

Поскольку у вас 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 может указывать на ошибку в браузере или сетевую ошибку. Если вы сталкиваетесь с этим неоднократно, сообщите об ошибке разработчикам браузера.