Регистрация триггеров атрибуции

В этой статье объясняется, как регистрировать триггеры атрибуции.

После регистрации источников атрибуции необходимо зарегистрировать триггеры атрибуции. Это взаимодействия на сайте, где необходимо отслеживать конверсии (например, нажатие кнопки "Купить" на сайте рекламодателя может указывать на то, что произошла конверсия). Затем браузер попытается сопоставить триггер атрибуции с записью источника атрибуции, хранящейся в частном локальном хранилище, и сгенерирует отчёт, если совпадение найдено.

Разные типы триггеров атрибуции регистрируются по-разному, что подробно описано в следующих разделах — см. триггеры атрибуции на основе HTML и триггеры атрибуции на основе JavaScript.

Однако, процесс регистрации триггеров, поиска совпадений и т. д. за кулисами одинаков во всех случаях.

1. Все типы триггеров отправляют заголовок Attribution-Reporting-Eligible в запросе, указывающий, что ответ подходит для регистрации триггера. Например:

   Attribution-Reporting-Eligible: trigger
   

2. Когда сервер получает запрос, содержащий заголовок Attribution-Reporting-Eligible, он может включить Attribution-Reporting-Register-Trigger в ответ. Его значение — строка JSON, содержащая данные, которые могут быть включены в сгенерированные отчёты, такие как идентификатор триггера, приоритет и значения для предотвращения дублирования.

   Следующий пример предназначен для соответствия источнику атрибуции отчёта по событиям:

   res.set(
     "Attribution-Reporting-Register-Trigger",
     JSON.stringify({
       "event_trigger_data": [
         {
           "trigger_data": "4",
           "priority": "1000000000000",
           "deduplication_key": "2345698765",
         },
       ],
       "debug_key": "1115698977",
     });
   );
   

   Указанные поля имеют следующее значение:

   • "event_trigger_data": Объект, представляющий данные о триггере. Он включает:
     • "trigger_data": Данные, связанные с триггером, обычно используемые для обозначения событий, таких как "пользователь добавил товар в корзину" или "пользователь подписался на рассылку". Это значение будет включено в сгенерированный отчёт, если таковой имеется, хотя оно будет изменено в зависимости от поля "trigger_data_matching" источника атрибуции.

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

     • "priority": Строка, представляющая значение приоритета для триггера атрибуции. Подробнее см. в разделе Приоритеты и ограничения отчётов.
     • "deduplication_key": Строка, представляющая уникальный ключ, который может быть использован для предотвращения дублирования атрибуции — например, если пользователь несколько раз добавит один и тот же товар в корзину. Подробнее см. Предотвращение дублирования в отчётах.
   • "debug_key": Число, представляющее ключ отладки. Установите это значение, если хотите сгенерировать отчёт об отладке вместе с соответствующим отчётом об атрибуции.

   Подробное описание всех доступных полей см. в Attribution-Reporting-Register-Trigger.

   Для триггера, предназначенного для соответствия источнику атрибуции сводного отчёта, требуются поля, показанные ниже:

   res.set(
     "Attribution-Reporting-Register-Trigger",
     JSON.stringify({
       "aggregatable_trigger_data": [
         {
           "key_piece": "0x400",
           "source_keys": ["campaignCounts"]
         },
         {
           "key_piece": "0xA80",
           "source_keys": ["geoValue", "nonMatchingKeyIdsAreIgnored"]
         }
       ],
       "aggregatable_values": {
         "campaignCounts": 32768,
         "geoValue": 1664
       },
       "debug_key": "1115698977"
     });
   );
   

   Поля в этом примере:

   • "aggregatable_trigger_data": Массив объектов, каждый из которых определяет ключ агрегирования, применяемый к различным ключам источника.
   • "aggregatable_values": Объект, содержащий свойства, представляющие значение для каждого точечного данных, определённого в "aggregatable_trigger_data".

   Ещё раз, подробное описание всех доступных полей см. в Attribution-Reporting-Register-Trigger.

3. При взаимодействии пользователя с триггером атрибуции браузер пытается сопоставить триггер с записью источника атрибуции, хранящейся в частном локальном кеше браузера. Для успешного сопоставления "trigger_data" триггера должно совпадать с одним из значений, предоставленных в Attribution-Reporting-Register-Source, а сайт (схема + eTLD+1) страницы верхнего уровня, на которой регистрируется триггер, должен:

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

   Примечание: Эти требования обеспечивают защиту конфиденциальности, но также предоставляют гибкость — источник и триггер могут быть вложены в <iframe> или расположены на сайте верхнего уровня.

   Существует множество других факторов, которые помешают успешному сопоставлению, например:

   • Фильтры триггера не соответствуют данным фильтра источника (см. Фильтры для получения дополнительной информации).
   • Настройка "trigger_data_matching" источника приводит к отсутствию совпадения.
   • Превышен предел "max_event_level_reports" источника.
   • Успешное сопоставление не сообщается из-за алгоритма случайного ответа браузера. См. Добавление шума в отчёты для получения дополнительной информации.

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

Триггеры атрибуции на основе HTML могут использоваться для определения конверсий на странице при её первой загрузке — или, точнее, при загрузке <img> или <script>. Например, если пользователь перешёл по ссылке источника атрибуции на странице издателя и перешёл на страницу рекламодателя, вы можете зарегистрировать триггер атрибуции и заставить браузер попытаться сопоставить его сохранённые записи источников, как только загрузится страница рекламодателя.

Вы можете зарегистрировать триггер атрибуции, добавив атрибут attributionsrc к соответствующему элементу. Это можно сделать для элементов <img> и <script>.

Если вы оставите значение атрибута пустым, запрос на регистрацию будет отправлен на сервер, на котором размещён запрашиваемый ресурс. Также можно указать дополнительный URL в значении, чтобы отправить запрос на регистрацию; см. Указание URL внутри attributionsrc для получения дополнительной информации.

Пример элемента <img>:

<img
  src="https://shop.example/conversion/4rghshdh5"
  width="1"
  height="1"
  attributionsrc />

Вы также можете добиться этого с помощью свойства HTMLImageElement.attributionSrc:

const imgElem = document.querySelector("img");
imgElem.attributionSrc = "";

В этом случае браузер попытается сопоставить триггер с сохранённым источником атрибуции, когда браузер получит ответ, содержащий изображение (когда срабатывает событие load). Имейте в виду, что пользователи, возможно, вообще не смогут увидеть изображение — это может быть 1x1 прозрачный отслеживающий пиксель, используемый только для отчётов об атрибуции.

Пример с элементом <script> может выглядеть следующим образом:

<script src="advertising-script.js" attributionsrc></script>

const scriptElem = document.querySelector("script");
scriptElem.attributionSrc = "";

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

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

Для регистрации триггера атрибуции на основе скрипта вы можете:

• Отправить запрос fetch(), содержащий параметр attributionReporting:

  const attributionReporting = {
    eventSourceEligible: false,
    triggerEligible: true,
  };
  
  // Optionally set keepalive to ensure the request outlives the page
  function triggerMatching() {
    fetch("https://shop.example/endpoint", {
      keepalive: true,
      attributionReporting,
    });
  }
  
  // Associate the interaction trigger with whatever
  // element and event makes sense for your code
  elem.addEventListener("click", triggerMatching);
  

• Отправить запрос XMLHttpRequest с вызовом setAttributionReporting() для объекта запроса:

  const attributionReporting = {
    eventSourceEligible: false,
    triggerEligible: true,
  };
  
  function triggerMatching() {
    const req = new XMLHttpRequest();
    req.open("GET", "https://shop.example/endpoint");
    // Check availability of setAttributionReporting() before calling
    if (typeof req.setAttributionReporting === "function") {
      req.setAttributionReporting(attributionReporting);
      req.send();
    } else {
      throw new Error("Attribution reporting not available");
      // Include recovery code here as appropriate
    }
  }
  
  // Associate the interaction trigger with whatever
  // element and event makes sense for your code
  elem.addEventListener("click", triggerMatching);
  

В этом случае браузер попытается сопоставить триггер с сохранённым источником атрибуции, когда браузер получит ответ от запроса fetch.

В приведённых выше примерах атрибут attributionsrc оставлен пустым, принимая значение пустой строки. Это нормально, если сервер, на котором хранится запрашиваемый ресурс, — тот же сервер, который вы также хотите использовать для обработки регистрации, т. е. получить заголовок Attribution-Reporting-Eligible и ответить заголовком Attribution-Reporting-Register-Trigger.

Однако, может быть, что запрашиваемый ресурс не находится на сервере, которым вы управляете, или вы просто хотите обработать регистрацию триггера атрибуции на другом сервере. В таких случаях вы можете указать один или несколько URL в качестве значения attributionsrc. При запросе ресурса заголовок Attribution-Reporting-Eligible будет отправлен на URL, указанные в attributionsrc, помимо источника ресурса; эти URL могут затем ответить заголовком Attribution-Reporting-Register-Trigger для завершения регистрации.

Например, в случае элемента <img> вы можете объявить URL в атрибуте attributionsrc:

<img
  src="https://shop.example/conversion/4rghshdh5"
  attributionsrc="https://my-separate-tracking-site.example.com"
  width="1"
  height="1" />

Или в JavaScript через свойство attributionSrc:

const imgElem = document.querySelector("img");
imgElem.attributionSrc = "https://my-separate-tracking-site.example.com";

• Инструмент проверки заголовков отчётности об атрибуции