Эта страница переведена с помощью Cloud Translation API.

Руководство по внедрению API отчетности по атрибуции и приложениям

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

Из этого руководства вы узнаете, как настроить кросс-приложенную и веб-атрибуцию.

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

Регистрация источников и триггеров в ОС Android

Кросс-приложение и веб-атрибуция будет доступна только в том случае, если API отчетов об атрибуции включен как в браузере, так и в ОС Android на одном устройстве. Информация о доступности Android Attribution Reporting API отправляется через заголовок Attribution-Reporting-Support. Этот заголовок вернет os, web или и то, и другое, в зависимости от того, что доступно на этом устройстве. Если оба варианта доступны, у рекламных специалистов будет возможность зарегистрировать веб-источники и веб-триггеры либо в браузере, либо в операционной системе.

Рекламному специалисту необходимо решить, регистрировать ли веб-источник или веб-триггер в браузере или ОС.

Для веб-кампаний специалисты по рекламе по-прежнему могут регистрировать как источники, так и триггеры с помощью Chrome Attribution Reporting API или делегировать и то, и другое ОС. Для веб-кампаний, в которых либо источник, либо триггер могут происходить в WebView, специалисты по рекламе должны делегировать ОС как регистрацию источника, так и триггера. Дополнительную информацию см. в разделе WebViews .
Специалистам по рекламе следует избегать одновременной регистрации источников и триггеров в API Chrome и Android, чтобы избежать создания дублирующихся отчетов об атрибуции.
Атрибуция происходит отдельно для браузеров и ОС. Если источник зарегистрирован в браузере, а триггер зарегистрирован в ОС, эти два значения не могут быть сопоставлены, и наоборот.
Для источников, которые могут привести к запуску приложения или веб-триггера, специалистам по рекламе настоятельно рекомендуется делегировать веб-источник и триггерную регистрацию API отчетов по атрибуции Android.
Для триггеров, которые могли быть вызваны источниками на основе приложений, рекламный техник может делегировать регистрацию веб-триггеров API отчетов по атрибуции Android.
Для кампаний, в которых и источник, и триггер происходят в приложении, оба должны быть зарегистрированы с помощью API отчетов об атрибуции ОС.

Зарегистрируйте источник приложения и веб-триггер

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

Пример

Пользователь читает статьи в своем любимом новостном приложении. Они видят рекламу дешевых авиабилетов в Париж и с нетерпением нажимают кнопку, чтобы забронировать билеты. Рекламная технология, обслуживающая рекламу в новостном приложении, регистрирует источник кликов с помощью Android Attribution Reporting API. Пользователь попадает на веб-страницу рекламодателя в Chrome, где он может совершить конверсию. Рекламная технология на сайте рекламодателя проверяет, доступен ли API уровня ОС, и он есть. Рекламная технология регистрирует триггер конверсии, инструктируя Chrome делегировать регистрацию ОС вместо того, чтобы регистрировать ее напрямую с помощью API отчетов по атрибуции Chrome. Затем API отчетов по атрибуции на уровне ОС сможет сопоставить источник приложения и веб-триггер и отправить соответствующие отчеты.

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

Регистрация источника приложения:

SDK рекламных технологий в приложении Daily News для Android регистрирует клик с помощью registerSource()
API отчетов по атрибуции на Android отправляет запрос на URL-адрес сервера рекламных технологий, указанный в registerSource()
Сервер рекламных технологий отвечает заголовком Attribution-Reporting-Register-Source, чтобы завершить регистрацию источника.

Регистрация веб-триггера:

Рекламная технология регистрирует триггер и проверяет доступность ОС в API отчетов по атрибуции.
Веб-ARA возвращает информацию о том, какая платформа поддерживается.
Заголовок OS-Trigger сообщает веб-API ARA о необходимости вызова функции registerWebTrigger() API OS ARA.
Вызов registerWebTrigger() происходит «под капотом», и разработчику не нужно напрямую вызывать registerWebTrigger() из ОС.
OS ARA берет на себя управление и отправляет запрос на URL-адрес сервера рекламных технологий, указанный в заголовке Attribution-Reporting-Register-OS-Trigger
Рекламная технология завершит регистрацию триггера с помощью API ОС.
OS ARA будет выполнять атрибуцию в соответствии с той же логикой, что и атрибуция приложения <> приложения, и отправлять те же отчеты.

Рабочий процесс

Следующие шаги включают дополнительную информацию о том, как выполнить задачу:

Рекламная технология приложения регистрирует источник с помощью Android Attribution Reporting API со следующими корректировками:
- Чтобы зарегистрировать источник приложения, который, как ожидается, будет конвертироваться на веб-сайте, заголовок ответа Attribution-Reporting-Register-Source должен включать веб-адрес (eTLD+1) вместо назначения приложения.
```
Attribution-Reporting-Register-Source: {
    "web_destination": "https://advertiser.example",
    ...
}
```
Примечание. Информацию о кампаниях, которые могут конвертироваться либо в Интернете, либо в приложении, см. в разделе о двойных назначениях.
- Некоторые рекламодатели могут использовать несколько поставщиков показателей (например, сторонний инструмент измерения или инструмент аналитики), используя цепочки перенаправления 302. В некоторых случаях API отчетов по атрибуции будет следовать пути перенаправления, указанному в заголовке Attribution-Reporting-Redirect, в фоновом режиме, и в то же время путь перенаправления 302 выполняется на переднем плане для существующих запросов навигации. Эти запросы будут отправляться на один и тот же URL-адрес и могут привести к двойному учету регистраций стороннего поставщика показателей. Чтобы предотвратить двойной учет регистраций, специалисты по рекламе могут изменить поведение перенаправления, чтобы отправить регистрацию API отчетов об атрибуции на альтернативный, но детерминированный URL-адрес.
- Чтобы включить такое поведение, рекламным специалистам необходимо включить новый HTTP-заголовок при ответе на запрос на регистрацию:
  - Заголовок: Attribution-Reporting-Redirect-Config
  - Значение заголовка должно быть redirect-302-to-well-known.
```
Attribution-Reporting-Redirect-Config: redirect-302-to-well-known
```
  Примечание. Все последующие перенаправления, следующие за этим заголовком, будут иметь .well-known , добавленный в начало пути URI перенаправления.
- Остальная часть процесса регистрации источника аналогична стандартной регистрации источника между приложениями.
Примечание. Если вы или приложение-публикатор используете веб-просмотр для показа нативной рекламы в приложении Android, обратитесь к разделу, посвященному веб-просмотру.
Рекламная технология на веб-сайте рекламодателя регистрирует триггер, прося Chrome делегировать регистрацию API отчетов по атрибуции Android:
- Как только пользователь совершит конверсию на веб-сайте, рекламная технология отправит запрос на регистрацию триггера в Chrome.
  1. Запрос пикселя или fetch() можно использовать для отправки запроса на регистрацию триггера.
  2. Заголовок запроса Attribution-Reporting-Support возвращается Chrome специалисту по рекламе. Если API включен как в браузере Chrome, так и на устройстве Android, заголовок вернет os, web
```
Attribution-Reporting-Support: os, web
```
- Затем специалист по рекламе должен указать Chrome делегировать полномочия ОС, используя заголовок Attribution-Reporting-Register-OS-Trigger который:
  1. Сообщает Chrome делегировать регистрацию ОС.
  2. Chrome делегирует регистрацию ОС, вызывая функцию API ОС registerWebTrigger()
    - Вызов метода registerWebTrigger() происходит «под капотом», рекламной технологии не требуется напрямую вызывать registerWebTrigger()
  3. API ОС инициирует вторичный вызов API к URI рекламной технологии, передаваемому из браузера.
```
Attribution-Reporting-Register-OS-Trigger: "https://adtech.example/register-trigger",
"https://other-adtech.example/register-trigger"
```
- В некоторых случаях заголовок Attribution-Reporting-Support недоступен и не может быть отправлен. В этом случае рекламный техник все равно может установить предпочтительную платформу для регистрации триггера, включив заголовок Attribution-Reporting-Info . Ключ — предпочтительная платформа, допустимые значения — os и web . Браузер будет использовать предпочтительную платформу, если она доступна, и вернется к веб-платформе, когда ОС недоступна.
Примечание. При указании предпочтительной платформы следует возвращать как заголовок Attribution-Reporting-Register-Trigger , содержащий информацию о веб-регистрации, так и заголовок Attribution-Reporting-Register-OS-Trigger содержащий информацию о регистрации ОС, чтобы обеспечить возможность правильной регистрации платформы. место. Необходимо предоставить как ОС, так и веб-регистрацию, чтобы в случае недоступности предпочтительной платформы присутствовала информация, необходимая для резервного метода.
```
Attribution-Reporting-Info: preferred-platform=os
```
- Чтобы завершить регистрацию триггера, конечная точка рекламного специалиста должна ответить на запрос API отчетов об атрибуции Android, используя заголовок ответа.
```
Attribution-Reporting-Register-Trigger: {
    "event_trigger_data": [{"trigger_data":"1"}],
    "aggregatable_trigger_data": [
        {"key_piece":"0x400","source_keys":["campaignCounts"]},
        {"key_piece":"0xA80","source_keys":["geoValue"]}
    ],
    ...
}
```
- Остальная часть регистрации триггера остается прежней.

Зарегистрируйте веб-источник и триггер приложения

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

Пример

Пользователь просматривает сайт в браузере Chrome на своем телефоне Android. Они видят рекламу свитера в одном из своих любимых магазинов. Они нажимают на рекламу и попадают в приложение, которое уже скачали. Рекламная технология на веб-сайте, где было показано объявление, регистрирует источник кликов, инструктируя Chrome делегировать регистрацию API отчетов по атрибуции Android вместо использования API отчетов по атрибуции в Chrome. Пользователь покупает свитер в приложении для покупок. Затем рекламная технология в приложении рекламодателя регистрирует триггер конверсии с помощью Android Attribution Reporting API. API отчетов по атрибуции на уровне ОС может сопоставлять веб-источник и триггер приложения и отправлять соответствующие отчеты.

Регистрация веб-источника:

Рекламный техник регистрирует источник и проверяет доступность ОС в API отчетов по атрибуции.
Веб-ARA возвращает информацию о том, какая платформа поддерживается.
Заголовок OS-Source сообщает веб-API ARA о необходимости вызова функции OS ARA API registerWebSource()
Вызов registerWebSource() происходит «под капотом», и разработчику не нужно напрямую вызывать registerWebSource() из ОС.
OS ARA берет на себя управление и отправляет запрос на URL-адрес сервера рекламных технологий, указанный в заголовке Attribution-Reporting-Register-OS-Source
Рекламный специалист завершит регистрацию источника с помощью API ОС.

Регистрация триггера приложения:

SDK рекламных технологий в Android-приложении Магазин одежды регистрирует триггер в ОС ARA.
API отчетов по атрибуции на Android отправляет запрос на URL-адрес сервера рекламных технологий, указанный для registerTrigger()
Сервер рекламных технологий отвечает заголовком Attribution-Reporting-Register-Trigger чтобы завершить регистрацию триггера.
OS ARA будет выполнять атрибуцию в соответствии с той же логикой, что и атрибуция приложения <> приложения, и отправлять те же отчеты.

Рабочий процесс

Следующие шаги включают дополнительную информацию о том, как выполнить задачу:

Рекламная технология на веб-сайте издателя регистрирует источник, инструктируя Chrome делегировать регистрацию Android Attribution Reporting API:
- В случае использования веб-приложения при регистрации источника параметр источника атрибуции должен быть указан напрямую либо с помощью тега attributionsrc , либо с помощью регистрации JavaScript.
- В следующем примере тег attributionsrc используется для указания исходного параметра:
```
<img src="https://adtech.example/conversionpixel"
attributionsrc="https://adtech.example/register-source?purchase=12">
```
Заголовок запроса Attribution-Reporting-Support возвращается Chrome специалисту по рекламе. Если API включен и в браузере Chrome, и на устройстве Android, заголовок вернет os, web .
```
Attribution-Reporting-Support: os, web
```
Примечание. Для успешного измерения данных в приложении и на сайте в ОС Android необходимо включить API отчетов по атрибуции.
Специалист по рекламе должен указать Chrome делегировать API уровня ОС, используя заголовок Attribution-Reporting-Register-OS-Source который:
1. Сообщает Chrome делегировать регистрацию ОС.
2. Chrome делегирует регистрацию ОС, вызывая функцию API ОС registerWebSource()
3. Вызов registerWebSource() происходит «под капотом», рекламной технологии не требуется напрямую вызывать registerWebSource()
4. API ОС инициирует вторичный вызов API к URI рекламной технологии, передаваемому из браузера.
```
Attribution-Reporting-Register-OS-Source: "https://adtech.example/register-source"
```
- В некоторых случаях заголовок Attribution-Reporting-Support недоступен. В этом случае рекламный техник все равно может установить предпочтительную платформу для регистрации источника, включив заголовок Attribution-Reporting-Info . Ключ — предпочтительная платформа, допустимые значения — os и web . Браузер будет использовать предпочтительную платформу, если она доступна, и вернется к веб-платформе, когда ОС недоступна.
Примечание. При указании предпочтительной платформы следует возвращать как заголовок Attribution-Reporting-Register-Source , содержащий информацию о веб-регистрации, так и заголовок Attribution-Reporting-Register-OS-Source содержащий информацию о регистрации ОС, чтобы обеспечить возможность правильной регистрации платформы. место. Необходимо предоставить как ОС, так и веб-регистрацию, чтобы в случае недоступности предпочтительной платформы присутствовала информация, необходимая для резервного метода.
```
Attribution-Reporting-Info: preferred-platform=os
```
- Чтобы завершить регистрацию источника, конечная точка рекламного специалиста должна ответить на запрос Android Attribution Reporting API заголовком ответа Attribution-Reporting-Register-Source . В ответе также следует указать пункт назначения приложения в поле назначения.
```
Attribution-Reporting-Register-Source: {
    "source_event_id":"123001",
    "destination":"android-app://com.example.advertiser",
    ...
}
```
- Чтобы поддерживать перенаправления для регистрации источников, Chrome будет следовать перенаправлениям и вызывать API веб-контекста для каждого перехода перенаправления.
- Остальная часть регистрации источника остается прежней.
Рекламная технология в приложении рекламодателя регистрирует триггер с помощью Android Attribution Reporting API:
- Триггеры, возникающие в приложениях, регистрируются с помощью Android Attribution Reporting API как обычно.

Кампании, у которых есть потенциальные направления как для приложений, так и для Интернета.

Настройте два пункта назначения
- Некоторые кампании могут быть настроены на конверсию либо в приложении рекламодателя, либо на веб-странице рекламодателя, в зависимости от различных факторов, например от того, установлено ли приложение у пользователя.
- В этих случаях рекомендуется делегировать регистрацию источника операционной системе, если она доступна, чтобы источник можно было правильно атрибутировать независимо от того, где происходит триггер. При регистрации источника в ОС в соответствующих параметрах можно указать как приложение, так и веб-адресат.
- Назначение приложения должно быть в поле destination .
- Веб-адресат должен быть указан в поле web_destination
- Разработчикам Chrome следует учитывать, что полем destination для API отчетов об атрибуции ОС должен быть пакет приложения, а не URL-адрес.
```
Attribution-Reporting-Register-Source: {
    "source_event_id":"123001",
    "destination":"android-app://com.example.advertiser",
    "web_destination": "https://example.advertiser"
    ...
}
```
- В следующем разделе, посвященном грубым отчетам, объясняется, как использование двойных адресатов может повлиять на шум в ваших отчетах.
Используйте грубые отчеты, чтобы уменьшить шум в отчетах на уровне событий для источников с двойным назначением:
- Если при регистрации источника были указаны и ОС (приложение), и веб-адресат, в отчетах на уровне событий будет указано, произошел ли триггер в веб-адресе или в приложении по умолчанию. Однако в целях соблюдения ограничений конфиденциальности в эти отчеты будет добавлен дополнительный шум .
- Специалисты по рекламе могут использовать coarse_event_report_destinations под заголовком Attribution-Reporting-Register-Source чтобы включить грубую отчетность и уменьшить шум. Если источник с указанным coarse_event_report_destinations выигрывает атрибуцию, результирующий отчет включает в себя как приложение, так и веб-адреса без различия того, где фактически произошел триггер, но с меньшим количеством шума, чем отчеты, в которых указано приложение или веб-адрес.
- Сводные отчеты остаются без изменений.

Для приложений, использующих пользовательские вкладки Chrome

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

Зарегистрируйте источник приложения и триггер пользовательской вкладки:
- Следуйте инструкциям, чтобы зарегистрировать источник приложения и веб-триггер .
Зарегистрируйте источник пользовательской вкладки и триггер приложения:
- Следуйте инструкциям, чтобы зарегистрировать веб-источник и триггер приложения .
Зарегистрируйте источник CCT и триггер CCT
- В Chrome это рассматривается так же, как и любая межсайтовая веб-атрибуция .

Для приложений, использующих WebView

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

В WebView доступна только атрибуция на уровне ОС. Заголовок Attribution-Reporting-Support вернет только os и только в том случае, если API отчетов по атрибуции Android доступен.
Примечание. Для атрибуции в Chrome и WebView необходимо делегировать регистрацию источника и триггера в Chrome операционной системе, поскольку для WebView поддерживается только атрибуция на основе ОС.
При делегировании ОС WebView может использовать registerSource или registerWebSource и registerTrigger или registerWebTrigger . Какие методы используются WebView, задается приложением, отображающим WebView, и определяется отдельно для каждого WebView.
- Разница между registerSource и registerWebSource заключается в том, какой источник регистрируется как издатель. При использовании registerSource приложение регистрируется как издатель; примером использования registerSource может служить приложение издателя, показывающее рекламу, отображаемую с помощью WebView. При использовании registerWebSource веб-сайт, размещенный в WebView, регистрируется как издатель; примером использования registerWebSource может служить приложение, на котором размещен WebView, а веб-сайт, отображаемый WebView, показывает рекламу. registerTrigger и registerWebTrigger ведут себя аналогично. На диаграмме в пункте №3 подробно описаны различные сценарии, когда разработчик приложения или SDK захочет настроить API для использования registerSource или registerWebSource и registerTrigger или registerWebTrigger .

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

Если приложению требуется другое поведение, ему необходимо будет использовать новый метод setAttributionRegistrationBehavior в классе androidx.webkit.WebViewSettingsCompat . Этот метод укажет, должен ли WebView вызывать registerWebSource() или registerWebTrigger() , а не registerSource() или registerTrigger() .
- Это поведение необходимо будет установить для каждого инициируемого WebView.
- Если SDK рекламных технологий инициирует WebView, SDK необходимо будет установить это поведение по умолчанию.
- Приложения, которые хотели бы использовать registerWebSource() для связи регистрации источника с веб-сайтом в WebView, а не с приложением, должны присоединиться к белому списку веб-приложений. Заполните эту форму , чтобы присоединиться к белому списку. Цель белого списка — смягчить соображения конфиденциальности, связанные с установлением доверия к веб-контексту .
Параметры setAttributionRegistrationBehavior

Ценить	Описание	Пример варианта использования
APP_SOURCE_AND_WEB_TRIGGER (по умолчанию)	Позволяет приложениям регистрировать источники приложений (источники, связанные с именем пакета приложения) и веб-триггеры (триггеры, связанные с eTLD+1) из WebView.	Приложения, которые используют WebView для показа рекламы, а не для просмотра веб-страниц
WEB_SOURCE_AND_WEB_TRIGGER	Позволяет приложениям регистрировать веб-источники и веб-триггеры из WebView.	Браузерные приложения на основе WebView, в которых показы рекламы и конверсии могут происходить на веб-сайтах в WebView.
APP_SOURCE_AND_APP_TRIGGER	Позволяет приложениям регистрировать источники приложений и триггеры приложений из WebView.	Приложения на основе WebView, в которых показы рекламы и конверсии всегда должны быть связаны с приложением, а не с eTLD+1 WebView.
НЕПОЛНОЦЕННЫЙ	Отключает регистрацию источника и триггера из WebView.

Источник и триггер регистрации из WebView
- Специалисты по рекламе должны отвечать на регистрации источников, используя заголовок Attribution-Reporting-Register-OS-Source . В зависимости от заданного поведения для WebView он либо вызовет registerSource() , либо registerWebSource() с ОС и инициирует вторичный вызов API от API отчетов об атрибуции Android к URI рекламной технологии.
  - Чтобы завершить регистрацию источника, конечная точка рекламной технологии должна ответить на запрос Android Attribution Reporting API заголовком ответа.
```
Attribution-Reporting-Register-OS-Source: {
    "source_event_id":"123001",
    "destination":"android-app://com.example.advertiser",
    ...
}
```
- Остальная часть регистрации источника остается прежней.
Специалисты по рекламе должны реагировать на триггерные регистрации, используя заголовок Attribution-Reporting-Register-OS-Trigger . В зависимости от заданного поведения для WebView он либо вызовет registerTrigger() , либо registerWebTrigger() с ОС и инициирует вторичный вызов API от Rb к URI рекламной технологии.
- Чтобы завершить регистрацию триггера, конечная точка рекламного специалиста должна ответить на запрос Android Attribution Reporting API заголовком ответа.
```
Attribution-Reporting-Register-OS-Trigger: {
    "event_trigger_data": [{"trigger_data":"1"}],
    "aggregatable_trigger_data": [
        {"key_piece":"0x400","source_keys":["campaignCounts"]},
        {"key_piece":"0xA80","source_keys":["geoValue"]}
    ],
    ...
}
```
- Остальная часть процесса регистрации триггера остается прежней.

Отлаживать

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

Общие инструкции по отладке отчетов об атрибуции см. в книге рецептов отладки .