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

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

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

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

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

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

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

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

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

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

Чтобы зарегистрировать источник атрибуции для кликов или просмотров, выполните действия, описанные здесь. Полные шаги приведены ниже. Вот краткое изложение:

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

2. Завершите регистрацию источника , отправив ответ с заголовком регистрации источника. После получения запроса отправьте ответ с заголовком Attribution-Reporting-Register-Source . В этом заголовке укажите выбранную конфигурацию Attribution Reporting. Этот шаг одинаков как для кликов, так и для просмотров.

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

   {
     "aggregation_keys": {
       "campaignCounts": "0x159",
       "geoValue": "0x5"
     },
     "aggregatable_report_window": "86400",
     "destination": "https://example.com"
   }
   

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

   {
     "source_event_id": "12340873456",
     "destination": "[eTLD+1]",
     "expiry": "[64-bit signed integer]",
     "priority": "[64-bit signed integer]",
     "event_report_window": "[64-bit signed integer]"
   }
   

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

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

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

Шаг 1: Инициировать регистрацию источника

Первый шаг отличается для кликов и просмотров.

Для регистрации источника атрибуции для клика можно использовать тег <a> или метод JavaScript window.open() .

Использование якоря

Добавьте attributionsrc к существующим тегам <a> , для которых вы хотите измерять показы или клики:

<a href="https://shoes.example/..." attributionsrc>Click me</a>

Для получения более подробной информации ознакомьтесь с примером кода .

Используя скрипт

Вызовите window.open() с attributionsrc :

window.open(
  "https://shoes.example/...",
  "_blank",
  "attributionsrc");

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

Вместо того чтобы добавлять attributionsrc отдельно, для изображения или скрипта можно указать одно значение URL:

<a href=... attributionsrc="https://a.example/register-source">Click me</a>

В случае с JavaScript, если вы задаете значение для параметра attributionsrc , убедитесь, что этот URL-адрес закодирован на случай, если он содержит специальные символы, такие как = , которые могут привести к некорректному анализу параметра.

Закодируйте следующим образом:

const encodedUrl = encodeURIComponent(
  "https://adtech.example/attribution_source?ad_id=...");
window.open(
  "https://shoes.example/landing",
   "_blank",
   `attributionsrc=${encodedUrl}`);

attributionsrc также может принимать список URL-адресов, разделенных пробелами, как показано здесь с помощью тега <a> :

<a href=... attributionsrc="https://a.example/register-source
  https://b.example/register-source">Click me</a>

или, как здесь, используя window.open() .

window.open("...", "_blank", `attributionsrc=${encodedUrl1}
  attributionsrc=${encodedUrl2}`)

В таких случаях оба URL-адреса получают запросы navigation-source-eligible attributionsrc (запросы, включающие заголовок Attribution-Reporting-Eligible ).

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

Как вы видели ранее, вы можете указать attributionsrc без URL-адреса. Вы также можете указать один URL-адрес. Кроме того, вы можете использовать список URL-адресов, разделенных пробелами.

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

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

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

Для регистрации источника атрибуции для представления можно использовать тег изображения или скрипта, к которому следует добавить атрибут attributionsrc .

В качестве альтернативы можно использовать функции JavaScript fetch() или XMLHttpRequest() .

С изображением

<img attributionsrc
src="https://adtech.example/attribution_source?ad_id=...">

С помощью сценария

<script attributionsrc
  src="https://adtech.example/attribution_source?ad_id=..."></script>

При желании вы можете указать значение URL-адреса для параметра attributionsrc аналогично тому, как это делается для кликов; то есть, для изображения или скрипта вы можете задать URL-адрес или URL-адреса для параметра attributionsrc следующим образом:

С помощью одного URL-адреса:

<img attributionsrc="https://adtech.example/attribution_source?ad_id=123">

Список URL-адресов:

<img attributionsrc="https://a.example/register-source
  https://b.example/register-source">

Использование fetch() или XMLHttpRequest()

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

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

// 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: true,
  triggerEligible: false,
};

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

Шаг 2: Ответьте, добавив заголовок (клики и просмотры).

Следующим шагом как для кликов, так и для просмотров является отправка ответа с заголовком Attribution-Reporting-Register-Source .

Для получения более подробной информации ознакомьтесь с примером кода .

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

res.set(
  "Attribution-Reporting-Register-Source",
  JSON.stringify({
    // Use source_event_id to map it to any granular information
    // you need at ad-serving time
    source_event_id: "412444888111012",
    destination: "https://advertiser.example",
    // Optional fields
    expiry: "604800",
    priority: "100",
    debug_key: "122939999"
  })
);

После преобразования в строку ваш заголовок будет выглядеть так:

{"source_event_id":"412444888111012","destination":"https://advertiser.example","expiry":"604800","priority":"100","debug_key":"122939999"}

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

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