Генерация отчетов об атрибуции

В этой статье объясняется, как генерируются отчеты Attribution Reporting API — как отчеты об атрибуции, так и отчёты отладки — и как вы можете управлять генерируемыми отчётами. Это включает обработку шума, приоритизацию отчетов, фильтрацию отчетов и генерацию отчетов отладки.

При совпадении триггера и источника браузер генерирует отчет и отправляет его посредством незащищенного POST запроса к определённому конечной точке на происхождении отчета:

• Для отчетов на уровне события это <reporting-origin>/.well-known/attribution-reporting/report-event-attribution.
• Для сводных отчетов это <reporting-origin>/.well-known/attribution-reporting/report-aggregate-attribution.

Конечная точка <reporting-origin> будет иметь тот же домен, что и тот, который зарегистрировал источник и триггер.

Данные отчета содержатся в структуре JSON.

Отчеты на уровне событий генерируются и планируются для отправки в конце содержащего их окна отчета. Длительность окна отчета определяется значениями, установленными в "event_report_window" или "event_report_windows" поле, установленное в заголовке источника Attribution-Reporting-Register-Source.

Если ни одно из этих полей не указано, окно отчета возвращается к следующим значениям по умолчанию:

• Для источников на основе событий окно отчета заканчивается по истечении срока действия источника, который установлен в поле Attribution-Reporting-Register-Source "expiry". По умолчанию это 30 дней после регистрации, если не установлено явно.
• Для источников на основе навигации значения по умолчанию для окон отчета составляют 2 дня, 7 дней и "expiry" источника.

Для получения дополнительной информации см. Персонализированные окна отчетов.

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

{
  "attribution_destination": "https://advertiser.example",
  "source_event_id": "412444888111012",
  "trigger_data": "4",
  "report_id": "123e4567-e89b-12d3-a456-426614174000",
  "source_type": "navigation",
  "randomized_trigger_rate": 0.34,
  "scheduled_report_time": "1692255696",
  "source_debug_key": 647775351539539,
  "trigger_debug_key": 647776891539539
}

Свойства следующие:

"attribution_destination"

Строка или массив из 2–3 строк, в зависимости от того, был ли источник зарегистрирован с несколькими конечными точками. Эти строки представляют атрибуционный "destination" сайт(ы), установленные при регистрации источника в соответствующем ответе Attribution-Reporting-Register-Source заголовке.

"source_event_id"

Строка, представляющая идентификатор источника атрибуции. Он равен "source_event_id", установленному при регистрации источника (через соответствующий ответ Attribution-Reporting-Register-Source заголовке).

"trigger_data"

Строка, представляющая данные, полученные от триггера атрибуции, установленные при регистрации триггера (поле "trigger_data", установленное в ответе Attribution-Reporting-Register-Trigger заголовке).

"report_id"

Строка, представляющая универсальный уникальный идентификатор (UUID) для этого отчета, который может быть использован для предотвращения дублирования подсчётов.

"source_type"

Строка, равная либо "navigation" , либо "event", что соответственно указывает, является ли связанный источник атрибуции на основе навигации или на основе событий.

"randomized_trigger_rate"

Случайное число от 0 до 1, указывающее, как часто применяется шум для данной конфигурации источника.

"scheduled_report_time"

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

"source_debug_key" Необязательно

64-битное беззнаковое целое число, представляющее ключ отладки для источника атрибуции. Это отражает значение, установленное в соответствующем заголовке Attribution-Reporting-Register-Source в поле "debug_key". Дополнительная информация в разделе Отчеты отладки.

"trigger_debug_key" Необязательно

64-битное беззнаковое целое число, представляющее ключ отладки для триггера атрибуции. Это отражает значение, установленное в соответствующем заголовке Attribution-Reporting-Register-Trigger в поле "debug_key". Дополнительная информация в разделе Отчеты отладки.

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

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

Время истечения определяется значением expiry в связанном Attribution-Reporting-Register-Source заголовке, которое по умолчанию составляет 30 дней после регистрации, если явно не указано другое значение. Имейте в виду, что длину периода отчета можно дополнительно изменить, установив значение aggregatable_report_window в заголовке Attribution-Reporting-Register-Source. Подробнее см. Пользовательские периоды отчета.

Типичный агрегируемый отчет может выглядеть следующим образом:

{
  "shared_info": "{\"api\":\"attribution-reporting\",\"attribution_destination\":\"https://advertiser.example\",\"report_id\":\"123e4567-e89b-12d3-a456-426614174000\",\"reporting_origin\":\"https://reporter.example\",\"scheduled_report_time\":\"1692255696\",\"source_registration_time\":\"1692230400\",\"version\":\"3\"}",
  "aggregation_service_payloads": [
    {
      "payload": "[base64-encoded HPKE encrypted data readable only by the aggregation service]",
      "key_id": "[string identifying public key used to encrypt payload]",
      "debug_cleartext_payload": "[base64-encoded unencrypted payload]"
    }
  ],
  "aggregation_coordinator_origin": "https://publickeyservice.aws.privacysandboxservices.com",
  "source_debug_key": 647775351539539,
  "trigger_debug_key": 647776891539539
}

Свойства следующие:

"shared_info"

Это сериализованный объект JSON, предоставляющий информацию, которую служба агрегирования будет использовать для составления сводного отчета. Эти данные шифруются с помощью AEAD, чтобы предотвратить подделку. В сериализованной строке представлены следующие свойства:

"api"

Перечисление, представляющее API, которое инициировало создание отчета. В настоящее время это всегда будет равно "attribution-reporting", но в будущем оно может быть расширено дополнительными значениями для поддержки других API.

"attribution_destination"

Строка, представляющая атрибуционную "destination" URL, заданную при регистрации источника (через связанный Attribution-Reporting-Register-Source заголовок ответа).

"report_id"

Строка, представляющая уникальный идентификатор (UUID) для этого отчета, который можно использовать для предотвращения двойного подсчета.

"reporting_origin"

Источник, инициировавший создание отчета.

"scheduled_report_time"

Строка, представляющая количество секунд с эпохи Unix до момента, когда браузер первоначально запланировал отправку отчета (для избежания неточностей, возникающих из-за того, что автономные устройства сообщают о результатах с опозданием).

"source_registration_time"

Строка, представляющая количество секунд с эпохи Unix до момента регистрации источника атрибуции, округленная до целого дня.

"version"

Строка, представляющая версию API, используемой для создания отчета.

"aggregation_service_payloads"

Массив объектов, представляющих объекты полезной нагрузки, содержащие вклады гистограммы, используемые службой агрегирования для сборки данных, содержащихся в отчете. В настоящее время поддерживается только одна полезная нагрузка на отчет, настроенная браузером. В будущем может быть поддерживается несколько настраиваемых полезных нагрузок. Каждый объект полезной нагрузки может содержать следующие свойства:

"payload"

CBOR карта, зашифрованная с помощью HPKE и затем закодированная в формате Base64 со следующей структурой:

{
  "operation": "histogram",  // Allows for the service to support other operations in the future
  "data": [{
    "bucket": <bucket, encoded as a 16-byte (i.e. 128-bit) big-endian bytestring>,
    "value": <value, encoded as a 4-byte (i.e. 32-bit) big-endian bytestring>
  }, ...]
}

"key_id"

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

"debug_cleartext_payload" Необязательно

Необязательная отладочная информация.

"aggregation_coordinator_origin"

Вариант развертывания службы агрегирования.

"source_debug_key" Необязательно

64-битовое беззнаковое целое число, представляющее отладочный ключ для источника атрибуции. Это отражает значение, заданное в соответствующем Attribution-Reporting-Register-Source заголовке в поле "debug_key". Дополнительную информацию см. в разделе Отчеты отладки.

"trigger_debug_key" Необязательно

64-битовое беззнаковое целое число, представляющее отладочный ключ для триггера атрибуции. Это отражает значение, заданное в соответствующем Attribution-Reporting-Register-Trigger заголовке в поле "debug_key". Дополнительную информацию см. в разделе Отчеты отладки.

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

Для получения информации о том, как работает шум в отчетах об атрибуции, см.:

• Понимание шума в сводных отчетах.
• Пределы данных и шум
• Работа с шумом

По умолчанию у всех источников атрибуции одинаковый приоритет, а модель атрибуции — последняя, что значит, что конверсия приписывается последнему соответствующему событию источника. Для отчетов на уровне событий и агрегируемых отчетов можно изменить приоритет источника, задав новое значение для поля "priority" в соответствующем Attribution-Reporting-Register-Source заголовке. Значение по умолчанию — 0; если вы установите значение "priority" в 1 для определенного источника, этот источник будет соответствовать в первую очередь перед любыми источниками с приоритетом 0. Источники с "priority": "2" будут соответствовать раньше источников с "priority": "1" и так далее.

Приоритеты триггеров атрибуции работают аналогичным образом; вы также можете задать приоритеты триггеров, добавив поле "priority" в связанный Attribution-Reporting-Register-Trigger заголовок, но только для отчетов на уровне событий.

Разные типы источников имеют разные пределы по умолчанию:

• Источники атрибуции на основе навигации по умолчанию имеют ограничение в три отчета. Например, скажем, пользователь кликает по объявлению и совершает четыре конверсии: посещает домашнюю страницу сайта рекламодателя, затем страницу продукта, подписывается на рассылку новостей и, наконец, совершает покупку. Отчет о покупке будет пропущен, так как он поступает от четвертой конверсии.
• Источники атрибуции на основе событий по умолчанию имеют ограничение в один отчет.

При возникновении атрибуции для события определенного источника, если максимальное количество атрибуций (три для кликов, один для изображений/скриптов) достигнуто для этого источника, браузер:

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

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

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

Для объявления фильтров:

1. При регистрации источника добавьте поле filter_data в заголовок Attribution-Reporting-Register-Source, которое определяет ключи фильтра, которые вы будете использовать для фильтрации конверсий на стороне триггера. Это полностью настраиваемые поля. Например, для указания только конверсий на определённых субдоменах и для определённых продуктов:

   "filter_data": {
     "conversion_subdomain": ["electronics.megastore", "electronics2.megastore"],
     "product": ["1234"]
   }
   

2. При регистрации триггера добавьте поле filters в заголовок Attribution-Reporting-Register-Trigger. Например, следующее вызывает соответствие триггерных взаимодействий с вышеуказанной регистрацией источника, так как оба содержат поле "electronics.megastore" "conversion_subdomain". Фильтр "directory", в свою очередь, игнорируется при попытке сопоставления, поскольку он не был включён в вышеупомянутую регистрацию источника.

   "filters": {
     "conversion_subdomain": ["electronics.megastore"],
     "directory": ["/store/electronics"]
   }
   

Если поля "filter_data" и "filters" содержат совпадающие подполя (например, "conversion_subdomain" в примере выше), но ни одно из значений подполей не совпадает, триггер игнорируется, что приводит к отсутствию совпадения.

Поле event_trigger_data в заголовке Attribution-Reporting-Register-Trigger может быть расширено для выполнения селективной фильтрации для установки trigger_data, priority, или deduplication_key, на основе filter_data , определённого в заголовке Attribution-Reporting-Register-Source.

Например:

{
  "event_trigger_data": [
    {
      "trigger_data": "2",
      "filters": { "source_type": ["navigation"] }
    },
    {
      "trigger_data": "1",
      "filters": { "source_type": ["event"] }
    }
  ]
}

В этом контексте filters может быть объектом или массивом объектов. При указании списка для активации триггера достаточно совпадения только одного словаря.

{
  "event_trigger_data": [
    {
      "trigger_data": "2",
      "filters": [
        {
          "product": ["1234"],
          "conversion_subdomain": ["electronics.megastore"]
        },
        {
          "product": ["4321"],
          "conversion_subdomain": ["electronics4.megastore"]
        }
      ]
    }
  ]
}

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

Вы можете включить отчёты отладки для возврата информации о устранении неполадок по вашим отчётам об атрибуции. Это, например, может использоваться для проверки правильности вашей настройки и понимания пробелов в результатах измерения между вашей старой реализацией на основе файлов cookie и новой реализацией отчётности об атрибуции. Отчёты отладки отправляются немедленно; они не подчиняются тому же планированию, что и отчёты на уровне события и сводные отчёты.

Существует два различных типа отчётов отладки:

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

Для использования отчётов отладки необходимо:

1. Установите cookie ar_debug в источнике отчётности. Он должен быть присутствовать во время регистрации как источника, так и триггера:

   Set-Cookie: ar_debug=1; SameSite=None; Secure; Path=/; HttpOnly
   

2. Установите поле debug_key в любом ответе Attribution-Reporting-Register-Source и Attribution-Reporting-Register-Trigger ответных заголовках, относящихся к отчётам об атрибуции, для которых вы хотите предоставить информацию для отладки. Каждое значение debug_key должно быть 64-битным беззнаковым целым числом, отформатированным в виде строки в десятичной системе. Сделайте каждый ключ отладки уникальным идентификатором — вы можете, например, установить каждый как идентификатор cookie + отметка времени источника/триггера (и захватить эту же отметку времени в вашей старой системе на основе файлов cookie, если хотите сравнить их).

   {
     "debug_key": "647775351539539"
   }
   

   Примечание: Сделайте ключ отладки на стороне источника отличным от source_event_id, чтобы вы могли различать отдельные отчёты, у которых есть одинаковый идентификатор события источника.

3. Необязательно, установите поле debug_reporting в true, в обоих заголовках Attribution-Reporting-Register-Source и Attribution-Reporting-Register-Trigger. Если вы это сделаете, будет сгенерирован подробный отчёт отладки. Если вы этого не сделаете, будет сгенерирован отчёт отладки успеха, который отражает тип отчёта об атрибуции, который вы генерируете (на уровне события или агрегируемый).

   {
     "debug_key": "647775351539539",
     "debug_reporting": true
   }
   

4. Настройте соответствующие конечные точки для получения отчётов об отладке, которые вы хотите сгенерировать. Отчёты об отладке отправляются на три отдельные конечные точки в источнике отчётности:

   • Конечная точка для отчётов отладки успеха на уровне события: <reporting-origin>/.well-known/attribution-reporting/debug/report-event-attribution
   • Конечная точка для агрегируемых отчётов отладки успеха: <reporting-origin>/.well-known/attribution-reporting/debug/report-aggregate-attribution
   • Конечная точка для подробных отчётов отладки: <reporting-origin>/.well-known/attribution-reporting/debug/verbose

Сгенерированные отчёты отладки успеха идентичны отчётам об атрибуции и содержат ключи отладки на стороне источника и на стороне триггера соответственно в полях "source_debug_key" и "trigger_debug_key".

Для получения дополнительной информации и примеров см.:

• Введение в отчёты отладки на developers.google.com (2023)
• Настройка отчётов отладки на developers.google.com (2023)
• Справочник по отладке на developers.google.com (2023)