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

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

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

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

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

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

• тег <a>
• тег <img>
• тег <script>
• fetch вызов
• XMLHttpRequest
• window.open

При этом генерируются сетевые запросы, на которые вы затем отвечаете заголовком 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]"
     }]
   }
   ```
   
   **Example for summary reports:**
   
   ```json
   {
     ... // 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, так и eTLD+1 URL-адреса этой страницы. <br> Если обнаружено несколько источников, браузер выбирает тот, который был сохранен последним — если только источники не имеют разных приоритетов, при которых браузер выбирает тот, который имеет наибольший приоритет.

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

Если 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> ) или тега скрипта.

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

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

Ключевой момент: * Источник для src должен совпадать с источником, выполнившим регистрацию источника. * Атрибуцию можно активировать только на странице, eTLD+1 которой соответствует сайту, указанному в месте назначения при регистрации источника.

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

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

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

// With fetch
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 });

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

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

Ключевой момент: — Источник для <code>src</code> должен совпадать с источником, который выполнил регистрацию источника. – Атрибуцию можно активировать только на странице, чей <a href="https://web.dev/same-site-same-origin/#%22schemeful-same-site%22">eTLD+1</a> соответствует сайту, который был указан в поле <code>destination</code> при регистрации источника.

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. Это полезно для фильтров.

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

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