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

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

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

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

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

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

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

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

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

Ознакомьтесь с API.

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

Настройте и протестируйте демонстрационное приложение.

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

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

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

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

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

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

Прототип атрибуции событий на уровне приложений

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

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

Имитационное тестирование

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

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

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

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

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

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

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

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

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

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

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

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

Используйте API отладки для генерации отладочных ключей (настоятельно рекомендуется).

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

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

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

Работа с MMP и другими организациями.

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

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

1. Межприложениевая и веб-атрибуция (доступна в конце 4 квартала)
   • Поддерживаются сценарии использования, когда пользователь видит рекламу в приложении, а затем совершает покупку в мобильном браузере или приложении, или наоборот.