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

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

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

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

Способы регистрации

Для регистрации триггеров используйте элементы 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
     }
   }
   

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

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

Если 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()	Н/Д: window.open не может зарегистрировать триггер.

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

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

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

В следующем примере атрибуция активируется для существующего изображения путем добавления атрибута 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>

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

Использование тега сценария

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

Этот код эффективно имитирует действия HTML-запроса с attributionsrc :

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

// Optionally set keepalive to ensure 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();

Ключевой момент:

• Источник или url , заданный в fetch() или open() должен совпадать с источником, выполнившим регистрацию источника.
• Атрибуцию можно активировать только на странице, сайт которой соответствует сайту, указанному в месте назначения при регистрации источника.

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 — по одному для каждого 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"
});

Внимание: значение поля event_trigger_data должно быть вложено в квадратные скобки, поскольку браузер ожидает массив JSON. Это полезно для фильтров.

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

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