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

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

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

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

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

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

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

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

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

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

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

Пример

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

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

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

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

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

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

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

Рекламная технология приложения регистрирует источник в API отчетов об атрибуции Android со следующими корректировками:
- Чтобы зарегистрировать источник приложения, который, как ожидается, будет конвертироваться на веб-сайте, заголовок ответа Attribution-Reporting-Register-Source должен включать веб-адрес назначения (eTLD+1) вместо адреса назначения приложения.
```
Attribution-Reporting-Register-Source: {
    "web_destination": "https://advertiser.example",
    ...
}
```
Примечание: для кампаний, которые могут конвертироваться как в веб-приложении, так и в приложении, см. раздел о двойных назначениях.
- Некоторые рекламодатели могут использовать несколько поставщиков измерений (например, сторонний инструмент измерения или аналитический инструмент) с использованием цепочек перенаправлений 302. В некоторых случаях API Attribution Reporting будет следовать пути перенаправления, указанному в заголовке Attribution-Reporting-Redirect в фоновом режиме, и в то же время путь перенаправления 302 будет выполняться на переднем плане для существующих навигационных запросов. Эти запросы будут отправляться на один и тот же URL-адрес и могут привести к двойному подсчету регистраций сторонним поставщиком измерений. Чтобы предотвратить двойной подсчет регистраций, специалисты по рекламе могут изменить поведение перенаправления, чтобы отправить регистрацию API Attribution Reporting на альтернативный, но детерминированный URL-адрес.
- Чтобы включить такое поведение, специалистам по рекламе необходимо включить новый HTTP-заголовок при ответе на запрос регистрации:
  - Заголовок — Attribution-Reporting-Redirect-Config
  - Значение заголовка должно быть redirect-302-to-well-known
```
Attribution-Reporting-Redirect-Config: redirect-302-to-well-known
```
  Примечание: все последующие перенаправления, следующие за этим заголовком, будут иметь .well-known добавленный к началу пути URI перенаправления.
- Остальная часть процесса регистрации источника такая же, как и при стандартной регистрации источника «приложение-приложение».
Примечание: Если вы или приложение-публикатор используете WebView для показа рекламы в приложении Android, см. раздел о WebView.
Рекламный технолог на сайте рекламодателя регистрирует триггер, запрашивая у Chrome делегирование регистрации API Android Attribution Reporting:
- Как только пользователь завершит конверсию на веб-сайте, рекламный техник сделает запрос на регистрацию триггера в Chrome.
  1. Для создания запроса на регистрацию триггера можно использовать запрос пикселя или fetch()
  2. Заголовок запроса Attribution-Reporting-Support возвращается Chrome в ad tech. Если 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 . Ключ — preferred-platform, а допустимые значения — os и web . Браузер будет использовать предпочтительную платформу, если она доступна, и вернется к веб-платформе, если ОС недоступна.
Примечание: заголовок Attribution-Reporting-Register-Trigger содержащий информацию о веб-регистрации, и заголовок Attribution-Reporting-Register-OS-Trigger содержащий информацию о регистрации ОС, должны быть возвращены при указании предпочтительной платформы для проверки возможности правильной регистрации платформы. Необходимо предоставить как регистрацию ОС, так и веб-регистрацию, чтобы в случае недоступности предпочтительной платформы информация, необходимая для резервного метода, присутствовала.
```
Attribution-Reporting-Info: preferred-platform=os
```
- Для завершения регистрации триггера конечная точка рекламного специалиста должна ответить на запрос API Android Attribution Reporting, используя заголовок ответа.
```
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. Пользователь покупает свитер в приложении для покупок. Затем рекламная технология в приложении рекламодателя регистрирует триггер конверсии с API отчетов об атрибуции Android. API отчетов об атрибуции на уровне ОС может сопоставлять веб-источник и триггер приложения и отправлять соответствующие отчеты.

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

Специалист по рекламе регистрирует источник и проверяет доступность ОС в API Attribution Reporting.
Веб-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 будет выполнять атрибуцию в соответствии с той же логикой, которая применяется к атрибуции app<>app, и отправлять те же отчеты.

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

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

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

Кампании, которые имеют потенциальные цели как для приложений, так и для веб-сайтов

Настройте двойные пункты назначения
- Некоторые кампании могут быть настроены на конверсию либо в приложении рекламодателя, либо на веб-странице рекламодателя в зависимости от различных факторов, например, от того, установлено ли у пользователя приложение.
- В этих случаях рекомендуется делегировать регистрацию источника ОС, где это возможно, чтобы источник можно было правильно атрибутировать независимо от того, где происходит триггер. При регистрации источника в ОС в соответствующих параметрах можно указать как приложение, так и веб-адрес.
- Место назначения приложения должно быть указано в поле destination
- Веб-адрес должен быть указан в поле web_destination
- Разработчикам Chrome следует обратить внимание, что полем destination для API OS Attribution Reporting должен быть пакет приложения, а не 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, например, рендеринг рекламы, размещение веб-контента или пользовательские функции приложения, лучше подходящие для веб-формата.

Чтобы разрешить WebViews использовать API Attribution Reporting, необходимо настроить встраиваемое приложение с правильными разрешениями .
В WebView доступна только атрибуция на уровне ОС. Заголовок Attribution-Reporting-Support вернет только os и только если доступен API Android Attribution Reporting.
Примечание: для выполнения атрибуции в 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 Attribution Reporting. Это связывает источники с приложением и триггеры с источником верхнего уровня URL в WebView при возникновении триггера.

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

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

Источник и инициирование регистрации из WebView
Технические специалисты по рекламе должны отвечать на регистрации источников с помощью заголовка Attribution-Reporting-Register-OS-Source . В зависимости от заданного поведения для WebView это вызовет registerSource() или registerWebSource() с ОС и инициирует вторичный вызов API из Android Attribution Reporting API к URI технических специалистов.
- Для завершения регистрации источника конечная точка рекламного специалиста должна ответить на запрос API Android Attribution Reporting заголовком ответа.
```
 Attribution-Reporting-Register-OS-Source: {
  "source_event_id":"123001",
  "destination":"android-app://com.example.advertiser",
  ...
}
```
Остальная часть регистрации источника остается прежней.
Ad techs должны реагировать на регистрации триггеров с помощью заголовка Attribution-Reporting-Register-OS-Trigger . В зависимости от заданного поведения для WebView, это вызовет registerTrigger() или registerWebTrigger() с ОС и инициирует вторичный вызов API из Rb к URI ad tech.
Для завершения регистрации триггера конечная точка рекламного специалиста должна ответить на запрос API Android Attribution Reporting заголовком ответа.

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"]}
    ],
    ...
}

Остальная часть процесса регистрации триггера остается прежней.

Отлаживать

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

Общие шаги по отладке Attribution Reporting см. в книге «Рецепты отладки» .