HTTP-заголовок Attribution-Reporting-Register-Source ответа регистрирует функцию страницы как источник атрибуции. Этот заголовок включается в ответ на запрос, содержащий заголовок Attribution-Reporting-Eligible. Он предоставляет сведения, которые браузер должен сохранить, когда пользователь взаимодействует с источником атрибуции. Сведения, включённые в этот заголовок, также определяют типы отчётов, которые браузер может создавать.

Подробнее см. в документации Attribution Reporting API.

Синтаксис

Attribution-Reporting-Register-Source: <json-string>

Директивы

<json-string>

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

"source_event_id" Необязательно

Строка, представляющая идентификатор источника атрибуции. Её можно использовать для сопоставления источника с другими сведениями при взаимодействии с ним или для агрегирования сведений в конечной точке отчётов. Строка должна состоять только из беззнакового 64-битного целого числа в десятичном формате.

"destination"

Одна строка или массив из 1–3 строк. Эти строки должны содержать полный URL сайта, включая схему, на котором ожидается срабатывание триггера. Они используются для сопоставления триггера атрибуции с источником при взаимодействии с триггером.

"aggregation_keys" Необязательно

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

"aggregatable_report_window" Необязательно

Строка, представляющая время в секундах, по истечении которого данные триггера больше не будут включаться в создаваемые агрегируемые отчёты (это называется окном отчёта). Если значение не задано, по умолчанию используется значение "expiry".

"debug_key" Необязательно

Беззнаковое 64-битное целое число в десятичном формате, представляющее ключ отладки. Установите это значение, если хотите создать отчёт отладки вместе с соответствующим отчётом атрибуции.

"debug_reporting" Необязательно

Логическое значение. Если задано значение debug_key, установите true, чтобы указать, что создаваемый отчёт отладки должен быть подробным.

"event_level_epsilon" Необязательно

Число, равное или большее 0, которое определяет уровень шума, добавляемого в отчёты. Чем меньше значение эпсилон, тем больше шума и, следовательно, выше уровень защиты конфиденциальности. Максимальные значения и значения по умолчанию различаются в разных реализациях; например, в Chrome максимальное значение и значение по умолчанию — 14.

"event_report_window" Необязательно

Строка, представляющая время в секундах, по истечении которого последующие триггеры перестанут связываться с этим источником при создании отчётов на уровне событий (это называется окном отчёта). Если значение не задано, в качестве окна отчёта для событий используется значение "expiry".

Примечание: Если указано "event_report_window", нельзя указывать "event_report_windows", иначе регистрация источника завершится с ошибкой.

"event_report_windows" Необязательно

Объект, представляющий последовательность окон отчёта, начинающихся с "start_time"; отчёты для этого источника отправляются по истечении каждого указанного времени окончания из "end_times". Это можно использовать, чтобы распределить время отправки нескольких отчётов. Если значение не задано, в качестве окна отчёта для событий используется значение "expiry". Свойства:

• "start_time" Необязательно: Неотрицательное число, задающее время начала окон отчётности. Если значение не указано, по умолчанию используется 0.
• "end_times": Массив положительных чисел, задающих время окончания последующих окон отчёта. Значения должны идти по возрастанию и быть больше "start_time".

  Примечание: Если указано "event_report_windows", нельзя указывать "event_report_window", иначе регистрация источника завершится с ошибкой.

"expiry" Необязательно

Строка, представляющая срок действия источника атрибуции в секундах, по истечении которого он перестанет быть активным (то есть последующие триггеры нельзя будет связать с этим источником). Максимальный допустимый срок действия — 2592000 секунд (30 дней); это значение также используется по умолчанию, если "expiry" не задано явно.

"filter_data" Необязательно

Объект, определяющий пользовательские данные, которые можно использовать для фильтрации конверсий, создающих отчёты. Подробнее см. в разделе «Фильтры».

"max_event_level_reports" Необязательно

Число от 0 до 20 включительно, задающее общее количество отчётов на уровне событий, которые может создать этот источник. После достижения этого предела источник больше не сможет создавать новые данные. Если значение не указано, "max_event_level_reports" по умолчанию равно 3 для источников, основанных на навигации, и 1 для источников, основанных на событиях (изображениях или скриптах).

"priority" Необязательно

Строка, представляющая значение приоритета источника атрибуции. По умолчанию конверсии связываются с последним подходящим источником. Чтобы задать приоритет для определённых источников, укажите более высокое значение приоритета как для отчётов на уровне событий, так и для сводных отчётов. Например, значение 2 имеет приоритет над значением по умолчанию 1. Подробнее см. в разделе «Приоритеты и ограничения отчётов».

"trigger_data" Необязательно

Массив беззнаковых 32-битных целых чисел, представляющих данные о различных событиях-триггерах, которые могут соответствовать этому источнику. Например, «пользователь добавил товар в корзину» или «пользователь подписался на рассылку» — это действия на сайте триггера, которые могут соответствовать этому источнику и указывать на конверсию, измеряемую рекламодателем. Для атрибуции на уровне событий эти значения должны соответствовать "trigger_data", указанным в триггерах. Если значение не указано, "trigger_data" по умолчанию равно [0, 1, 2, 3, 4, 5, 6, 7] для источников, основанных на навигации, и [0, 1] для источников, основанных на событиях (изображениях или скриптах).

Примечание: Значения, используемые для представления каждого события, и количество элементов в массиве выбираются произвольно и определяются вами как разработчиком. Массив может содержать неиспользуемые значения, однако при регистрации триггера в нём должны присутствовать значения, чтобы браузер мог связать их с источником.

"trigger_data_matching" Необязательно

Строка, задающая способ сопоставления "trigger_data" триггера с "trigger_data" источника. Возможные значения:

• "exact": "trigger_data" триггера должно точно совпадать со значением в "trigger_data" источника; если совпадения нет, атрибуция на уровне событий не выполняется.
• "modulus": В этом случае выполняется следующий расчёт — d % allowedValues.size, где d — это "trigger_data" триггера, а allowedValues — последовательность значений в массиве "trigger_data" источника. Если результат расчёта совпадает со значением в массиве "trigger_data" источника, сопоставление считается успешным. В этом случае значение всегда будет совпадать, если только allowedValues не пуст.

Режим "modulus" существует главным образом для обратной совместимости с поведением API до появления "exact", поэтому вряд ли вам понадобится его использовать. Он по-прежнему полезен в отдельных случаях, когда требуется очень специфический тип сжатия, позволяющий уменьшить размер заголовков регистрации. Это может потребоваться при использовании сложной логики фильтрации, которая должна задавать разные данные триггера в зависимости от типа источника, с учётом максимального количества элементов "trigger_data" источника.

Примечание: При использовании "modulus" значения "trigger_data" источника должны образовывать непрерывную последовательность целых чисел, начинающуюся с 0. Если данные триггера не образуют такую последовательность, возникает ошибка.

Если значение не указано, "trigger_data_matching" по умолчанию равно "modulus". Причина опять же в обратной совместимости: отсутствие поля "trigger_data_matching" должно приводить к тому же поведению, которое наблюдалось до появления этого поля.

Примеры

Регистрация источника для отчёта на уровне событий

Сервер Node.js может задать заголовок ответа Attribution-Reporting-Register-Source следующим образом, чтобы браузер создавал отчёт на уровне событий, когда триггер соответствует источнику:

res.set(
  "Attribution-Reporting-Register-Source",
  JSON.stringify({
    source_event_id: "412444888111012",
    destination: "https://shop.example",
    trigger_data: [0, 1, 2, 3, 4],
    trigger_data_matching: "exact",
    expiry: "604800",
    priority: "100",
    debug_key: "122939999",
    event_report_window: "86400",
  }),
);

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

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

res.set(
  "Attribution-Reporting-Register-Source",
  JSON.stringify({
    source_event_id: "412444888111012",
    destination: "https://shop.example",
    trigger_data: [0, 1, 2, 3, 4],
    trigger_data_matching: "exact",
    expiry: "604800",
    priority: "100",
    debug_key: "122939999",
    event_report_window: "86400",

    aggregation_keys: {
      campaignCounts: "0x159",
      geoValue: "0x5",
    },
    aggregatable_report_window: "86400",
  }),
);

Спецификации

Совместимость с браузерами

См. также

• Attribution-Reporting-Eligible
• Attribution-Reporting-Register-Trigger
• Attribution Reporting API