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

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

Триггер атрибуции — это событие, которое сообщает браузеру о необходимости фиксировать конверсии.

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

Методы регистрации

Для регистрации триггеров используйте HTML-элементы или вызовы JavaScript:

  • <img> тег
  • <script> тег
  • fetch вызов
  • XMLHttpRequest

Это генерирует сетевые запросы, на которые вы затем отвечаете заголовком HTTP-ответа, указывающим на регистрацию триггера.

Зарегистрируйте триггер для присвоения статуса конверсии.

Регистрация триггера аналогична регистрации события источника атрибуции . Полные шаги описаны далее. Вот краткое изложение:

  1. Инициируйте регистрацию триггера. Используйте пиксель или вызов функции fetch() для отправки запроса.

  2. Завершите регистрацию триггера , отправив в ответ заголовок регистрации триггера.

    После получения запроса на пиксель — отправленного либо на конечную точку, определенную в обычном атрибуте src , либо на конечную точку, определенную в attributionsrc если вы выбрали использование attributionsrc и указали для него значение — отправьте ответ с заголовком Attribution-Reporting-Register-Trigger .

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

    Пример отчетов на уровне событий:

    {
  "event_trigger_data": [{
    "trigger_data": "[unsigned 64-bit integer]",
    "priority": "[signed 64-bit integer]",
    "deduplication_key": "[unsigned 64-bit integer]"
  }]
}

    Пример сводных отчетов:

    {
  ... // existing fields, such as "event_trigger_data"

  "aggregatable_trigger_data": [
   {
     "key_piece": "0x400",
     "source_keys": ["campaignCounts"]
   },
   {
     "key_piece": "0xA80",
     "source_keys": ["geoValue", "nonMatchingKeyIdsAreIgnored"]
   }
  ],
  "aggregatable_values": {
    "campaignCounts": 32768,
    "geoValue": 1664
  }
}

Работа с поддоменами

Если destination является https://advertiser.example , то конверсии как на https://advertiser.example , так и на его поддоменах, таких как https://shop.advertiser.example могут быть учтены.

Если destination — https://shop.advertiser.example , то конверсии как на https://advertiser.example , так и https://shop.advertiser.example могут быть учтены.

Обязательные и необязательные атрибуты

При использовании HTML-элементов или вызовах JavaScript для регистрации триггеров может потребоваться использование attributionsrc или attributionReporting . Подробную информацию о том, когда они необходимы, см. в следующей таблице.

Если attributionsrc является необязательным , его использование указывает на то, что запрос подходит для включения в отчет об атрибуции. При использовании attributionsrc браузер отправляет заголовок Attribution-Reporting-Eligible . Это также полезно для измерения эффективности приложений и веб-сайтов: если attributionsrc присутствует, браузер отправляет заголовок Attribution-Reporting-Support .

Способ регистрации Курок
<a> тег Неприменимо : Якоря не могут зарегистрировать триггер.
<img> тег attributionsrc является необязательным. Заголовка достаточно для регистрации триггера.
<script> тег attributionsrc является необязательным . Заголовка достаточно для регистрации триггера.
fetch вызов Для использования этой опции требуется параметр attributionReporting .
XMLHttpRequest Для использования этой опции требуется параметр attributionReporting .
window.open() N/A: window.open не может зарегистрировать триггер.

Шаг 1: Инициируйте регистрацию триггера.

Зарегистрировать триггер можно с помощью пикселя (тега <img> ) или тега <script>.

Использование нового или существующего пикселя конверсии

В следующем примере добавление атрибута attributionsrc активирует указание авторства для существующего изображения.

Исходный код для attributionsrc должен совпадать с исходным кодом, выполнившим регистрацию источника.

<img src="https://advertiser.example/conversionpixel"
     attributionsrc="https://adtech.example/attribution_trigger?purchase=13">

В следующем примере атрибуция запускается путем добавления нового атрибута attributionsrc для пикселя конверсии.

Значение параметра src должно совпадать с тем значением, которое использовалось для регистрации источника.

<img src="https://adtech.example/conversionpixel"
     attributionsrc>

Использование тега <script>

Вы можете зарегистрировать триггер с помощью тега <script>; он работает аналогично тегу <img> . Следующие примеры кода иллюстрируют использование функций fetch() и XMLHttpRequest() (XHR).

Этот код эффективно имитирует то, что бы сделал HTML-запрос с attributionsrc :

const attributionReporting = {
  eventSourceEligible: false,
  triggerEligible: true,
};

// Optionally set keepalive to make sure the request outlives the page.
window.fetch("https://adtech.example/attribution_source?my_ad_id=123",
  { keepalive: true, attributionReporting });

const attributionReporting = {
  eventSourceEligible: false,
  triggerEligible: true,
};

const req = new XMLHttpRequest();
req.open("GET", url);
req.setAttributionReporting(attributionReporting);
req.send();

attributionsrc со значением или без него

Вы можете добавить attributionsrc как с указанием значения, так и без него.

<!-- Without a value -->
<img src="..." width="1" height="1" attributionsrc>

<!-- With a value (URL) -->
<img src="..." width="1" height="1" attributionsrc="https://...">

Если вы зададите значение для attributionsrc , оно может представлять собой один или несколько URL-адресов, разделенных пробелами.

Использование URL-адреса приводит к тому, что браузер инициирует отдельный запрос на проверку соединения (keepalive fetch) — по одному для каждого URL-адреса — который включает заголовок запроса Attribution-Reporting-Eligible .

Это полезно, если вы хотите зарегистрировать триггер, ответив на запрос, отдельный от основного запроса элемента.

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

Шаг 2: Ответьте, добавив заголовок.

После получения запроса от браузера ответьте на него, включив в него заголовок Attribution-Reporting-Register-Trigger :

JSON.stringify({
  event_trigger_data: [{
    trigger_data: "412444888111012",
    // Optional
    priority: "1000000000000",
    deduplication_key: "2345698765"
  }],
  debug_key: "1115698977"
});

Следующие шаги

Узнайте, как зарегистрировать источники указания авторства .