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

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

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

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

Регистрация источников и триггеров в операционной системе Android.

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

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

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

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

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

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

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

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

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

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

Пример

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

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

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

  1. В Android-приложении Daily News SDK для рекламных технологий регистрирует клик с помощью registerSource()

  2. API Attribution Reporting на Android отправляет запрос на URL-адрес рекламного сервера, указанный в registerSource()

  3. Сервер рекламных технологий отправляет заголовок Attribution-Reporting-Register-Source для завершения регистрации источника.

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

  1. Рекламная технология регистрирует триггер и проверяет доступность ОС в API отчетов по атрибуции.

  2. Веб-интерфейс ARA возвращает информацию о том, какая платформа поддерживается.

  3. Заголовок OS-Trigger указывает веб-API ARA вызвать функцию registerWebTrigger() веб-API ARA.

  4. Вызов функции registerWebTrigger() происходит автоматически, и разработчику не нужно вызывать registerWebTrigger() напрямую через операционную систему.

  5. OS ARA берет на себя управление и отправляет запрос на URL-адрес рекламного сервера, указанный в заголовке Attribution-Reporting-Register-OS-Trigger

  6. Технология рекламных объявлений завершит регистрацию триггера с помощью API операционной системы.

  7. OS ARA будет выполнять атрибуцию по той же логике, что и атрибуция приложений, и отправлять те же отчеты.

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

Ниже приведены более подробные инструкции по выполнению задачи:

  1. Рекламная технология приложения регистрирует источник в API отчетов по атрибуции Android со следующими настройками:

    • Для регистрации источника приложения, который, как ожидается, будет конвертировать пользователей на веб-сайте, заголовок ответа 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

    • Остальная часть процесса регистрации источника аналогична стандартной регистрации источника для взаимодействия между приложениями.

  2. Технология обработки рекламы на веб-сайте рекламодателя регистрирует триггер, запрашивая у 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 . Ключевым параметром является preferred-platform, а допустимые значения — os и web . Браузер будет использовать предпочтительную платформу, если она доступна, и переключится на веб-платформу, если операционная система недоступна.

    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 Attribution Reporting для Android вместо использования API Attribution Reporting в Chrome. Пользователь покупает свитер в приложении для покупок. Затем технология обработки рекламы в приложении рекламодателя регистрирует триггер конверсии в API Attribution Reporting для Android. API Attribution Reporting на уровне операционной системы может сопоставить веб-источник и триггер приложения и отправить соответствующие отчеты.

поток атрибуции веб-приложений к приложениям
поток атрибуции веб-приложений к приложениям

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

  1. Технологическая платформа для размещения рекламы регистрирует источник и проверяет доступность ОС в API для составления отчетов по атрибуции.

  2. Веб-интерфейс ARA возвращает информацию о том, какая платформа поддерживается.

  3. Заголовок OS-Source указывает веб-API ARA вызвать функцию registerWebSource() для API ARA ОС.

  4. Вызов функции registerWebSource() происходит автоматически, и разработчику не нужно вызывать registerWebSource() напрямую из операционной системы.

  5. OS ARA берет на себя управление и отправляет запрос на URL-адрес рекламного сервера, указанный в заголовке Attribution-Reporting-Register-OS-Source

  6. Рекламная технология завершит регистрацию источника через API операционной системы.

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

  1. SDK рекламных технологий в приложении магазина одежды для Android регистрирует триггер в OS ARA.

  2. API Attribution Reporting на Android отправляет запрос на URL-адрес рекламного сервера, указанный в функции registerTrigger()

  3. Сервер рекламных технологий отправляет заголовок Attribution-Reporting-Register-Trigger для завершения регистрации триггера.

  4. OS ARA будет выполнять атрибуцию по той же логике, что и атрибуция приложений, и отправлять те же отчеты.

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

Ниже приведены более подробные инструкции по выполнению задачи:

  1. Технология обработки рекламы на веб-сайте издателя регистрирует источник, указывая Chrome делегировать регистрацию API для отчетов об атрибуции Android:

    • В случае использования веб-приложения при регистрации источника параметр источника атрибуции должен быть указан напрямую, либо с помощью тега attributionsrc , либо с помощью регистрации JavaScript.
    • В следующем примере для указания параметра source используется тег attributionsrc : 
    <img src="https://adtech.example/conversionpixel"
attributionsrc="https://adtech.example/register-source?purchase=12">

  2. Заголовок запроса Attribution-Reporting-Support возвращается браузером Chrome в рекламную систему. Если API включен как в браузере Chrome, так и на устройстве Android, заголовок вернет os, web .

    Attribution-Reporting-Support: os, web

  3. Специалистам по рекламным технологиям следует указать 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 . Браузер будет использовать предпочтительную платформу, если она доступна, и переключится на веб-платформу, если платформа OS недоступна.
    Attribution-Reporting-Info: preferred-platform=os
    • Для завершения регистрации источника конечная точка рекламной технологии должна ответить на запрос к API отчетности по атрибуции Android заголовком Attribution-Reporting-Register-Source . В ответе также следует указать целевое приложение в поле назначения. 
    Attribution-Reporting-Register-Source: {
    "source_event_id":"123001",
    "destination":"android-app://com.example.advertiser",
    ...
}
    • Для поддержки перенаправлений при регистрации источников Chrome будет следовать этим перенаправлениям и вызывать API веб-контекста для каждого этапа перенаправления.
    • Остальная часть регистрации источника остается без изменений.

  4. Технология, используемая в приложении рекламодателя, регистрирует триггер в API отчетности по атрибуции Android:

    • Для триггеров, срабатывающих в приложениях, приложения регистрируют триггеры в API Android Attribution Reporting в обычном режиме.

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

  1. Настройте два пункта назначения

    • Некоторые рекламные кампании могут быть настроены на конверсию либо в приложении рекламодателя, либо на его веб-странице, в зависимости от различных факторов, таких как наличие установленного приложения у пользователя.
    • В таких случаях рекомендуется делегировать регистрацию источника операционной системе, если таковая имеется, чтобы источник мог быть корректно идентифицирован независимо от места срабатывания триггера. При регистрации источника в операционной системе в соответствующих параметрах можно указать как приложение, так и веб-адрес.
    • В поле «Назначение приложения» следует указать пункт 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"
    ...
}
    • В следующем разделе, посвященном составлению отчетов низкого качества, будет объяснено, как использование двух целевых адресов может повлиять на уровень шума в ваших отчетах.

  2. Используйте упрощенную отчетность для уменьшения шума в отчетах на уровне событий для источников с двумя получателями:

    • Если при регистрации источника были указаны как операционная система (приложение), так и веб-адрес, отчеты на уровне событий по умолчанию будут указывать, произошло ли событие в веб-адресе или в приложении. Однако для соблюдения ограничений конфиденциальности в эти отчеты будет добавляться дополнительная информация .
    • Специалисты по рекламным технологиям могут использовать поле coarse_event_report_destinations в заголовке Attribution-Reporting-Register-Source чтобы включить грубую отчетность и уменьшить количество лишней информации. Если источник с указанным полем coarse_event_report_destinations выигрывает в атрибуции, результирующий отчет включает как приложение, так и веб-адреса без указания фактического места срабатывания триггера, но с меньшим количеством лишней информации, чем отчеты, где указано только приложение или веб-адрес.
    • Сводные отчеты остаются без изменений.

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

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

  1. Зарегистрируйте источник приложения и триггер пользовательской вкладки:

  2. Зарегистрируйте источник данных для пользовательской вкладки и триггер приложения:

  3. Зарегистрируйте источник CCT и триггер CCT.

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

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

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

  2. В WebView доступна только атрибуция на уровне ОС. Заголовок Attribution-Reporting-Support вернет только информацию об ОС и только в том случае, если доступен API отчетности по атрибуции Android.

  3. При делегировании задач операционной системе 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, а не с самим приложением, необходимо присоединиться к списку разрешенных веб-приложений. Заполните эту форму , чтобы присоединиться к списку разрешенных приложений. Цель списка разрешенных приложений — снизить риски, связанные с обеспечением доверия к веб-контексту .

      Ценить Описание Пример использования
      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.
    1. Инициируйте и запускайте регистрацию из WebView

    2. Специалистам по рекламным технологиям следует отвечать на регистрацию источников, используя заголовок Attribution-Reporting-Register-OS-Source . В зависимости от заданного поведения WebView, это приведет либо к вызову registerSource() , либо registerWebSource() с указанием операционной системы и инициированию вторичного вызова API из Android Attribution Reporting API к URI рекламного технологического компонента.

      • Для завершения регистрации источника конечная точка рекламной технологии должна ответить на запрос к API отчетности по атрибуции Android заголовком ответа. 
       Attribution-Reporting-Register-OS-Source: {
  "source_event_id":"123001",
  "destination":"android-app://com.example.advertiser",
  ...
}

    3. Остальная часть регистрации источника остается без изменений.

    4. Специалисты по рекламным технологиям должны реагировать на регистрацию триггеров, используя заголовок Attribution-Reporting-Register-OS-Trigger . В зависимости от заданного поведения WebView, это приведет либо к вызову registerTrigger() , либо registerWebTrigger() с указанием операционной системы и инициированию вторичного вызова API из Rb к URI рекламного специалиста.

    5. Для завершения регистрации триггера конечная точка рекламной технологии должна ответить на запрос к API отчетности по атрибуции Android заголовком ответа. 

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

Отлаживать

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

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