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

В этой статье объясняется, как регистрировать источники атрибуции при использовании API отчетов об атрибуции.

Источники атрибуции представляют собой ссылки, изображения или скрипты, содержащиеся в контенте, взаимодействие с которым вы хотите отслеживать (например, это могут быть рекламные объявления, по которым вы хотите отслеживать конверсии). Они заставляют браузер хранить данные источника в частном локальном кэше (доступном только браузеру) при определённых пользовательских взаимодействиях. Разные типы источников атрибуции регистрируются и сигнализируют об взаимодействиях по-разному — они различаются как:

• Источники навигации, которые заставляют браузер хранить данные источника в ответ на навигацию — например, когда пользователь щелкает по ссылке или активирует её с помощью клавиатуры, или когда навигация происходит в результате вызова Window.open(). См. Источники атрибуции, основанные на навигации для примеров.
• Источники событий, которые заставляют браузер хранить данные источника в ответ на срабатывание событий. См. Источники атрибуции, основанные на событиях для примеров.

То, что происходит за кулисами для регистрации источников и извлечения и хранения данных источника, в обоих случаях одинаково:

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

   Attribution-Reporting-Eligible: navigation-source
   

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

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

     res.set(
       "Attribution-Reporting-Register-Source",
       JSON.stringify({
         source_event_id: "412444888111012",
         destination: "https://advertiser.example",
         trigger_data: [0, 1, 2, 3, 4],
         trigger_data_matching: "exact",
         expiry: "604800",
         priority: "100",
         debug_key: "122939999",
         event_report_window: "86400",
       }),
     );
     

     Единственным необходимым полем в этом контексте является destination, которое определяет 1–3 сайта, на которых ожидается возникновение триггера. Они используются для сопоставления триггера атрибуции с источником при взаимодействии с триггером. Другие указанные выше поля выполняют следующие действия:

     • "source_event_id": Строка, представляющая идентификатор источника атрибуции, который можно использовать для сопоставления его с другой информацией при взаимодействии с источником атрибуции или для агрегации информации на конечной точке отчета (см. Генерация отчетов > Основной процесс для информации об конечной точке).
     • "trigger_data": Массив из 32-битных беззнаковых целых чисел, представляющих данные, описывающие различные события триггера, которые могут соответствовать этому источнику. Например, «пользователь добавил товар в корзину» или «пользователь подписался на рассылку» могут быть действиями, происходящими на сайте триггера, которые могут соответствовать этому источнику и указывать на некий вид конверсии, которую рекламодатель пытается измерить. Они должны соответствовать "trigger_data", указанному в триггерах, для того, чтобы произошла атрибуция на уровне события.

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

     • "trigger_data_matching": Строка, которая определяет, как "trigger_data" от триггера сопоставляется с "trigger_data" источника. "exact" — это значение, которое вы будете использовать почти всегда, которое соответствует точным значениям.
     • "expiry": Строка, представляющая время истечения срока действия источника атрибуции в секундах, после которого он больше не будет активен (т. е. последующие триггеры не будут относиться к этому источнику).
     • "priority": Строка, представляющая приоритет источника атрибуции. См. Приоритеты и ограничения отчетов для получения дополнительной информации.
     • "debug_key": Беззнаковое 64-битное целое число в формате с основанием 10, представляющее ключ отладки. Установите его, если вы хотите сгенерировать отчет об отладке наряду с соответствующим отчетом об атрибуции.
     • "event_report_window": Строка, представляющая время в секундах, после которого последующие триггеры больше не будут относиться к этому источнику для целей создания отчетов на уровне событий.

     См. Attribution-Reporting-Register-Source для подробного описания всех доступных полей в этом заголовке.

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

     res.set(
       "Attribution-Reporting-Register-Source",
       JSON.stringify({
         source_event_id: "412444888111012",
         destination: "https://advertiser.example",
         trigger_data: [0, 1, 2, 3, 4],
         trigger_data_matching: "exact",
         expiry: "604800",
         priority: "100",
         debug_key: "122939999",
         event_report_window: "86400",
     
         aggregation_keys: {
           campaignCounts: "0x159",
           geoValue: "0x5",
         },
         aggregatable_report_window: "86400",
       }),
     );
     

     Дополнительные поля в этом примере:

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

     Опять же, см. Attribution-Reporting-Register-Source для подробного описания всех доступных полей в этом заголовке.

3. После успешной регистрации источника браузер хранит предоставленные данные источника в своем частном локальном кэше.

Источники навигации полезны для измерения взаимодействий со ссылками — например, пользователь может увидеть рекламу на странице издателя и перейти по ней на страницу рекламодателя, где, надеемся, произойдёт конверсия.

Существует несколько различных типов источников атрибуции, основанных на навигации (например, щелчок по рекламе), которые можно зарегистрировать — те, которые основаны на HTML (использующие атрибут attributionsrc) и те, которые основаны на вызовах Window.open() (использующие функцию окна attributionsrc).

Чтобы зарегистрировать источник атрибуции, основанный на навигации, вы можете добавить атрибут attributionsrc к соответствующему элементу <a>, который указывает, куда будет отправлен запрос на регистрацию.

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

attributionsrc можно добавить декларативно:

<a href="https://shop.example" attributionsrc target="_blank">
  Click to visit our shop
</a>

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

const aElem = document.querySelector("a");
aElem.attributionSrc = "";

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

Вы также можете добавить ключевое слово функции attributionsrc к свойству features вызова Window.open(). В этом примере мы запускаем его в ответ на срабатывание события click.

elem.addEventListener("click", () => {
  window.open("https://shop.example", "_blank", "attributionsrc");
});

В этом случае взаимодействие происходит, и браузер хранит данные источника, когда вызывается Window.open(), и браузер получает ответ.

Источники атрибуции, основанные на событиях, заставляют браузер хранить данные источника в ответ на срабатывание какого-либо события, например, события load в случае с элементом <img> или <script> (которые используют атрибут attributionsrc так же, как мы видели выше с элементом <a> ), или пользовательского события по вашему выбору, установленного в вашем JavaScript.

HTML-основанные источники событий можно использовать для измерения взаимодействия с страницей издателя при её первой загрузке — или, точнее, при загрузке <img> или <script>. Чтобы зарегистрировать источник атрибуции на основе событий через HTML, можно добавить атрибут attributionsrc к соответствующему элементу — <img> или <script>.

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

Рассмотрим пример элемента <img>:

<img src="advertising-image.png" attributionsrc />

Это также можно сделать с помощью свойства HTMLImageElement.attributionSrc:

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

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

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

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

Или с помощью свойства HTMLScriptElement.attributionSrc:

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

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

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

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

• Отправить запрос fetch() с опцией attributionReporting:

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

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

  const attributionReporting = {
    eventSourceEligible: true,
    triggerEligible: false,
  };
  
  function triggerSourceInteraction() {
    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
  // event makes sense for your code (does not have to be a
  // DOM event/user interaction)
  elem.addEventListener("click", triggerSourceInteraction);
  

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

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

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

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

<a
  href="https://shop.example"
  attributionsrc="https://a.example/register-source">
  Click to visit our shop
</a>

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

// encode the URLs in case they contain special characters
// such as '=' that would be improperly parsed.
const encodedUrlA = encodeURIComponent("https://a.example/register-source");
const encodedUrlB = encodeURIComponent("https://b.example/register-source");

const aElem = document.querySelector("a");
aElem.attributionSrc = `${encodedUrlA} ${encodedUrlB}`;

В случае вызова Window.open(), разные URL-адреса должны быть перечислены как несколько отдельных функций attributionsrc в параметре windowFeatures, разделённые запятыми или пробелами:

// encode the URLs in case they contain special characters
// such as '=' that would be improperly parsed.
const encodedUrlA = encodeURIComponent("https://a.example/register-source");
const encodedUrlB = encodeURIComponent("https://b.example/register-source");

elem.addEventListener("click", () => {
  window.open(
    "https://ourshop.example",
    "_blank",
    `attributionsrc=${encodedUrlA},attributionsrc=${encodedUrlB}`,
  );
});

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