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

Обеспечить обратную связь

Недавние обновления

  • Обновлен список предстоящих изменений и известных проблем.
  • Представлена ​​облегченная гибкая конфигурация на уровне событий как мост к полной гибкой конфигурации на уровне событий.
  • Начиная с сентября 2023 года, registerWebSource , registerWebTrigger , registerAppSource и registerAppTrigger должны использовать строки для полей, которые ожидают числового значения (например, priority , source_event_id , debug_key , trigger_data , deduplication_key и т. д.).
  • В четвертом квартале 2023 года в Android Attribution Reporting API будет добавлена ​​поддержка Google Cloud для создания сводных отчетов с использованием службы агрегирования в Google Cloud. Более точные сроки указаны здесь. Дополнительную информацию о настройке службы агрегации с Google Cloud см. в руководстве по развертыванию.
  • Новые ограничения на тарифы, сохраняющие конфиденциальность, для количества уникальных направлений.
  • Обновленные функции триггерных фильтров окна ретроспективного анализа появятся в первом квартале 2024 года. Дополнительную информацию см. в примечании.

Обзор

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

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

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

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

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

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

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

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

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

Зарегистрируйте источник атрибуции (нажмите или просмотрите)

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

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

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

  • Идентификатор исходного события . Это значение представляет данные на уровне события, связанные с этим источником атрибуции (клик по объявлению или просмотр). Должно быть 64-битное целое число без знака, отформатированное как строка.
  • Назначение : источник, eTLD+1 которого или имя пакета приложения, в котором происходит триггерное событие.
  • Срок действия (необязательно) : срок действия в секундах, когда источник должен быть удален с устройства. По умолчанию — 30 дней, минимальное значение — 1 день, максимальное — 30 дней. Это значение округляется до ближайшего дня. Может быть отформатировано как 64-битное целое число без знака или строка.
  • Окно отчета о событии (необязательно) : продолжительность в секундах после регистрации источника, в течение которой для этого источника могут быть созданы отчеты о событиях. Если окно отчета о событии прошло, но срок действия еще не истек, триггер все еще можно сопоставить с источником, но отчет о событии для этого триггера не отправляется. Не может быть больше срока действия. Может быть отформатировано как 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. Это обрабатывается WebView, напрямую вызывающим registerSource() в качестве фонового запроса. Этот вызов связывает источник атрибуции с приложением, а не с источником верхнего уровня. Также поддерживается регистрация источников встроенного веб-контента в контексте браузера; Для этого и вызывающим API, и приложениям необходимо настроить параметры. Инструкции для вызывающих API см. в разделе Регистрация источника атрибуции и триггера из WebView, а инструкции для приложений — источник атрибуции и триггер регистрации из WebView .

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

Регистрация триггера (конверсии)

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

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

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

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

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

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

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

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

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

    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 отчетов по атрибуции проверяет, когда происходит установка приложения, и внутренне приписывает установку источнику атрибуции с приоритетом источника. Однако установка не отправляется рекламным специалистам и не учитывается в соответствующих ограничениях скорости платформы.
  • Проверка установки приложения доступна для любого загруженного приложения.
  • Любые будущие триггеры, возникающие в окне атрибуции после установки, относятся к тому же источнику атрибуции, что и проверенная установка, если этот источник атрибуции соответствует критериям.

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

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

Событие День, когда происходит событие Примечания
Нажмите 1 1 install_attribution_window установлено значение 172800 (2 дня), а для post_install_exclusivity_window установлено значение 864000 (10 дней).
Проверенная установка 2 API внутренне атрибутирует проверенные установки, но эти установки не считаются триггерами. Поэтому на этом этапе никакие отчеты не отправляются.
Триггер 1 (первое открытие) 2 Первый триггер зарегистрирован рекламной технологией. В этом примере он представляет собой первое открытие, но может быть любым типом триггера.
Приписывается клику 1 (соответствует атрибуции проверенной установки).
Нажмите 2 4 Использует те же значения для install_attribution_window и post_install_exclusivity_window , что и для Click 1.
Триггер 2 (после установки) 5 Второй триггер зарегистрирован рекламной технологией. В этом примере он представляет собой конверсию после установки, например покупку.
Приписывается клику 1 (соответствует атрибуции проверенной установки).
Клик 2 отбрасывается и не подлежит дальнейшей атрибуции.

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

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

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

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

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

Мы разрешаем веб-браузерам поддерживать новые функции, доступные в Интернете, например функции, аналогичные Privacy Sandbox для веб-интерфейса Attribution Reporting API , который может вызывать 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 в свои ключи агрегирования.

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

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

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

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

День 1. Пользователь нажимает на объявление, предоставляемое рекламной технологией А.

Рекламная технология А вызывает registerSource() со своим URI. API отправляет запрос к URI, и клик регистрируется с использованием метаданных ответа сервера специалиста по рекламе А.

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

День 2. Пользователь нажимает на объявление, предоставляемое рекламной технологией Б.

Рекламная технология Б вызывает registerSource() со своим URI. API отправляет запрос к URI, и клик регистрируется с помощью метаданных ответа сервера рекламной службы Б.

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

День 3. Пользователь просматривает рекламу, предоставленную рекламной технологией А.

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

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

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

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

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

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

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

  • Рекламная технология А устанавливает приоритет кликов выше просмотров и, следовательно, получает установку, связанную с кликом в первый день.
  • Рекламная технология Б получает установку на второй день.
  • MMP устанавливает приоритет кликов выше, чем просмотров, и устанавливает установку, связанную с кликом во второй день. Клик во второй день является самым приоритетным и самым последним рекламным событием.

Межсетевая атрибуция без редиректов

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

Высокий уровень потока

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

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

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

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

Триггерная регистрация

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

Кроме того, специалист по рекламе должен также указать свою каскадную логику атрибуции, используя новый вызов API конфигурации атрибуции. В этой конфигурации AD Tech может указать приоритет, исходное приоритет источника и фильтры для источников, в которые они не имели видимости (например, источники, которые не использовали перенаправление).

Атрибуция

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

  • Пользователь нажал на рекламу, обслуживаемые AD Techs A, B, C и D. Затем пользователь установил приложение рекламодателя, в котором используется Tech Partner Measurement AD (MMP).
  • AD Tech A перенаправляет свои источники MMP.
  • AD Techs B и C не перенаправляют, но делятся своими ключами агрегации.
  • AD Tech D не перенаправляет и не разделяет ключи агрегации.

MMP регистрирует источник от Ad Tech A и определяет конфигурацию атрибуции, которая включает AD Tech B и Ad Tech D.

Атрибуция для MMP теперь включает в себя:

  • Ad Tech A, так как MMP зарегистрировал источник из перенаправления этой рекламной технологии.
  • Ad Tech B, так как Ad Tech B общие ключи и MMP включали его в свою конфигурацию атрибуции.

Атрибуция для MMP не включает:

  • AD Tech C, поскольку MMP не включила его в свою конфигурацию атрибуции.
  • AD Tech D, поскольку они не перенаправляли и не разделяли ключи агрегации.

Отладка

Для поддержки отладки для атрибуции по перекрестной сети без перенаправлений, дополнительное поле, shared_debug_key , доступно для AD Techs для установки при регистрации источника. Если установлено на исходной регистрации источника, она также будет установлена ​​на соответствующем производном источнике в качестве debug_key во время регистрации триггеров для атрибуции поперечной сети без перенаправлений. Этот ключ отладки прикреплен как source_debug_key в отчетах о событии и совокупности.

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

  • Приложение к измерению приложения, где разрешено ADID
  • Приложение к веб -измерению, где ADID разрешено и соответствует как источника приложения, так и в веб -триггере
  • Интернет -измерение (в одном и том же приложении браузера), когда ar_debug `присутствует как на источнике, так и на триггере

Ключевое обнаружение для атрибуции поперечной сети без перенаправлений

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

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

  • Список всех возможных ключей большой:
    • Объявляющая рекламная сеть выполняет сложную инициативу по привлечению пользователей, которая включает в себя 20 кампаний, каждая из которых имеет 10 групп AD, и каждая группа AD с 5 креативщиками, которые обновляются каждую неделю в зависимости от производительности.
  • Список всех возможных ключей неизвестен:
    • Объявляющая рекламная сеть обслуживает рекламу во многих мобильных приложениях, где полный список идентификаторов приложений издателя не известен при запуске кампании.
    • Рекламодатель работает в нескольких порционных рекламных сетях, которые не перенаправляются на MMP при регистрации источника; Каждая сервировая рекламная сеть имеет различную ключевую структуру и значения, которые могут быть ранее разделены с MMP.

С введением ключевого открытия:

  • Служба агрегации больше не требует полного перечисления возможных ключей агрегации.
  • Вместо того, чтобы указать полный список возможных клавиш, MMP может создать пустые (или частично пустые) набор клавиш и установить порог, так что только (не предварительно декоративные) значения, превышающие порог выход.
  • MMP получает сводный отчет, который включает в себя шумные значения для ключей, которые имеют значения, превышающие пороговое значение SET. Отчет также может включать в себя ключи, которые не имеют связанных реальных вкладов пользователей и являются чисто чушцом.
  • MMP использует поле x_network_bit_mapping в регистрации триггеров, чтобы определить, какая технология AD соответствует какой ключ.
  • Затем MMP может связаться с соответствующей службой AD Tech, чтобы понять значения в клавише источника.

Таким образом, Key Discovery позволяет MMP получать ключи агрегации, не зная их заранее, и избегать обработки большого объема клавиш исходных классов за счет дополнительного шума.

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

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

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

Эти два типа отчетов дополняют друг друга и могут использоваться одновременно.

Отчеты на уровне событий

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

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

Отчет на уровне событий содержит данные, такие как следующие:

  • Пункт назначения: имя пакета приложений рекламодателя или Etld+1, где произошел триггер
  • Идентификатор источника атрибуции: тот же идентификатор источника атрибуции, который использовался для регистрации источника атрибуции
  • Тип триггера: 1 или 3 бита данных триггера с низкой точки зрения, в зависимости от типа источника атрибуции

Содержание конфиденциальности, применяемые ко всем отчетам

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

Ограничения на количество рекламных технологий

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

  • 100 Techs AD с источниками атрибуции на {исходное приложение, приложение назначения, 30 дней, устройство}.
  • 10 AD Techs с приписанными триггерами на {Source App, приложение для назначения, 30 дней, устройство}.
  • 20 Techs могут зарегистрировать единый источник или триггер (через Attribution-Reporting-Redirect )

Ограничения на количество уникальных направлений

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

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

Срок действия источников не учитывается в пределах ставки.

Один из сообщений о происхождении на исходное приложение в день

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

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

  1. Ad Tech Origity Origin 1 регистрирует источник в приложении B
  2. 12 часов спустя, Ad Tech Arating Origin 2 пытается зарегистрировать источник в приложении B

Второй источник, для API, будет отклонен API. Ad Tech Orying 2 Origin 2 не сможет успешно зарегистрировать источник на том же устройстве в приложении B до следующего дня.

Отсудания и пределы ставок

Чтобы ограничить количество утечки идентификации пользователя между парой {источника, назначения}, API подавляет сумму общей информации, отправленной в определенный период времени для пользователя.

Текущее предложение состоит в том, чтобы ограничить каждую технологию AD 100 приписанными триггерами на {исходное приложение, приложение для назначения, 30 дней, устройство}.

Количество уникальных направлений

API ограничивает количество направлений, которые AD Tech может попытаться измерить. Чем меньше ограничение, тем сложнее AD -технологии использует API, чтобы попытаться измерить деятельность просмотра пользователей, которая не связана с показанной рекламой.

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

Содержание конфиденциальности, применяемые к отчетам на уровне событий

Ограниченная верность данных триггера

API предоставляет 1 бит для просмотра триггеров и 3 бита для триггеров. Источники атрибуции продолжают поддерживать полные 64 бита метаданных.

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

Структура для дифференциального шума конфиденциальности

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

Шум применяется на том, правдиво ли сообщено событие источника атрибуции. Источник атрибуции зарегистрирован на устройстве с вероятностью $ 1-P $, что источник атрибуции зарегистрирован как нормальный, и с вероятностью $ p $, что устройство случайным образом выбирает среди всех возможных состояний выходных данных (включая вообще ничего не сообщать , или сообщать о нескольких поддельных отчетах).

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

\[ p = \frac{k}{k + e^ε - 1} \]

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

  • P = 0,24% для источников навигации
  • P = 0,00025% для источников событий

Ограничения на доступные триггеры (преобразования)

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

  • 1-2 Триггеры для источников атрибуции AD (2 триггера доступны только в случае атрибуции после установки)
  • 3 триггера для клика. Источники атрибуции AD

Конкретные временные окна для отправки отчетов (поведение по умолчанию)

Отчеты об уровне событий для источников атрибуции AD отправляются через 1 час после истечения источника. Эта дата истечения может быть настроена, но она не может быть менее 1 дня или более 30 дней. Если два триггера приписываются источнику атрибуции AD представления (через атрибуцию после установки ), отчеты об уровне событий могут быть отправлены за интервалы окна отчетности, указанные следующим образом.

Отчеты об уровне событий для источников атрибуции AD Click не могут быть настроены и отправляются до или когда исход истекает, в указанные моменты времени по сравнению с тем, когда источник был зарегистрирован. Время между источником атрибуции и истечением срока делится на несколько отчетных окон. Каждое окно отчетности имеет крайний срок (из исходного времени атрибуции). В конце каждого окна отчетности устройство собирает все триггеры, которые произошли после предыдущего окна отчетности, и отправляет запланированный отчет. API поддерживает следующие окна отчетности:

  • 2 дня: устройство собирает все триггеры, которые произошли не более чем через 2 дня после зарегистрированного источника атрибуции. Отчет отправляется через 2 дня и через 1 час после регистрации источника атрибуции.
  • 7 дней: устройство собирает все триггеры, которые произошли более 2 дней, но не более чем через 7 дней после зарегистрированного источника атрибуции. Отчет отправляется через 7 дней и через 1 час после регистрации источника атрибуции.
  • Пользовательский продолжительность времени, определяемый атрибутом «истечения» источника атрибуции. Отчет отправляется через 1 час после указанного времени истечения. Это значение не может быть менее 1 дня или более 30 дней.

Гибкая конфигурация на уровне событий

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

Эта дополнительная гибкость будет введена в API отчета о атрибуции в два этапа:

  • Фаза 1: Гибкая конфигурация уровня событий Lite
    • Эта версия предоставляет подмножество полных функций и может использоваться независимо от фазы 2.
  • Фаза 2: Полная версия гибкой конфигурации уровня событий

Фаза 1 (Lite гибкий уровень событий) может быть использован для:

  • Варьировать частоту отчетов, указав количество отчетных окон
  • Варьировать количество атрибутов на регистрацию источника
  • Уменьшить количество общего шума за счет уменьшения вышеуказанных параметров
  • Настройка отчетности Windows, а не использование по умолчанию

Фаза 2 (полный уровень гибкого события) может быть использован для выполнения всех возможностей на фазе 1 и:

  • Варьировать кардинальность данных триггера в отчете
  • Уменьшить количество общего шума за счет уменьшения кардинальности данных триггеров

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

В дополнение к динамическому установлению уровней шума на основе выбранной конфигурации AD Tech, у нас будут некоторые ограничения параметров, чтобы избежать больших затрат на вычисление и конфигурации с слишком большим количеством выходных состояний (где шум значительно увеличится). Вот пример набора ограничений. Обратная связь поощряется в [проектном предложении] [50]:

  • Максимум 20 общих отчетов, глобально и за trigger_data
  • Максимум 5 возможных отчетных окон на trigger_data
  • Максимум 32 данных за триггер (не применимо для фазы 1: Lite гибкий уровень события)

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

Совокупные отчеты

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

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

  • Отчеты о значениях триггера, такие как доход
  • Обработка больше типов триггеров

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

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

  1. Устройство отправляет зашифрованные агрегируемые отчеты в AD Tech. В производственной среде рекламные технологии не могут использовать эти отчеты напрямую.
  2. AD Tech отправляет партию агрегируемых отчетов в службу агрегации для агрегации.
  3. Служба агрегации читает множество агрегируемых отчетов, расшифровывает и агрегирует их.
  4. Окончательные заполнители отправляются обратно в AD Tech в сводном отчете .
Процесс, который использует API отчетности по атрибуции для подготовки и отправки обширных отчетов.

Агрегируемые отчеты содержат следующие данные, связанные с источниками атрибуции:

  • Пункт назначения: имя пакета приложения или веб -URL ETLD+1, где произошел триггер.
  • Дата: дата, когда произошло событие, представленное источником атрибуции.
  • Полезная нагрузка: значения запуска, собранные в виде зашифрованных паров ключей/значений, которые используются в службе доверенной агрегации для вычисления агрегаций.

Агрегационные услуги

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

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

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

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

Эта служба агрегации работает в надежной среде исполнения (TEE), размещенной в облаке. TEE предлагает следующие преимущества безопасности:

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

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

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

Служба управления ключами

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

Агрегируемый отчет бухгалтерский учет

Эта служба отслеживает, как часто сервис агрегации AD Tech обращается к конкретному триггеру, который может содержать несколько клавиш агрегации, и ограничивает доступ к соответствующему количеству расшифровков. Обратитесь к службе агрегации для получения подробной информации о предложении API API .

Агрегируемые отчеты API

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

Зарегистрируйте агрегатируемые исходные данные

Когда API делает запрос на URI источника атрибуции, AD Tech может зарегистрировать список клавиш агрегации с именем histogram_contributions , ответив новым полетом, называемым aggregation_keys в HTTP Header Attribution-Reporting-Register-Source , с Key как key_name и значение как key_piece :

  • (Ключ) Имя ключа: строка для имени ключа. Используется в качестве клавиши соединения для объединения с ключами на стороне триггера, чтобы сформировать конечную клавишу.
  • (Значение) Ключевая часть: значение битстроирования для ключа.

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

Последние ключи ограничены максимум 128 бит; Ключи длиннее этого усечены. Это означает, что шестигранные струны в JSON должны быть ограничены не более 32 цифр.

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

В следующем примере рекламная технология использует API для сбора следующего:

  • Совокупное количество конверсии на уровне кампании
  • Совокупные стоимость покупки на уровне GEO
// 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"
}

Зарегистрируйте агрегируемый триггер

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

Первое поле используется для регистрации списка совокупных ключей на стороне триггера. AD Tech должна ответить с помощью поля aggregatable_trigger_data в HTTP Header Attribution-Reporting-Register-Trigger , со следующими полями для каждого ключа агрегата в списке:

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

Второе поле используется для регистрации списка значений, которые должны способствовать каждому ключу. AD Tech должна ответить обратно с помощью поля aggregatable_values ​​в HTTP Header Attribution-Reporting-Register-Trigger . Второе поле используется для регистрации списка значений, которые должны вносить вклад в каждый ключ, который может быть целым числом в диапазоне $ [1, 2^{16}] $.

Каждый триггер может внести несколько вкладов в агрегируемые отчеты. Общая сумма взносов в любое данное событие исходного события связана параметром $ L1 $, который является максимальной суммой взносов (значений) во всех совокупных ключах для данного источника. $ L1 $ относится к чувствительности L1 или норме взносов на гистограмму в отношении исходного события. Превышение этих ограничений приводит к тому, что будущий вклад в молчащее падение. Первоначальное предложение - установить $ l1 $ $ 2^{16} $ (65536).

Шум в службе агрегации масштабируется пропорционально этому параметру. Учитывая это, рекомендуется надлежащим образом масштабировать значения, представленные для данного совокупного ключа, в зависимости от части бюджета $ L1 $, выделенного на него. Этот подход помогает гарантировать, что агрегатные отчеты сохраняют максимально возможную верность при применении шума. Этот механизм очень гибкий и может поддерживать многие стратегии агрегации.

В следующем примере бюджет конфиденциальности распределяется в равной степени между campaignCounts и geoValue , разделяя вклад $ L1 $ на каждый:

// 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
    }
}

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

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

Коэффициенты масштабирования могут быть инвертированы, чтобы получить правильные значения, применяемый модульный шум:

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

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

Цель этого API - иметь структуру, которая может поддерживать дифференциально частное совокупное измерение. Это может быть достигнуто путем добавления шума, пропорционального бюджету $ L1 $, таким как выбор шума со следующим распределением:

\[ Laplace(\frac{L1}{ε}) \]

Защищенная аудитория API и атрибуция отчетности API интеграция

Интеграция Cross-API в области защищенной аудитории и отчетности по атрибуции позволяет AdTechs оценивать свои показатели атрибуции по различной тактике ремаркетинга, чтобы понять, какие типы аудитории обеспечивают наибольшую рентабельность инвестиций.

Благодаря этой кросс-афийской интеграции Adtechs Can:

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

Когда пользователь видит или нажимает на объявление:

  • URL -адрес, используемый для сообщений об этих взаимодействиях с использованием защищенной аудитории, также будет использоваться для регистрации представления или щелчка в качестве подходящего источника с помощью API отчета о атрибуции.
  • AD Tech может выбрать передачу CustomAudience (или другую соответствующую контекстную информацию о рекламе, такой как размещение рекламы или продолжительность просмотра), используя этот URL -адрес, чтобы эти метаданные могли распространяться на сводные отчеты, когда AD Tech рассматривает агрегатную эффективность кампании.

Для получения дополнительной информации о том, как это включено в защищенную аудиторию, см. В соответствующем разделе «Объяснитель API защищенной аудитории ».

Приоритет регистрации, атрибуция и отчетность примеры

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

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

Рассмотрим случай, когда пользователь делает следующее:

  1. Пользователь видит объявление. AD Tech регистрирует источник атрибуции с API с приоритетом 0 (просмотр № 1).
  2. Пользователь видит объявление, зарегистрированное с приоритетом 0 (представление № 2).
  3. Пользователь нажимает объявление, зарегистрированное с приоритетом 1 (нажмите № 1).
  4. Пользователь преобразует (достигает целевой страницы) в приложении для рекламодателя. AD Tech регистрирует триггер с API с приоритетом 0 (преобразование № 1).
    • Поскольку триггеры зарегистрированы, API сначала выполняет атрибуцию перед созданием отчетов.
    • Доступно 3 источника атрибуции: Просмотр № 1, просмотр № 2 и нажмите #1. API приписывает этот триггер, чтобы щелкнуть #1, потому что он является наивысшим приоритетом и последним.
    • View #1 и View #2 отброшены и больше не имеют права на будущую атрибуцию.
  5. Пользователь добавляет элемент в свою корзину в приложение для рекламодателя, зарегистрированное с приоритетом 1 (конверсия № 2).
    • Нажмите #1 - единственный подходящий источник атрибуции. API приписывает этот триггер, чтобы щелкнуть #1.
  6. Пользователь добавляет элемент в свою корзину в приложение для рекламодателя, зарегистрированное с приоритетом 1 (конверсия № 3).
    • Нажмите #1 - единственный подходящий источник атрибуции. API приписывает этот триггер, чтобы щелкнуть #1.
  7. Пользователь добавляет элемент в свою корзину в приложение для рекламодателя, зарегистрированное с приоритетом 1 (преобразование № 4).
    • Нажмите #1 - единственный подходящий источник атрибуции. API приписывает этот триггер, чтобы щелкнуть #1.
  8. Пользователь совершает покупку в приложении для рекламодателей, зарегистрированной с приоритетом 2 (конверсия № 5).
    • Нажмите #1 - единственный подходящий источник атрибуции. API приписывает этот триггер, чтобы щелкнуть #1.

Отчеты на уровне событий имеют следующие характеристики:

  • По умолчанию первые 3 триггера, приписываемые щелчке, и первый триггер, приписываемый представлению, отправляются после применимых отчетных окон.
  • В окне отчетности, если есть триггеры, зарегистрированные с более высоким приоритетом, они имеют приоритет и заменяют самый последний триггер.
  • В предыдущем примере AD Tech получает 3 отчеты о событиях после двухдневного окна отчетности, для преобразования № 2, конверсии № 3 и преобразования № 5.
    • Все 5 триггеров приписываются на щелчок #1. По умолчанию API отправит отчеты для первых 3 триггеров: преобразование № 1, преобразование № 2 и преобразование № 3.
    • Однако приоритет конверсии № 4 ( 1 ) выше, чем приоритет конверсии № 1 ( 0 ). Отчет о событии конверсии № 4 заменяет отчет о событии конверсии #1, который будет отправлен.
    • Кроме того, приоритет конверсии № 5 ( 2 ) выше, чем любой другой триггер. Отчет о событии конверсии № 5 заменяет отчет о преобразовании № 4, который будет отправлен.

Агрегируемые отчеты имеют следующие характеристики:

  • Зашифрованные агрегируемые отчеты отправляются в AD Tech, как только они обрабатываются, через несколько часов после зарегистрированы триггеры.

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

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

  • По сравнению с отчетами на уровне событий, зашифрованные агрегируемые отчеты могут приписывать больше триггеров источнику.

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

Отчеты о переходной отладке

API отчетности по атрибуции-это новый и довольно сложный способ выполнения измерения атрибуции без идентификаторов перекрестного приложения. Таким образом, мы поддерживаем переходный механизм, чтобы узнать больше информации о отчетах о атрибуции, когда доступен идентификатор рекламы (пользователь не отказался от персонализации, используя рекламный идентификатор, а издатель или приложение для рекламодателя объявили о выдаче разрешения) . Это гарантирует, что API может быть полностью понят во время развертывания, помогает вымыть любые ошибки и легче сравнить производительность с альтернативами на основе рекламы на основе идентификатора. Существует два типа отчетов отладки: Attribution-Success и Verbose.

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

Отчеты отладки Attribution-Success

Регистрация источника и триггера принимает новое 64-разрядное поле debug_key (отформатированное как строка), которое населяет AD Tech. source_debug_key и trigger_debug_key передаются в отчетах как на уровне событий, так и в совокупных отчетах.

Если отчет создан как с клавишами отладки источника, так и с запусками, отчет о дубликате отладки отправляется с ограниченной задержкой в .well-known/attribution-reporting/debug/report-event-attribution конечную точку. Отчеты отладки идентичны обычным отчетам, включая оба поля отладки. Включение этих ключей в обоих позволяет связывать нормальные отчеты с отдельным потоком отчетов отладки.

  • Для отчетов на уровне событий:
    • Отчеты о дубликатах отладки отправляются с ограниченной задержкой и, следовательно, не подавляются ограничениями на доступные триггеры , что позволяет AD Tech понимать влияние этих пределов на отчеты на уровне событий.
    • Отчеты уровня событий, связанные с ложными событиями триггеров, не будут иметь trigger_debug_key s. Это позволяет AD Tech более близко понимать, как шум применяется в API.
  • Для обширных отчетов:
    • Мы будем поддерживать новое поле debug_cleartext_payload , которое содержит расшифрованную полезную нагрузку, только если устанавливаются оба source_debug_key и trigger_debug_key .

Отчеты отладки

Отчеты об отладке словесной отладки позволяют разработчикам отслеживать определенные сбои в источнике атрибуции или запуска регистрации. Эти отчеты отладки отправляются с ограниченной задержкой после атрибуции или запуска регистрации в A. well-known/attribution-reporting/debug/verbose конечная точка.

Каждый отчет о словесах содержит следующие поля:

  • Тип : что вызвало сгенерировать отчет. См. Полный список словесных типов отчетов .
    • В целом, есть отчеты об уровне источников и отчеты о том, что инициируют отчеты.
    • Отчеты об уровне источников требуют, чтобы идентификатор рекламы был доступен в приложении издателя, а отчеты о том, что идентификатор рекламы, идентификатор рекламы, идентификатор рекламы.
    • Отчеты о том, что запуск словеса (за исключением trigger-no-matching-source ) могут при желании включать в себя 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 via 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?