API отчетов об атрибуции: руководство по интеграции

для разработчиков

При чтении документации Privacy Sandbox для Android используйте кнопку Developer Preview или Beta , чтобы выбрать версию программы, с которой вы работаете, поскольку инструкции могут отличаться.

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

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

Чтобы помочь вам с планированием интеграции, это руководство предоставляет комплексный обзор, который может включать функции, которые еще не реализованы на текущем этапе Privacy Sandbox в Android Developer Preview. В этих случаях предоставляется руководство по временной шкале.

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

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

Рабочий процесс интеграции атрибуции.
Рисунок 1. Рабочий процесс интеграции атрибуции.

Предварительные условия и настройка

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

Ознакомиться с API

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

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

  1. Когда вы будете готовы начать интеграцию, установите последнюю версию Developer Preview в Android Studio .
  2. Настройте конечные точки сервера-заглушки для регистрации событий и доставки отчетов. Мы предоставили заглушки , которые вы можете использовать в тандеме с инструментами, доступными в сети.
  3. Загрузите и запустите код в нашем примере приложения, чтобы ознакомиться с регистрацией источников и триггеров.
    1. Установите временное окно для отправки отчетов. API поддерживает окна в 2 дня, 7 дней или пользовательский период от 2 до 30 дней.
    2. После того, как вы зарегистрировали источники и триггеры, запустив и используя пример приложения, и что установленный период времени прошел, проверьте, что вы получили отчет на уровне событий и зашифрованный агрегируемый отчет. Если вам нужно отладить отчеты, вы можете сгенерировать их быстрее, принудительно запустив задания по созданию отчетов .
    3. Просмотрите результаты для атрибуции приложения к приложению. Подтвердите, что данные в этих результатах соответствуют ожидаемым для случаев последнего касания и после установки.

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

Предварительная интеграция

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

Взаимодействие с партнерами

Партнеры по рекламным технологиям (MMP/SSP/DSP) часто создают интегрированные решения атрибуции. Шаги в этом разделе помогут вам подготовиться к успешному взаимодействию с вашими партнерами по рекламным технологиям.

  1. Запланируйте обсуждение с вашими главными партнерами по измерению, чтобы обсудить тестирование и внедрение API Attribution Reporting. Партнерами по измерению могут быть рекламные технологические сети, SSP, DSP, рекламодатели или любые другие партнеры, с которыми вы работаете или хотели бы работать.
  2. Сотрудничайте с вашими партнерами по измерениям, чтобы определить сроки интеграции — от первоначального тестирования до внедрения.
  3. Уточните у своих партнеров по измерениям, какие области каждый из вас будет охватывать при проектировании атрибуции.
  4. Установите каналы связи между партнерами по измерениям для синхронизации сроков и сквозного тестирования.
  5. Проектируйте потоки данных высокого уровня между партнерами по измерению. Ключевые соображения включают следующее:
    • Как партнеры по измерениям будут регистрировать источники атрибуции с помощью API Attribution Reporting?
    • Как рекламные технологические сети будут регистрировать триггеры с помощью API Attribution Reporting?
    • Каким образом каждая рекламная технология будет проверять запросы API и возвращать ответы для завершения регистрации источника и триггера?
    • Существуют ли какие-либо отчеты, которые необходимо предоставить партнерам за пределами API Attribution Reporting?
    • Нужны ли какие-либо другие точки интеграции или согласования между партнерами? Например, нужно ли вам и вашим партнерам работать над дедупликацией конверсий или согласовывать ключи агрегации?
  6. Если применима атрибуция app-to-web, запланируйте обсуждение с партнерами по измерению в сети, чтобы обсудить проектирование, тестирование и внедрение API отчетов об атрибуции. Обратитесь к вопросам на предыдущем шаге, когда начнете общение с веб-партнерами.

Атрибуция на уровне событий от приложения к приложению-прототипу

Этот раздел поможет вам настроить базовую атрибуцию app-to-app с отчетами на уровне событий в вашем приложении или SDK. Завершение этого раздела необходимо, прежде чем вы сможете начать прототипирование атрибуции сервера агрегации .

  1. Настройте сервер сбора записей событий. Вы можете сделать это, используя предоставленную спецификацию для создания фиктивного сервера или настроить свой собственный сервер с помощью кода примера сервера .
  2. Добавьте вызовы событий источника регистрации в свой SDK или приложение при показе рекламы.
    • Важнейшие соображения включают следующее:
      • Убедитесь, что идентификаторы исходных событий доступны и правильно передаются в вызовы API регистрации источника.
      • Убедитесь, что вы также можете передать `InputEvent` для регистрации источников щелчков.
      • Определите, как вы будете настраивать приоритет источника для различных типов событий. Например, назначьте высокий приоритет событиям, которые считаются высокоценными, таким как клики по просмотрам.
      • Значение по умолчанию для срока годности — ОК для тестирования. В качестве альтернативы можно настроить различные окна срока годности .
      • Фильтры и окна атрибуции можно оставить по умолчанию для тестирования.
    • Дополнительные соображения включают следующее:
      • Разработайте ключи агрегации, если вы к ним готовы.
      • Продумайте стратегию перенаправления, когда будете определять, как вы хотите работать с другими партнерами по измерению.
  3. Добавьте события триггера регистрации в свой SDK или приложение для регистрации событий конверсии.
    • Важнейшие соображения включают следующее:
    • Дополнительные соображения включают следующее:
      • Пропустите создание ключей дедупликации, пока не проведете тесты точности.
      • Пропустите создание ключей и значений агрегации, пока не будет готова поддержка имитационного тестирования .
      • Пропустите перенаправления, пока не определитесь, как вы хотите работать с другими партнерами по измерениям.
      • Приоритет триггера не имеет значения для тестирования.
      • Фильтры, скорее всего, можно проигнорировать при первоначальном тестировании.
  4. Проверьте, генерируются ли исходные события для рекламы и приводят ли триггеры к созданию отчетов о событиях.

Тестирование методом моделирования

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

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

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

  1. Настройте библиотеку моделирования измерений на локальном компьютере.
  2. Ознакомьтесь со спецификацией о том, как должны быть отформатированы данные о конверсиях, чтобы они были совместимы с имитированным генератором отчетов.
  3. Разрабатывайте ключи агрегации на основе бизнес-требований.
    • Важнейшие соображения включают следующее:
      • Подумайте о важнейших параметрах, которые необходимо учитывать вашим клиентам или партнерам, и сосредоточьте свою оценку на них.
      • Определите минимальное количество агрегированных измерений и мощностей, необходимых для ваших требований.
      • Убедитесь, что длина ключей на стороне источника и триггера не превышает 128 бит.
      • Если ваши решения предполагают вклад в несколько значений на одно событие-триггер, обязательно масштабируйте значения по максимальному бюджету вклада, L1. Это поможет минимизировать влияние шума.
      • Ниже приведен пример , в котором подробно описывается настройка ключа для сбора совокупных показателей конверсий на уровне кампании и ключа для сбора совокупных значений покупок на географическом уровне.
  4. Запустите генератор отчетов для создания событийных и агрегированных отчетов.
  5. Пропустите агрегируемые отчеты через имитированные серверы агрегации, чтобы получить сводные отчеты.
  6. Проведите полезные эксперименты:
    • Сравните итоговые данные по конверсиям из отчетов на уровне событий и сводных отчетов с историческими данными по конверсиям, чтобы определить точность отчетов по конверсиям. Для достижения наилучших результатов запустите тесты и сравнения отчетов на широкой, репрезентативной части базы рекламодателей.
    • Переобучите свои модели на основе данных отчета на уровне событий и потенциально сводных данных отчета. Сравните точность с моделями, построенными на исторических данных обучения.
    • Попробуйте разные стратегии пакетирования и посмотрите, как они повлияют на ваши результаты.
      • Важнейшие соображения включают следующее:
      • Своевременность сводных отчетов для корректировки заявок.
      • Средняя частота атрибутивных событий на устройстве. Например, возвращение пользователей, прекративших использование, на основе исторических данных о покупках.
      • Уровень шума. Больше партий означает меньшую агрегацию, а меньшая агрегация означает больше шума.

Атрибуция прототипа сервера агрегации: Настройка

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

  1. Настройте свой сервер агрегации:
    • Настройте свою учетную запись AWS.
    • Зарегистрируйтесь в сервисе агрегации у своего координатора.
    • Настройте свой сервер агрегации на AWS с помощью предоставленных двоичных файлов.
  2. Разработайте ключи агрегации на основе бизнес-требований. Если вы уже выполнили эту задачу в разделе событий уровня приложения-приложения , вы можете пропустить этот шаг.
  3. Настройте сервер сбора для агрегируемых отчетов. Если вы уже создали его в разделе событий уровня приложения-приложения , вы можете использовать его повторно.

Атрибуция прототипа сервера агрегации: Интеграция

Чтобы продолжить работу после этого этапа, вам необходимо завершить раздел «Атрибуция сервера агрегации прототипа: настройка» или раздел «Атрибуция на уровне событий между приложениями прототипа» **.

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

Итеративный дизайн с дополнительными функциями

Ниже приведены дополнительные функции, которые вы можете включить в свое измерительное решение.

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

Настройте поведение атрибуции

  1. Атрибуция для триггеров после установки
    • Эту функцию можно использовать в случае, когда триггеры после установки необходимо приписать тому же источнику атрибуции, который привел к установке, даже если существуют другие подходящие источники атрибуции, которые произошли позднее.
    • Например, может быть случай, когда пользователь нажимает на рекламу, которая приводит к установке. После установки пользователь нажимает на другую рекламу и совершает покупку. В этом случае рекламная технологическая компания может захотеть, чтобы покупка была отнесена к первому клику, а не к клику повторного вовлечения.
  2. Используйте фильтры для точной настройки данных в отчетах на уровне событий.
    • Фильтры конверсий можно настроить так, чтобы они игнорировали выбранные триггеры и исключали их из отчетов о событиях. Поскольку существуют ограничения на количество триггеров на источник атрибуции , фильтры позволяют вам включать только те триггеры, которые предоставляют наиболее полезную информацию в ваши отчеты о событиях.
    • Фильтры также можно использовать для выборочной фильтрации некоторых триггеров, фактически игнорируя их. Например, если у вас есть кампания, нацеленная на установки приложений, вы можете захотеть отфильтровать триггеры после установки, чтобы они не приписывались источникам из этой кампании.
    • Фильтры также могут использоваться для настройки данных триггера на основе исходных данных. Например, источник может указать "product" : ["1234"] , где product — это ключ фильтра, а 1234 — это значение. Любой триггер с ключом фильтра "product", который имеет значение, отличное от "1234", игнорируется.
  3. Настраиваемый источник и приоритет триггера
    • В случае, если с триггером можно связать несколько источников атрибуции или источнику можно приписать несколько триггеров, можно использовать знаковое 64-битное целое число, чтобы приоритизировать определенные источники или атрибуции триггеров по сравнению с другими.

Работа с ММП и другими

  1. Перенаправления к третьим лицам для получения исходных и триггерных событий
    • Вы можете задать URL-адреса перенаправления, чтобы разрешить нескольким платформам рекламных технологий регистрировать запрос. Это можно использовать для включения межсетевой дедупликации в атрибуции.
  2. Ключи дедупликации
    • Когда рекламодатель использует несколько платформ ad tech для регистрации одного и того же события-триггера, ключ дедупликации может использоваться для устранения неоднозначности этих повторяющихся отчетов. Если ключ дедупликации не предоставлен, дублирующиеся триггеры могут быть возвращены каждой платформе ad tech как уникальные.

Работа с кроссплатформенными измерениями

  1. Атрибуция между приложениями и веб-сайтами (доступно в конце четвертого квартала)
    • Поддерживает сценарии использования, когда пользователь видит рекламу в приложении, а затем совершает конверсию в мобильном устройстве или браузере приложения, или наоборот.
{% дословно %} {% endverbatim %} {% дословно %} {% endverbatim %}