Отчеты по атрибуции для обзора мобильных устройств

Последние обновления

• Обновлен список предстоящих изменений и известных проблем.

• Представляем функцию повторных запросов (requerying), выход которой запланирован на вторую половину 2025 года. Повторные запросы позволяют специалистам по рекламным технологиям обрабатывать отчеты сервиса агрегации несколько раз, обеспечивая гибкий анализ для различных задач измерения. Присоединяйтесь к обсуждению на GitHub, чтобы узнать больше и оставить свой отзыв.

Обзор

Сегодня в решениях для атрибуции и измерения эффективности мобильного маркетинга часто используются идентификаторы разных сторонних пользователей, такие как Advertising ID. API для отчетов по атрибуции разработан для повышения конфиденциальности пользователей за счет исключения зависимости от идентификаторов пользователей разных сторонних пользователей, а также для поддержки ключевых сценариев использования атрибуции и измерения конверсий в приложениях и веб-среде.

Данный API обладает следующими структурными механизмами, которые предоставляют основу для повышения уровня конфиденциальности, более подробно описанными в последующих разделах этой страницы:

• Ограничивает количество битов, доступных для отчетов на уровне событий.

• Позволяет получать более точные данные о конверсии только в агрегируемых отчетах.

• Вводит ограничения на количество доступных триггеров (конверсий) и число рекламных технологий, которые могут быть связаны с одним источником атрибуции.

• Включает в себя различные методы добавления шума.

Указанные выше механизмы ограничивают возможность связывания личности пользователя в двух разных приложениях или доменах.

API для создания отчетов об атрибуции поддерживает следующие сценарии использования:

• Отчеты по конверсиям: помогают рекламодателям измерять эффективность своих кампаний, отображая количество конверсий (триггеров) и значения конверсий (триггеров) по различным параметрам, таким как кампания, группа объявлений и креатив объявления.
• Оптимизация: Предоставлять отчеты на уровне событий, которые помогут оптимизировать расходы на рекламу, предоставляя данные об атрибуции показов, которые можно использовать для обучения моделей машинного обучения.
• Выявление недопустимой активности: Предоставляйте отчеты, которые можно использовать для обнаружения и анализа недопустимого трафика и мошенничества с рекламой.

В общих чертах, API для создания отчетов об атрибуции работает следующим образом, который более подробно описан в последующих разделах этого документа:

1. Специалист по рекламным технологиям проходит процесс регистрации для использования API отчетов по атрибуции.
2. Эта рекламная технология регистрирует источники атрибуции — клики по объявлениям или просмотры — в API отчетов по атрибуции.
3. Рекламная технология регистрирует триггеры — конверсии пользователей в приложении или на веб-сайте рекламодателя — с помощью API отчетов по атрибуции.
4. API для формирования отчетов по атрибуции сопоставляет триггеры с источниками атрибуции — атрибуцией конверсий — и один или несколько триггеров отправляются за пределы устройства через отчеты на уровне событий и агрегируемые отчеты специалистам по рекламным технологиям.

Получите доступ к API для создания отчетов по атрибуции.

Для доступа к API отчетов по атрибуции рекламным платформам необходимо зарегистрироваться. Дополнительную информацию см. в разделе «Регистрация учетной записи в песочнице конфиденциальности» .

Укажите источник авторства (нажмите или просмотрите).

API для отчетов по атрибуции использует клики и просмотры объявлений в качестве источников атрибуции . Для регистрации клика или просмотра объявления вызовите registerSource() . Этот API ожидает следующие параметры:

• URI источника атрибуции: Платформа отправляет запрос по этому URI для получения метаданных, связанных с источником атрибуции.
• Событие ввода: либо объект InputEvent (для события клика), либо null (для события представления).

Когда API отправляет запрос к URI источника атрибуции, рекламная технология должна ответить метаданными источника атрибуции в новом HTTP-заголовке Attribution-Reporting-Register-Source , содержащем следующие поля:

• Идентификатор события источника : это значение представляет собой данные уровня события, связанные с данным источником атрибуции (клик по объявлению или просмотр). Должно быть 64-битным беззнаковым целым числом в формате строки.
• Назначение : Источник, eTLD+1 или имя пакета приложения, где происходит событие-триггер.
• Срок действия (необязательно) : Срок действия в секундах, по истечении которого источник должен быть удален с устройства. По умолчанию — 30 дней, минимальное значение — 1 день, максимальное — 30 дней. Значение округляется до ближайшего дня. Может быть задано в виде 64-битного беззнакового целого числа или строки.
• Окно отчета о событиях (необязательно) : Продолжительность в секундах после регистрации источника, в течение которой могут создаваться отчеты о событиях для этого источника. Если окно отчета о событиях прошло, но срок действия еще не истек, триггер все еще может быть сопоставлен с источником, но отчет о событии для этого триггера не отправляется. Не может быть больше, чем Expiry. Может быть отформатировано как 64-битное беззнаковое целое число или строка.
• Окно агрегируемых отчетов (необязательно) : Продолжительность в секундах после регистрации источника, в течение которой могут быть созданы агрегируемые отчеты для этого источника. Не может быть больше, чем «Срок действия». Может быть отформатировано как 64-битное беззнаковое целое число или строка.
• Приоритет источника (необязательно) : Используется для выбора источника атрибуции, с которым должен быть связан данный триггер, в случае, если с триггером может быть связано несколько источников атрибуции. Должен быть 64-битным знаковым целым числом, отформатированным как строка.
  
  При получении триггера API находит соответствующий источник атрибуции с наивысшим значением приоритета и генерирует отчет. Каждая рекламная технологическая платформа может определить свою собственную стратегию приоритезации. Более подробную информацию о том, как приоритет влияет на атрибуцию, см. в разделе примеров приоритезации .
  
  Более высокие значения указывают на более высокие приоритеты.
• Окна атрибуции при установке и после установки (необязательно): используются для определения атрибуции событий после установки , описанных далее на этой странице.
• Фильтрация данных (необязательно): Используется для выборочной фильтрации некоторых триггеров, фактически игнорируя их. Для получения более подробной информации см. раздел «Фильтры триггеров» на этой странице.
• Ключи агрегации (необязательно): укажите сегментацию , которая будет использоваться для агрегируемых отчетов .

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

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

Следующие шаги демонстрируют пример рабочего процесса:

1. SDK для рекламных технологий вызывает API для инициирования регистрации источника атрибуции, указывая URI, который API должен использовать для вызова:

   registerSource(
       Uri.parse("https://adtech.example/attribution_source?AD_TECH_PROVIDED_METADATA"),
       myClickEvent);
   

2. API отправляет запрос по адресу https://adtech.example/attribution_source? AD_TECH_PROVIDED_METADATA , используя один из следующих заголовков:

   <!-- For click events -->
   Attribution-Reporting-Source-Info: navigation
   
   <!-- For view events -->
   Attribution-Reporting-Source-Info: event
   

3. HTTPS-сервер этой рекламной технологии отправляет в ответ заголовки, содержащие следующее:

   Attribution-Reporting-Register-Source: {
       "destination": "android-app://com.advertiser.example",
       "source_event_id": "234",
       "expiry": "60000",
       "priority": "5"
   }
   Attribution-Reporting-Redirect:
   https://adtechpartner1.example?their_ad_click_id=567
   Attribution-Reporting-Redirect:
   https://adtechpartner2.example?their_ad_click_id=890
   

4. API отправляет запрос к каждому URL-адресу, указанному в Attribution-Reporting-Redirect . В этом примере указаны два URL-адреса партнеров по рекламным технологиям, поэтому API отправляет один запрос к https://adtechpartner1.example?their_ad_click_id=567 и еще один запрос к https://adtechpartner2.example?their_ad_click_id=890 .

5. HTTPS-сервер этой рекламной технологии отправляет в ответ заголовки, содержащие следующее:

   Attribution-Reporting-Register-Source: {
       "destination": "android-app://com.advertiser.example",
       "source_event_id": "789",
       "expiry": "120000",
       "priority": "2"
   }
   

На основе запросов, указанных на предыдущих этапах, регистрируются три источника атрибуции навигации (кликов).

Зарегистрируйте источник атрибуции в WebView

WebView поддерживает сценарий использования, когда приложение отображает рекламу внутри WebView. Это обрабатывается путем прямого вызова registerSource() в WebView. Этот вызов связывает источник атрибуции с приложением, а не с источником верхнего уровня. Также поддерживается регистрация источников из встроенного веб-контента в контексте браузера; как вызывающим API, так и приложениям необходимо настроить параметры для этого. См. раздел «Регистрация источника атрибуции и триггера из WebView» для инструкций для вызывающих API и «Регистрация источника атрибуции и триггера из WebView» для инструкций для приложений.

Поскольку в рекламных технологиях используется общий код как для веб-версий, так и для WebView, WebView обрабатывает HTTP-перенаправления 302 и передает действительные регистрации на платформу. Мы не планируем поддерживать заголовок Attribution-Reporting-Redirect для этого сценария, но свяжитесь с нами, если у вас есть затронутый сценарий использования.

Зарегистрируйте триггер (конверсию)

Платформы рекламных технологий могут регистрировать триггеры — конверсии, такие как установки или события после установки, — используя метод registerTrigger() .

Метод registerTrigger() ожидает в качестве параметра URI триггера . API отправляет запрос по этому URI для получения метаданных, связанных с триггером.

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

• Данные триггера: Данные для идентификации события-триггера (3 бита для кликов, 1 бит для просмотров). Должны представлять собой 64-битное знаковое целое число, отформатированное как строка.

• Приоритет триггера (необязательно): указывает приоритет данного триггера по сравнению с другими триггерами для того же источника атрибуции. Должен быть 64-битным знаковым целым числом в формате строки. Более подробную информацию о влиянии приоритета на отчетность см. в разделе «Приоритизация» .

• Ключ дедупликации (необязательный): используется для идентификации случаев, когда один и тот же триггер регистрируется несколько раз одной и той же рекламной платформой для одного и того же источника атрибуции. Должен быть 64-битным знаковым целым числом в формате строки.

• Ключи агрегации (необязательно): Список словарей, определяющих ключи агрегации и указывающих, для каких агрегируемых отчетов следует агрегировать их значения.

• Агрегированные значения (необязательно): Список значений, которые влияют на каждый ключ.

• Фильтры (необязательно): используются для выборочной фильтрации триггеров или данных триггеров. Более подробную информацию см. в разделе «Фильтры триггеров» на этой странице.

В качестве опции ответ сервера рекламных технологий может включать дополнительные данные в заголовке Attribution Reporting Redirects . Эти данные содержат URL-адреса перенаправлений, что позволяет нескольким рекламным технологическим компаниям регистрировать запрос .

Несколько рекламных технологий могут зарегистрировать одно и то же событие-триггер, используя либо перенаправления в поле Attribution-Reporting-Redirect либо несколько вызовов метода registerTrigger() . Мы рекомендуем использовать поле ключа дедупликации , чтобы избежать включения повторяющихся триггеров в отчеты в случае, если одна и та же рекламная технология предоставляет несколько ответов на одно и то же событие-триггер. Узнайте больше о том, как и когда использовать ключ дедупликации .

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

Следующие шаги демонстрируют пример рабочего процесса:

1. SDK для рекламных технологий вызывает API для инициирования регистрации триггера, используя предварительно зарегистрированный URI. Дополнительную информацию см. в разделе «Регистрация учетной записи в песочнице конфиденциальности» .

   registerTrigger(
       Uri.parse("https://adtech.example/attribution_trigger?AD_TECH_PROVIDED_METADATA"));
   

2. API отправляет запрос по адресу https://adtech.example/attribution_trigger? AD_TECH_PROVIDED_METADATA .

3. HTTPS-сервер этой рекламной технологии отправляет в ответ заголовки, содержащие следующее:

   Attribution-Reporting-Register-Trigger: {
       "event_trigger_data": [{
       "trigger_data": "1122",
       // This returns 010 for click-through conversions (CTCs) and 0 for
       // view-through conversions (VTCs) in reports
       "priority": "3",
       "deduplication_key": "3344"
       }],
   }
   Attribution-Reporting-Redirect: https://adtechpartner.example?app_install=567
   

4. API отправляет запрос к каждому URL-адресу, указанному в Attribution-Reporting-Redirect . В этом примере указан только один URL-адрес, поэтому API отправляет запрос по адресу https://adtechpartner.example?app_install=567 .

5. HTTPS-сервер этой рекламной технологии отправляет в ответ заголовки, содержащие следующее:

   Attribution-Reporting-Register-Trigger: {
   "event_trigger_data":[{
     "trigger_data": "5566",
     "priority": "3",
     "deduplication_key": "3344"
   }]
   }
   

   На основе запросов, полученных на предыдущих этапах, регистрируются два триггера.

Возможности атрибуции

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

Применен алгоритм атрибуции с приоритетом источника.

API для формирования отчетов об атрибуции использует алгоритм атрибуции с приоритетом источника для сопоставления триггера (конверсии) с источником атрибуции.

Параметры приоритета позволяют настраивать распределение триггеров по источникам:

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

В случае, когда несколько рекламных технологий регистрируют источник атрибуции , как описано далее на этой странице, эта атрибуция происходит независимо для каждой рекламной технологии. Для каждой рекламной технологии источнику атрибуции с наивысшим приоритетом присваивается событие-триггер. Если существует несколько источников атрибуции с одинаковым приоритетом, API выбирает последний зарегистрированный источник атрибуции. Любые другие источники атрибуции, которые не были выбраны, отбрасываются и больше не могут быть использованы для атрибуции в будущем.

Фильтры триггеров

Регистрация источника и триггера включает в себя дополнительные опциональные функции для выполнения следующих действий:

• Выборочно отфильтровать некоторые триггеры, фактически игнорируя их.
• Выберите данные-триггеры для отчетов на уровне событий на основе исходных данных.
• Выберите параметр, исключающий триггер из отчетов на уровне событий.

Для выборочной фильтрации триггеров рекламная технология может указать данные фильтра, состоящие из ключей и значений, во время регистрации источника и триггера. Если для источника и триггера указан один и тот же ключ, то триггер игнорируется, если пересечение пустое. Например, источник может указать "product": ["1234"] , где product — это ключ фильтра, а 1234 — значение. Если фильтр триггера установлен на "product": ["1111"] , то триггер игнорируется. Если нет ключа фильтра триггера, соответствующего product , то фильтры игнорируются.

Еще один сценарий, в котором платформы рекламных технологий могут захотеть выборочно фильтровать триггеры, — это принудительное сокращение периода истечения срока действия. При регистрации триггера платформа рекламных технологий может указать (в секундах) период ретроспективного анализа с момента совершения конверсии; например, 7-дневный период ретроспективного анализа будет определен следующим образом: "_lookback_window": 604800 // 7d

Чтобы определить, соответствует ли фильтр заданным параметрам, API сначала проверит период ретроспективного анализа. Если такой период доступен, он должен быть меньше или равен продолжительности этого периода.

Платформы рекламных технологий также могут выбирать данные триггера на основе данных исходного события. Например, source_type автоматически генерируется API как navigation или event . При регистрации триггера trigger_data может быть задан как одно значение для "source_type": ["navigation"] и как другое значение для "source_type": ["event"] .

Триггеры исключаются из отчетов на уровне событий, если выполняется хотя бы одно из следующих условий:

• trigger_data не указан.
• Источник и триггер указывают один и тот же ключ фильтра, но значения не совпадают. Обратите внимание, что в этом случае триггер игнорируется как для отчетов на уровне событий, так и для агрегируемых отчетов.

Атрибуция после установки

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

API может поддерживать этот вариант использования, позволяя специалистам по рекламным технологиям устанавливать период атрибуции после установки:

• При регистрации источника атрибуции укажите временной интервал, в течение которого ожидаются установки (обычно 2-7 дней, допустимый диапазон от 1 до 30 дней). Укажите этот временной интервал в секундах.
• При регистрации источника атрибуции укажите временной интервал эксклюзивности атрибуции после установки, в течение которого все события, запускающие установку, должны быть связаны с источником атрибуции, который послужил причиной установки (обычно от 7 до 30 дней, допустимый диапазон от 0 до 30 дней). Укажите этот временной интервал в секундах.
• API для отслеживания атрибуции проверяет факт установки приложения и внутренне связывает установку с источником атрибуции, имеющим приоритет. Однако данные об установке не передаются специалистам по рекламе и не учитываются в лимитах ставок соответствующих платформ.
• Проверка установки приложения доступна для любого загруженного приложения.
• Любые будущие события, происходящие в течение периода после установки, будут отнесены к тому же источнику атрибуции, что и подтвержденная установка, при условии, что этот источник атрибуции соответствует требованиям.

В будущем мы, возможно, рассмотрим возможность расширения функционала для поддержки более сложных моделей атрибуции.

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

Ниже приведён дополнительный список замечаний, касающихся указания авторства после установки:

• Если подтвержденная установка не произойдет в течение количества дней, указанного параметром install_attribution_window , то атрибуция после установки не будет применена.
• Подтвержденные установки не регистрируются рекламными технологическими компаниями и не включаются в отчеты. Они не учитываются в лимитах ставок рекламных технологических компаний. Подтвержденные установки используются только для идентификации источника атрибуции, которому приписывается установка.
• В примере из предыдущей таблицы триггер 1 и триггер 2 представляют собой первое открытие и конверсию после установки, соответственно. Однако платформы рекламных технологий могут регистрировать любой тип триггера. Другими словами, первый триггер не обязательно должен быть триггером первого открытия.
• Если после истечения периода post_install_exclusivity_window будет зарегистрировано больше триггеров, клик 1 по-прежнему может быть учтен, при условии, что этот период не истек и не достигнут лимит запросов.
  • Клик 1 может быть проигран или отброшен, даже если зарегистрирован источник атрибуции с более высоким приоритетом.
• Если приложение рекламодателя удалено и установлено заново, переустановка считается новой подтвержденной установкой.
• Если клик 1 был событием просмотра, то и триггер «первого открытия», и триггер после установки по-прежнему будут к нему привязаны. API ограничивает атрибуцию одним триггером на просмотр, за исключением случая атрибуции после установки, где допускается до двух триггеров на просмотр. В случае атрибуции после установки рекламная технология может получать 2 разных окна отчетов (через 2 дня или по истечении срока действия источника).

Поддерживаются все комбинации путей запуска на основе приложений и веб-интерфейсов.

API для создания отчетов об атрибуции позволяет назначать следующие пути запуска на одном устройстве Android:

• Переход из приложения в приложение: пользователь видит рекламу в приложении, а затем совершает покупку либо в этом приложении, либо в другом установленном приложении.
• Переход из приложения в веб: пользователь видит рекламу в приложении, а затем совершает покупку в мобильном браузере или браузере приложения.
• Веб-приложение: Пользователь видит рекламу в мобильном браузере или приложении, а затем совершает покупку в приложении.
• Веб-к-вебу: Пользователь видит рекламу в мобильном браузере или приложении, а затем совершает покупку либо в том же браузере, либо в другом браузере на том же устройстве.

Мы позволяем веб-браузерам поддерживать новые функции, доступные через веб-интерфейс, такие как функциональность, аналогичная API Attribution Reporting в Privacy Sandbox for the Web , которая может вызывать API Android для включения атрибуции как в приложениях, так и в веб-среде.

Узнайте о том, какие изменения необходимо внести рекламным компаниям и приложениям для поддержки механизмов запуска рекламы для измерения эффективности как в приложениях, так и на веб-платформах .

Расставьте приоритеты для нескольких триггеров в рамках одного источника атрибуции.

Один источник атрибуции может приводить к нескольким триггерам. Например, процесс покупки может включать триггер «установка приложения», один или несколько триггеров «добавление в корзину» и триггер «покупка». Каждый триггер приписывается одному или нескольким источникам атрибуции в соответствии с алгоритмом атрибуции с приоритетом источников , описанным далее на этой странице.

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

В случаях, когда количество триггеров превышает установленные пределы, полезно ввести логику приоритезации, чтобы получить наиболее ценные триггеры. Например, разработчики рекламной технологии могут захотеть отдать приоритет триггерам «покупка» перед триггерами «добавление в корзину».

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

Разрешите нескольким рекламным технологическим компаниям регистрировать источники атрибуции или триггеры.

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

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

• Настройка внутреннего сервера для регистрации и получения отчетов через API.
• Продолжение сотрудничества с существующим партнером по мобильным измерениям.

Источники информации

Перенаправления источника атрибуции поддерживаются в методе registerSource() :

1. Технологический партнер, вызывающий метод registerSource() может предоставить в своем ответе дополнительное поле Attribution-Reporting-Redirect , которое представляет собой набор URL-адресов перенаправления от партнерских технологических партнеров.
2. Затем API вызывает URL-адреса перенаправления, чтобы партнерские рекламные сервисы могли зарегистрировать источник атрибуции.

В поле Attribution-Reporting-Redirect можно указать несколько URL-адресов партнерских рекламных технологий, при этом партнерские рекламные технологии не могут указывать собственное поле Attribution-Reporting-Redirect .

API также позволяет различным рекламным технологиям вызывать функцию registerSource() .

Триггеры

Для регистрации триггеров поддержка сторонних разработчиков осуществляется аналогичным образом: разработчики рекламных технологий могут либо использовать дополнительное поле Attribution-Reporting-Redirect , либо каждый из них может вызвать метод registerTrigger() .

Когда рекламодатель использует несколько рекламных платформ для регистрации одного и того же события-триггера, следует использовать ключ дедупликации . Ключ дедупликации служит для различения повторяющихся сообщений об одном и том же событии, зарегистрированном одной и той же рекламной платформой. Например, рекламная платформа может использовать свой SDK для прямого вызова API для регистрации триггера и указать свой URL-адрес в поле перенаправления вызова другой рекламной платформы. Если ключ дедупликации не предоставлен, повторяющиеся триггеры могут быть отправлены каждой рекламной платформе как уникальные.

Обработка повторяющихся триггеров

Специалист по рекламным технологиям может зарегистрировать один и тот же триггер несколько раз через API. Возможны следующие сценарии:

• Пользователь выполняет одно и то же действие (триггер) несколько раз. Например, пользователь просматривает один и тот же товар несколько раз в одном и том же окне отчета.
• Приложение рекламодателя использует несколько SDK для измерения конверсий, которые перенаправляют на одну и ту же рекламную платформу. Например, приложение рекламодателя использует двух партнеров по измерению, MMP #1 и MMP #2. Оба MMP перенаправляют на рекламную платформу #3. Когда срабатывает триггер, оба MMP регистрируют этот триггер в API отчетов по атрибуции. Затем рекламная платформа #3 получает два отдельных перенаправления — одно от MMP #1 и одно от MMP #2 — для одного и того же триггера.

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

Рекомендуемый метод: дедупликационный ключ.

Рекомендуемый метод заключается в том, чтобы приложение рекламодателя передавало уникальный ключ дедупликации всем рекламным технологиям или SDK, которые оно использует для измерения конверсий. Когда происходит конверсия, приложение передает ключ дедупликации рекламным технологиям или SDK. Затем эти рекламные технологии или SDK продолжают передавать ключ дедупликации перенаправлениям, используя параметр в URL-адресах, указанных в Attribution-Reporting-Redirect .

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

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

Альтернативный метод: специалисты по рекламным технологиям согласовывают типы триггеров для каждого рекламодателя.

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

Технологии, инициирующие вызов регистрации триггера (например, SDK), включают параметр в URL-адреса, указанные в Attribution-Reporting-Redirect , например, duplicate_trigger_id . Этот параметр duplicate_trigger_id может содержать информацию, такую ​​как имя SDK и тип триггера для данного рекламодателя. Затем технологии могут отправлять подмножество этих дублирующихся триггеров в отчеты на уровне событий. Технологии также могут включать duplicate_trigger_id в свои ключи агрегации.

Пример межсетевой атрибуции

В примере, описанном в этом разделе, рекламодатель использует две платформы для показа рекламы (Ad tech A и Ad tech B) и одного партнера по измерению эффективности (MMP).

Для начала компаниям Ad tech A, Ad tech B и MMP необходимо пройти регистрацию для использования API отчетов по атрибуции. Дополнительную информацию см. в разделе «Регистрация учетной записи в песочнице конфиденциальности» .

В следующем списке представлена ​​гипотетическая последовательность действий пользователя, каждое из которых происходит с интервалом в один день, а также описано, как API отчетов по атрибуции обрабатывает эти действия в отношении рекламных технологий A, B и MMP:

День 1: Пользователь кликает на объявление, показанное компанией Ad tech A.

Компания Ad tech A вызывает registerSource() со своим URI. API отправляет запрос к этому URI, и клик регистрируется с использованием метаданных из ответа сервера Ad tech A.

Рекламная технология A также включает URI MMP в заголовок Attribution-Reporting-Redirect . API отправляет запрос на URI MMP, и клик регистрируется с метаданными из ответа сервера MMP.

День 2: Пользователь кликает на объявление, показанное компанией Ad tech B.

Компания Ad tech B вызывает registerSource() со своим URI. API отправляет запрос к этому URI, и клик регистрируется с использованием метаданных из ответа сервера Ad tech B.

Как и Ad tech A, Ad tech B также включила URI MMP в заголовок Attribution-Reporting-Redirect . API отправляет запрос на URI MMP, и клик регистрируется с метаданными из ответа сервера MMP.

День 3: Пользователь просматривает рекламу, размещенную компанией Ad tech A.

API отвечает так же, как и в первый день, за исключением того, что для Ad tech A и MMP регистрируется представление.

День 4: Пользователь устанавливает приложение, которое использует MMP для измерения конверсии.

MMP вызывает registerTrigger() со своим URI. API отправляет запрос на указанный URL, и конверсия регистрируется с использованием метаданных из ответа сервера MMP.

MMP также включает URI рекламных платформ A и B в заголовок Attribution-Reporting-Redirect . API отправляет запросы на серверы рекламных платформ A и B, и конверсия регистрируется соответствующим образом с использованием метаданных из ответов серверов.

Следующая диаграмма иллюстрирует процесс, описанный в предыдущем списке:

Атрибуция работает следующим образом:

• В рекламной технологической компании A приоритет отдается кликам, а не просмотрам, поэтому установка приложения приписывается клику в первый день.
• Установка приложения Ad tech B регистрируется на второй день.
• MMP устанавливает приоритет кликов выше, чем просмотров, и приписывает установку клику второго дня. Клик второго дня имеет наивысший приоритет и является самым недавним рекламным событием.

Межсетевая атрибуция без перенаправлений

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

Поток высокого уровня

1. При регистрации источника рекламная сеть, предоставляющая контент, передает свои ключи агрегации источников.
2. При регистрации триггера рекламодатель или партнер по измерению выбирает, какие ключевые элементы на стороне источника использовать, и указывает конфигурацию атрибуции.
3. Атрибуция основана на конфигурации атрибуции, общих ключах и любых источниках, которые были фактически зарегистрированы данным рекламодателем или партнером по измерению (например, из другой рекламной сети, которая включила перенаправления).
4. Если триггер связан с источником, не использующим перенаправление для показа рекламы, рекламодатель или партнер по измерению может получить сводную отчетность, объединяющую ключевые элементы источника и триггера, определенные на шаге №2.

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

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

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

Запустить регистрацию

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

Additionally, the measurement ad tech must also specify their waterfall attribution logic using a new attribution configuration API call. In this config, the ad tech can specify source priority, expiry, and filters for sources that they had no visibility into (for example, sources that did not use a redirect).

Атрибуция

The Attribution Reporting API performs source-prioritized, last-touch attribution for the measurement ad tech based on their attribution config, shared keys, and any sources they registered. For example:

• The user clicked on ads served by ad techs A, B, C, and D. The user then installed the advertiser's app, which uses a measurement ad tech partner (MMP).
• Ad tech A redirects its sources to the MMP.
• Ad techs B and C don't redirect, but share their aggregation keys.
• Ad tech D neither redirects nor shares aggregation keys.

The MMP registers a source from Ad tech A, and defines an attribution config that includes Ad tech B and Ad tech D.

Attribution for the MMP now includes:

• Ad tech A, since the MMP registered a source from that ad tech's redirect.
• Ad tech B, since Ad tech B shared keys and the MMP included it in their attribution config.

Attribution for the MMP does not include:

• Ad tech C, since the MMP did not include it in their attribution config.
• Ad tech D, since they did not redirect nor share aggregation keys.

Отладка

To support debugging for cross-network attribution without redirects, an additional field, shared_debug_key , is available for ad techs to set upon source registration. If set on the original source registration, it will also be set on the corresponding derived source as debug_key during trigger registration for cross-network attribution without redirects. This debug key is attached as source_debug_key in event and aggregate reports.

This debug feature will only be supported for cross-network attribution without redirects under the following scenarios:

• App to app measurement where AdId is permitted
• App to web measurement where AdId is permitted and matching across both the app source and the web trigger
• Web to web measurement (on the same browser app) when ar_debug ` is present on both source and trigger

Key discovery for cross-network attribution without redirects

Key discovery is intended to streamline how ad techs (usually MMPs) implement their attribution config for the purposes of cross-network attribution when one or several serving ad techs are using shared aggregation keys (as described in Cross-network attribution without redirects above).

When an MMP queries the Aggregation Service to generate summary reports for campaigns that include derived sources, Aggregation Service requires the MMP to specify the list of possible keys as input for the aggregation job. In some cases, the list of potential source aggregation keys may be very large, or unknown. Large lists of possible keys are challenging to track, and are also likely to be quite complex and costly to process. Consider the following examples:

• List of all possible keys is large:
  • A serving ad network is executing a complex user acquisition initiative that includes 20 campaigns, each with 10 ad groups, and each ad group with 5 creatives that are refreshed every week based on performance.
• List of all possible keys is unknown:
  • A serving ad network is serving ads across many mobile apps where the full list of publisher app IDs is not known at campaign launch.
  • An advertiser is working across multiple serving ad networks that are not redirecting to the MMP on source registration; each serving ad network has a different key structure and values, which may not be shared in advance with the MMP.

With the introduction of key discovery:

• The Aggregation Service no longer requires a full enumeration of possible aggregation keys.
• Instead of having to specify the full list of possible keys, an MMP can create an empty (or partially empty) set of keys and set a threshold, so that only (non pre-declared) keys with values exceeding the threshold are included in the output.
• MMP receives a summary report that includes noisy values for keys that have contributing values above the set threshold. The report may also include keys that have no associated real user contributions and are purely noised.
• MMP uses the x_network_bit_mapping field in trigger registration to determine which ad tech corresponds to which key.
• MMP can then contact the appropriate serving ad tech to understand the values in the source key.

In summary, key discovery enables MMPs to obtain aggregation keys without knowing them in advance, and avoid processing a large volume of source keys at the expense of added noise.

Daisy chain redirects

By providing multiple Attribution-Reporting-Redirect headers in a source or trigger registration HTTPS server-response, an ad tech can use the Attribution Reporting API to perform multiple source and trigger registrations with a single registration API call.

In the server-response, the ad tech can also include a single Location (302 redirect) header with a URL, which in turn leads to another registration, up to a set limit.

Both types of headers are optional and none can be provided if redirects are not needed. Either one or both types of headers may be provided. Source and trigger registration requests (including redirects) are retried in case of network failure. The number of retries per request is limited to a fixed number to avoid significant impact on the device.

Redirects are not accepted for registerWebSource and registerWebTrigger used by browsers. More details can be found in the Cross Web and App Implementation Guide .

View measurement data in attribution reports

The Attribution Reporting API enables the following types of reports, described in more detail later on this page:

• Event-level reports associate a particular attribution source (click or view) with limited bits of high-fidelity trigger data.
• Aggregatable reports aren't necessarily tied with a specific attribution source. These reports provide richer, higher-fidelity trigger data than event-level reports, but this data is only available in an aggregate form.

These two report types are complementary to each other and can be used simultaneously.

Event-level reports

After a trigger is attributed to an attribution source, an event-level report is generated and stored on the device until it can be sent back to each ad tech's postback URL during one of the time windows for sending reports , described in more detail later on this page.

Event-level reports are useful when very little information is needed about the trigger. Event-level trigger data is limited to 3 bits of trigger data for clicks—which means that a trigger can be assigned one of eight categories—and 1 bit for views. In addition, event-level reports don't support encoding of high-fidelity trigger-side data, such as a specific price or trigger time. Because attribution happens on device, there is no support for cross-device analytics in the event-level reports.

The event-level report contains data such as the following:

• Destination: Advertiser app package name or eTLD+1 where the trigger happened
• Attribution Source ID: The same attribution source ID that was used for registering an attribution source
• Trigger type: 1 or 3 bits of low-fidelity trigger data, depending on the type of attribution source

Privacy-preserving mechanisms applied to all reports

The following limits are applied after priorities regarding attribution sources and triggers are taken into consideration.

Limits on number of ad techs

There are limits on the number of ad techs that can register or receive reports from the API, with a current proposal of the following:

• 100 ad techs with attribution sources per {source app, destination app, 30 days, device}.
• 10 ad techs with attributed triggers per {source app, destination app, 30 days, device}.
• 20 ad techs can register a single attribution source or trigger (via Attribution-Reporting-Redirect )

Limits on number of unique destinations

These limits make it difficult for a set of ad techs to collude by querying a large number of apps to understand a given user's app usage behavior.

• Across all registered sources, across all ad techs, the API supports no more than 200 unique destinations, per source app, per minute.
• Across all registered sources, for a single ad tech, the API supports no more than 50 unique destinations, per source app, per minute. This limit prevents one ad tech from using up the entire budget from the previously mentioned rate limit.

Expired sources don't count towards the rate limits.

One reporting origin per source app per day

A given ad tech platform may only use one reporting origin to register sources on a publisher app, for a given device, on the same day. This rate limit prevents ad techs from using multiple reporting origins to access additional privacy budget.

Consider the following scenario, where a single ad tech wants to use multiple reporting origins to register sources on a publisher app, for a single device.

1. Ad tech A's reporting origin 1 registers a source on App B
2. 12 hours later, ad tech A's reporting origin 2 attempts to register a source on App B

The second source, for Ad tech A's reporting origin 2, would be rejected by the API. Ad tech A's reporting origin 2 wouldn't be able to successfully register a source on the same device on App B until the following day.

Cooldown and rate limits

To limit the amount of user identity leakage between a {source, destination} pair, the API throttles the amount of total information sent in a given time period for a user.

The current proposal is to limit each ad tech to 100 attributed triggers per {source app, destination app, 30 days, device}.

Number of unique destinations

The API limits the number of destinations that an ad tech can try to measure. The lower the limit, the harder it is for an ad tech to use the API to attempt to measure user browsing activity that isn't associated with ads being shown.

The current proposal is to limit each ad tech to 100 distinct destinations with non-expired sources per source app.

Privacy-preserving mechanisms applied to event-level reports

Limited fidelity of trigger data

The API provides 1 bit for view-through triggers and 3 bits for click-through triggers. Attribution sources continue to support the full 64 bits of metadata.

You should evaluate if and how to reduce the information expressed in triggers so they work with the limited number of bits available in event-level reports.

Framework for differential privacy noise

A goal of this API is to allow event-level measurement to satisfy local differential privacy requirements by using k-randomized responses to generate a noisy output for each source event.

Noise is applied on whether an attribution source event is reported truthfully. An attribution source is registered on the device with probability $ 1-p $ that the attribution source is registered as normal, and with probability $ p $ that the device randomly chooses among all possible output states of the API (including not reporting anything at all, or reporting multiple fake reports).

The k-randomized response is an algorithm that is epsilon differentially private if the following equation is satisfied:

For low values of ε, the true output is protected by the k-randomized response mechanism. Exact noise parameters are works in progress and are subject to change based on feedback, with a current proposal of the following:

• p=0.24% for navigation sources
• p=0.00025% for event sources

Limits on available triggers (conversions)

There are limits on the number of triggers per attribution source, with a current proposal of the following:

• 1-2 triggers for ad view attribution sources (2 triggers only available in the case of post-install attribution)
• 3 triggers for click ad attribution sources

Specific time windows for sending reports (default behaviour)

Event-level reports for ad view attribution sources are sent 1 hour after the source expires. This expiry date can be configured, but it cannot be less than 1 day or more than 30 days. If two triggers are attributed to an ad view attribution source (via post-install attribution )), event-level reports can be sent at the reporting window intervals specified as follows.

Event-level reports for ad click attribution sources cannot be configured and are sent before or when the source expires, at specified points in time relative to when the source was registered. The time between the attribution source and expiry is split into multiple reporting windows. Each reporting window has a deadline (from the attribution source time). At the end of each reporting window, the device collects all the triggers that have occurred since the previous reporting window and sends a scheduled report. The API supports the following reporting windows:

• 2 days: The device collects all the triggers that occurred at most 2 days after the attribution source was registered. The report is sent 2 days and 1 hour after the attribution source is registered.
• 7 days: The device collects all the triggers that occurred more than 2 days but no more than 7 days after the attribution source was registered. The report is sent 7 days and 1 hour after the attribution source is registered.
• A custom length of time, defined by the "expiry" attribute of an attribution source. The report is sent 1 hour after the specified expiry time. This value cannot be less than 1 day or more than 30 days.

Flexible event-level configuration

The default configuration for event level reporting is what ad techs are advised to start using as they begin utility testing, but may not be ideal for all use cases. The Attribution Reporting API will support optional, and more flexible configurations so that ad techs have increased control over the structure of their event level reports and are able to maximize the utility of the data.

This additional flexibility will be introduced into the Attribution Reporting API in two phases:

• Phase 1: Lite flexible event level configuration
  • This version provides a subset of the full features, and can be used independently of Phase 2.
• Phase 2: Full version of flexible event level configuration

Phase 1 (Lite flexible event level) could be used to:

• Vary the frequency of reports by specifying the number of reporting windows
• Vary the number of attributions per source registration
• Reduce the amount of total noise by decreasing the preceding parameters
• Configure reporting windows rather than using the defaults

Phase 2 (Full flexible event level) could be used to do all of the capabilities in Phase 1 and:

• Vary the trigger data cardinality in a report
• Reduce the amount of total noise by decreasing the trigger data cardinality

Reducing one dimension of the default configuration allows the ad tech to increase another dimension. Alternatively, the total amount of noise in an event level report may be reduced by net decreasing the parameters mentioned earlier.

In addition to dynamically setting noise levels based on an ad tech's chosen configuration, we will have some parameter limits to avoid large computation costs and configurations with too many output states (where noise will increase considerably). Here is an example set of restrictions. Feedback is encouraged on the design proposal:

• Maximum of 20 total reports, globally and per trigger_data
• Maximum of 5 possible reporting windows per trigger_data
• Maximum of 32 trigger data cardinality (not applicable for Phase 1: Lite Flexible Event Level)

As ad techs start using this feature, be advised that using extrema values may result in a large amount of noise, or failure to register if privacy levels are not met.

Aggregatable reports

Before using aggregatable reports, you must set up your cloud account and start receiving aggregatable reports.

Aggregatable reports provide higher-fidelity trigger data from the device more quickly, beyond what is offered for event-level reports . This higher-fidelity data can only be learned in aggregate , and isn't associated with a particular trigger or user. Aggregation keys are up to 128 bits, and this allows aggregatable reports to support reporting use cases such as the following:

• Reports for trigger values, such as revenue
• Handling more trigger types

In addition, aggregatable reports use the same source-prioritized attribution logic as event-level reports, but they support more conversions attributed to a click or view.

The overall design of how the Attribution Reporting API prepares and sends aggregatable reports, shown in the diagram, is as follows:

1. The device sends encrypted aggregatable reports to the ad tech. In a production environment, ad techs can't use these reports directly.
2. The ad tech sends a batch of aggregatable reports to the aggregation service for aggregation.
3. The aggregation service reads a batch of aggregatable reports, decrypts and aggregates them.
4. The final aggregates are sent back to the ad tech in a summary report .

Aggregatable reports contain the following data related to attribution sources:

• Destination: The app's package name or eTLD+1 web URL where the trigger happened.
• Date: The date when the event represented by the attribution source occurred.
• Payload: Trigger values, collected as encrypted key/value pairs, which is used in the trusted aggregation service to compute aggregations.

Aggregation services

The following services provide data aggregation capabilities and safeguard against unauthorized access to aggregated data..

These services are managed by different parties, which are described in more detail later on this page:

• The aggregation service is the only one that ad techs are expected to deploy.
• The key management and aggregatable report accounting services are run by trusted parties called coordinators . These coordinators attest that the code running the aggregation service is the publicly-available code provided by Google and that all aggregation service users have the same key and aggregatable report accounting services applied to them.

Aggregation service

Ad tech platforms must, in advance, deploy an aggregation service that's based on binaries provided by Google.

This aggregation service operates in a Trusted Execution Environment (TEE) hosted in the cloud. A TEE offers the following security benefits:

• It ensures that the code operating in the TEE is the specific binary offered by Google. Unless this condition is satisfied, the aggregation service can't access the decryption keys it needs to operate.
• It offers security around the running process, isolating it from external monitoring or tampering.

These security benefits make it safer for an aggregation service to perform sensitive operations, such as accessing encrypted data.

For more information on the design, workflow, and security considerations of the aggregation service, see the aggregation service document on GitHub.

Key management service

This service verifies that an aggregation service is running an approved version of the binary and then provides the aggregation service in the ad tech with the correct decryption keys for their trigger data.

Aggregatable report accounting

This service tracks how often an ad tech's aggregation service accesses a specific trigger—which can contain multiple aggregation keys—and limits access to the appropriate number of decryptions. Refer to the Aggregation Service for the Attribution Reporting API design proposal for details.

Aggregatable Reports API

The API for creating contributions to aggregatable reports uses the same base API as when registering an attribution source for event-level reports. The following sections describe the extensions of the API.

Register the aggregatable source data

When the API makes a request to the Attribution Source URI, the ad tech can register a list of aggregation keys, named histogram_contributions , by responding with a new field called aggregation_keys in HTTP header Attribution-Reporting-Register-Source , with key as the key_name and value as key_piece :

• (Key) Key name: A string for the name of the key. Used as a join key to combine with trigger-side keys to form the final key.
• (Value) Key piece: A bitstring value for the key.

The final histogram bucket key is fully defined at trigger time by performing a binary OR operation on these pieces and the trigger-side pieces.

Final keys are restricted to a maximum of 128 bits; keys longer than this are truncated. This means that hex strings in the JSON should be limited to at most 32 digits.

Learn more about how aggregation keys are structured and how you can configure aggregation keys.

In the following example, an ad tech uses the API to collect the following:

• Aggregate conversion counts at a campaign level
• Aggregate purchase values at a geo level

// This is where the Attribution-Reporting-Register-Source object appears when
// an ad tech registers an attribution source.

// Attribution source metadata specifying histogram contributions in aggregate report.
Attribution-Reporting-Register-Source:
…
aggregation_keys: {
  // Generates a "0x159" key piece named (low order bits of the key) for the key
  // named "campaignCounts".
  // User saw an ad from campaign 345 (out of 511).

  "campaignCounts": "0x159",
  // Generates a "0x5" key piece (low order bits of the key) for the key name "geoValue"
  // Source-side geo region = 5 (US), out of a possible ~100 regions.
  "geoValue": "0x5"
}

Register the aggregatable trigger

Trigger registration includes two additional fields.

The first field is used to register a list of aggregate keys on the trigger side. The ad tech should respond back with the aggregatable_trigger_data field in HTTP header Attribution-Reporting-Register-Trigger , with the following fields for each aggregate key in the list:

• Key piece: A bitstring value for the key.
• Source keys: A list of strings with the names of attribution source side keys that the trigger key should be combined with to form the final keys.

The second field is used to register a list of values which should contribute to each key. The ad tech should respond back with the aggregatable_values field in the HTTP header Attribution-Reporting-Register-Trigger . The second field is used to register a list of values which should contribute to each key, which can be integers in the range $ [1, 2^{16}] $.

Each trigger can make multiple contributions to the aggregatable reports. The total amount of contributions to any given source event is bound by an $ L1 $ parameter, which is the maximum sum of contributions (values) across all aggregate keys for a given source. $ L1 $ refers to the L1 sensitivity or norm of the histogram contributions per source event. Exceeding these limits causes future contributions to silently drop. The initial proposal is to set $ L1 $ to $ 2^{16} $ (65536).

The noise in the aggregation service is scaled in proportion to this parameter. Given this, it is recommended to appropriately scale the values reported for a given aggregate key, based on the portion of $ L1 $ budget allocated to it. This approach helps make sure that the aggregate reports retain the highest possible fidelity when noise is applied. This mechanism is highly flexible and can support many aggregation strategies.

In the following example, the privacy budget is split equally between campaignCounts and geoValue by splitting the $ L1 $ contribution to each:

// This is where the Attribution-Reporting-Register-Trigger object appears
// when an ad tech registers a conversion trigger.

// Specify a list of dictionaries that generates aggregation keys.
Attribution-Reporting-Register-Trigger:{
    …
    "aggregatable_trigger_data":

    [
    // Each dictionary independently adds pieces to multiple source keys.
    {
    // Conversion type purchase = 2 at a 9-bit offset, i.e. 2 << 9.
    // A 9-bit offset is needed because there are 511 possible campaigns, which
    // will take up 9 bits in the resulting key.
        "key_piece": "0x400",// Conversion type purchase = 2
        // Apply this key piece to:
        "source_keys": ["campaignCounts"]
    },
    {
    // Purchase category shirts = 21 at a 7-bit offset, i.e. 21 << 7.
    // A 7-bit offset is needed because there are ~100 regions for the geo key,
    // which will take up 7 bits of space in the resulting key.
        "key_piece": "0xA80",
        // Apply this key piece to:
        "source_keys": ["geoValue", "nonMatchingIdsListedHereAreIgnored"]
    }
    ]

    // Specify an amount of an abstract value which can be integers in [1, 2^16] to
    // contribute to each key that is attached to aggregation keys in the order that
    // they're generated.
    aggregatable_values:
    {
    // Privacy budget for each key is L1 / 2 = 2^15 (32768).
    // Conversion count was 1.
    // Scale the count to use the full budget allocated: 1 * 32768 = 32768.
        "campaignCounts": 32768,

    // Purchase price was $52.
    // Purchase values for the app range from $1 to $1,024 (integers only).
    // Scaling factor applied is 32768 / 1024 = 32.
    // For $52 purchase, scale the value by 32 ($52 * 32 = $1,664).
        "geoValue": 1664
    }
}

The preceding example generates the following histogram contributions:

[
  // campaignCounts:
  {
    "key": "0x559", // = 0x159 | 0x400
    "value": 32768
  },
  // geoValue:
  {
    "key": "0xA85",  // = 0x5 | 0xA80
    "value": 1664
  }
]

The scaling factors can be inverted in order to obtain the correct values, modulo noise that is applied:

L1 = 65536
trueCampaignCounts = campaignCounts / (L1 / 2)
trueGeoValue = geoValue / (L1 / 2) * 1024

Дифференцированная конфиденциальность

A goal of this API is to have a framework which can support differentially private aggregate measurement. This can be achieved by adding noise proportional to the $ L1 $ budget, such as picking noise with the following distribution:

Protected Audience API and Attribution Reporting API Integration

Cross-API integration across the Protected Audience and Attribution Reporting APIs enables adtechs to evaluate their attribution performance across various remarketing tactics in order to understand which types of audiences deliver the highest ROI.

Through this cross-API integration, adtechs can:

• Create a key-value map of URIs to be used for both 1) interaction reporting and 2) source registration.
• Include CustomAudience in their source-side key mapping for aggregate summary reporting (using the Attribution Reporting API).

When a user sees or clicks on an ad:

• The URL used to report those interactions using Protected Audience will also be used to register a view or click as an eligible source with the Attribution Reporting API.
• The ad tech may choose to pass CustomAudience (or other relevant contextual information about the ad such as ad placement or view duration) using that URL so this metadata can propagate down to summary reports when the ad tech is reviewing aggregate campaign performance.

For more information on how this is enabled within Protected Audience, see the relevant section of the Protected Audience API explainer .

Registration priority, attribution, and reporting examples

This example showcases a set of user interactions and how ad tech defined attribution source and trigger priorities could affect attributed reports. In this example, we assume the following:

• All attribution sources and triggers are registered by the same ad tech, for the same advertiser.
• All attribution sources and triggers are happening during the first event reporting window (within 2 days of initially displaying the ads in a publisher app).

Consider the case where a user does the following:

1. The user sees an ad. Ad tech registers an attribution source with the API, with a priority of 0 (view #1).
2. The user sees an ad, registered with a priority of 0 (view #2).
3. The user clicks an ad, registered with a priority of 1 (click #1).
4. The user converts (reaches landing page) in an advertiser app. The ad tech registers a trigger with the API, with a priority of 0 (conversion #1).
   • As triggers are registered, the API performs attribution first before generating reports.
   • There are 3 attribution sources available: view #1, view #2, and click #1. The API attributes this trigger to click #1 because it's the highest priority and most recent.
   • View #1 and view #2 are discarded and are no longer eligible for future attribution.
5. The user adds an item to their cart in the advertiser app, registered with a priority of 1 (conversion #2).
   • Click #1 is the only eligible attribution source. The API attributes this trigger to click #1.
6. The user adds an item to their cart in the advertiser app, registered with a priority of 1 (conversion #3).
   • Click #1 is the only eligible attribution source. The API attributes this trigger to click #1.
7. The user adds an item to their cart in the advertiser app, registered with a priority of 1 (conversion #4).
   • Click #1 is the only eligible attribution source. The API attributes this trigger to click #1.
8. The user makes a purchase in the advertiser app, registered with a priority of 2 (conversion #5).
   • Click #1 is the only eligible attribution source. The API attributes this trigger to click #1.

Event-level reports have the following characteristics:

• By default, the first 3 triggers attributed to a click and the first trigger attributed to a view are sent out after applicable reporting windows.
• Within the reporting window, if there are triggers registered with higher priority, those take precedence and replace the most recent trigger.
• In the preceding example, the ad tech receives 3 event reports after the 2-day reporting window, for conversion #2, conversion #3, and conversion #5.
  • All 5 triggers are attributed to click #1. By default, the API would send out reports for the first 3 triggers: conversion #1, conversion #2, and conversion #3.
  • However, conversion #4's priority ( 1 ) is higher than conversion #1's priority ( 0 ). Conversion #4's event report replaces conversion #1's event report to be sent out.
  • Additionally, conversion #5's priority ( 2 ) is higher than any other trigger. Conversion #5's event report replaces conversion #4's report to be sent out.

Aggregatable reports have the following characteristics:

• Encrypted aggregatable reports are sent to the ad tech as soon as they are processed, a few hours after the triggers are registered.

  As an ad tech, you create their batches based on the information that comes unencrypted in your aggregatable reports. This information is contained in the shared_info field in your aggregatable report, and includes timestamp and reporting origin. You can't batch based on any encrypted information in your aggregation key-value pairs. Some basic strategies you can follow are batching reports daily or weekly. Ideally, batches should contain at least 100 reports each.

• It's up to the ad tech on when and how to batch the aggregatable reports and send to the aggregation service.

• Compared to event-level reports, encrypted aggregatable reports can attribute more triggers to a source.

• In the preceding example, 5 aggregatable reports are sent out, one for each registered trigger.

Transitional debugging reports

The Attribution Reporting API is a new and fairly complex way to do attribution measurement without cross-app identifiers. As such, we are supporting a transitional mechanism to learn more information about attribution reports when the advertising ID is available (the user has not opted out of personalization using the advertising ID and the publisher or advertiser app has declared AdID permissions) . This ensures that the API can be fully understood during roll-out, help flush out any bugs, and more readily compare the performance to advertising ID-based alternatives. There are two types of debugging reports: attribution-success and verbose.

Read the guide on transitional debugging reports for details on debugging reports with app-to-web and web-to-app measurement.

Attribution-success debugging reports

Source and trigger registrations both accept a new 64-bit debug_key field (formatted as a String), which the ad tech populates. source_debug_key and trigger_debug_key are passed unaltered in both event-level and aggregate reports.

If a report is created with both source and trigger debug keys, a duplicate debug report is sent with limited delay to a .well-known/attribution-reporting/debug/report-event-attribution endpoint. The debug reports are identical to normal reports, including both debug key fields. Including these keys in both allows tying normal reports to the separate stream of debug reports.

• For event-level reports:
  • Duplicate debug reports are sent with limited delay and therefore aren't suppressed by limits on available triggers , which allows ad tech to understand the impact of those limits for event-level reports.
  • Event-level reports associated with false trigger events won't have trigger_debug_key s. This allows ad tech to more closely understand how noise is applied in the API.
• For aggregatable reports:
  • We will support a new debug_cleartext_payload field which contains the decrypted payload, only if both source_debug_key and trigger_debug_key are set.

Verbose debugging reports

Verbose debugging reports allow developers to monitor certain failures in the attribution source or trigger registrations. These debugging reports are sent with limited delay after attribution source or trigger registrations to a . well-known/attribution-reporting/debug/verbose endpoint.

Each verbose report contains the following fields:

• Type : what caused the report to be generated. See the full list of verbose report types .
  • In general, there are source verbose reports and trigger verbose reports.
  • Source verbose reports require the advertising ID to be available to the publisher app, and trigger verbose reports require the advertising ID to be available to the advertiser app.
  • Trigger verbose reports (with the exception of trigger-no-matching-source ) can optionally include the source_debug_key . This can only be included if the advertising ID is also available to the publisher app.
• Body : The report's body, which depends on its type.

Ad techs need to opt in to receive verbose debugging reports using a new debug_reporting dictionary field in the Attribution-Reporting-Register_Source and Attribution-Reporting-Register-Trigger headers.

• Source verbose reports require opt-in on the source registration header only.
• Trigger debug reports require opt-in on the trigger registration header only.

How to use debug reports

If a conversion took place (according to your existing measurement system) and a debug report was received for that conversion, this means the trigger was successfully registered.

For each debug attribution report, check if you're receiving a regular attribution report that matches the two debug keys.

When there's no match, it can be for a number of reasons.

Works as intended:

• Privacy-preserving API behaviors:
  • A user hits the report rate limit—causing all subsequent reports to not be sent in the time period; or a source is removed due to the pending destination limit.
  • For event-level reports: the report is subject to randomized response (noise) and is suppressed, or you may receive a randomized report.
  • For event-level reports: the limit of three (for clicks) or one (for views) reports has been reached, and subsequent reports have no explicit priority set, or a priority that is lower than existing reports.
  • The contribution limits for aggregatable reports have been exceeded.
• Ad tech-defined business logic:
  • A trigger is filtered out using filters or priority rules.
• Time delays or interactions with network availability (eg, the user turns off their device for an extended period of time).

Unintended causes:

• Implementation issues:
  • The source header is misconfigured.
  • The trigger header is misconfigured.
  • Other configuration issues.
• Device or network issues:
  • Failures due to network conditions.
  • Source or trigger registration response doesn't reach the client.
  • API bug.

Future considerations & open questions

The Attribution Reporting API is a work in progress. We're also exploring future potential features, such as non-last-click attribution models and cross-device measurement use cases.

Additionally, we'd like to seek feedback from the community on a few issues:

1. Are there any use cases where you'd like the API to send out reports for the verified install? These reports would count against ad tech platforms' respective rate limits.
2. Do you foresee any difficulties with passing the InputEvent from the app to ad tech for source registration?
3. Do you have any special attribution use cases for pre-loaded apps or re-installed apps?