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

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

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

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

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

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

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

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

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

Регистрация источников кликов или просмотров

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

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

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

    {
      "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 .

Метод регистрации Источник
тег <a> (источник навигации)
Требуется attributionsrc .
тег <img> (источник события)
Требуется attributionsrc .
тег <script> (источник события)
Требуется attributionsrc .
fetch вызов Опция attributionReporting является обязательной .
XMLHttpRequest Опция attributionReporting является обязательной .
window.open вызов (источник навигации)
attributionsrc обязателен.

Шаг 1. Начать регистрацию источника

Шаг 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-адреса получают запросы 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 ensure 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"}

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

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