Guía de implementación de apps y para la Web de la API de Attribution Reporting

La API de Attribution Reporting habilita la atribución web y de apps para las fuentes y activadores que ocurren en el mismo dispositivo. Los navegadores, como Chrome, Pueden delegar registros de fuentes y activadores a los informes de atribución. para Android en lugar de manejar esos registros en el navegador. Esto permite que Android haga coincidir las fuentes y los activadores en los sitios y las apps.

En esta guía, se explica cómo configurar la atribución web y entre apps.

Cuando configures la atribución web y entre apps, te recomendamos Familiarízate con las soluciones de depuración disponibles para asegurarte de que tu que la configuración funcione según lo previsto.

Registra fuentes y activadores con el SO Android

La atribución web y entre aplicaciones solo estará disponible si la La API de Reporting se habilita en el navegador y en el SO Android en la misma dispositivo. Se envía la disponibilidad de la API de Attribution Reporting de Android. a través del encabezado Attribution-Reporting-Support. Este encabezado mostrará el SO, la Web, o ambas, según lo que esté disponible en ese dispositivo. Si ambos son disponibles, las plataformas de tecnología publicitaria tendrán la opción de registrar con el navegador o el SO.

La tecnología publicitaria debe decidir si registrar la fuente web o el activador web con el navegador o el SO.

  • Para las campañas solo para la Web, las plataformas de tecnología publicitaria aún pueden registrar fuentes y activadores con la API de Attribution Reporting de Chrome o puedes delegar ambas al SO. Para campañas solo web en las que la fuente o el activador pueden ocurrir en una WebView, las plataformas de tecnología publicitaria deben delegar los registros de la fuente y del activador a el SO. Consulta la sección sobre WebViews para obtener más información.
  • Las tecnologías publicitarias deben evitar registrar fuentes y activadores con Chrome y las APIs de Android simultáneamente para evitar crear atribuciones duplicadas informes.
  • La atribución ocurre por separado para los navegadores y el SO. Si una fuente es pero el activador se registra con el SO, esos dos y viceversa.
  • Para las fuentes que pueden generar una aplicación o un activador web, se recomienda que la tecnología publicitaria delegue la fuente web y active registros para la API de Attribution Reporting de Android.
  • Para los activadores que podrían haberse impulsado por fuentes basadas en la app, la tecnología publicitaria elige delegar el registro del activador web a los Informes de atribución de Android en la API de Cloud.
  • En el caso de las campañas en las que la fuente y el activador ocurren en una aplicación, ambas deben estar registrados en la API de Attribution Reporting del SO.

Registra una fuente de app y un activador web

En algunas campañas, la fuente puede ocurrir en una aplicación mientras se activa el activador. en un sitio web, en el navegador para dispositivos móviles y en el mismo dispositivo.

Ejemplo

Un usuario está leyendo artículos en su app de noticias favorita. Ve un anuncio de bajo precio vuelos a París y hacer clic con entusiasmo para reservar. La tecnología publicitaria que publica el anuncio La app de noticias registra la fuente del clic con la API de Attribution Reporting de Android. Se dirige al usuario a la página web del anunciante en Chrome, donde puede hacer lo siguiente: generar una conversión. La tecnología publicitaria en el sitio del anunciante verifica si la API a nivel del SO está disponible, y así es. La tecnología publicitaria registra el activador de conversiones Indicarle a Chrome que delegue el registro al SO en lugar de directamente con la API de Attribution Reporting de Chrome. La atribución a nivel del SO La API de Reporting puede hacer coincidir la fuente de la app y el activador web, y enviar los informes relevantes.

Flujo de atribución de app a la Web
Flujo de atribución de app a la Web

Registro de la fuente de la app:

  1. El SDK de tecnología publicitaria de la app de Daily News para Android registra el clic usando registerSource()

  2. La API de Attribution Reporting en Android envía una solicitud al servidor de tecnología publicitaria. Se proporcionó una URL a registerSource()

  3. El servidor de tecnología publicitaria responde con la fuente Attribution-Reporting-Register-Source para completar el registro de la fuente

Registro de activadores web:

  1. La tecnología publicitaria registra un activador y verifica la disponibilidad del SO API de Attribution Reporting

  2. La ARA web devuelve información sobre la plataforma compatible

  3. El encabezado OS-Trigger le indica a la API de la ARA web que llame a la API de la ARA del SO. Función registerWebTrigger()

  4. La llamada a registerWebTrigger() ocurre de forma interna y el desarrollador no necesita llamar a registerWebTrigger() directamente con el SO

  5. La ARA del SO toma el control y envía una solicitud a la URL del servidor de tecnología publicitaria proporcionada por el encabezado Attribution-Reporting-Register-OS-Trigger

  6. La tecnología publicitaria completará el registro del activador con la API del SO.

  7. La ARA del SO realizará la atribución según la misma lógica aplicada la atribución de apps<>y enviar los mismos informes

Flujo de trabajo

En los siguientes pasos, se incluyen más detalles para completar la tarea:

  1. La tecnología publicitaria de la app registra una fuente con la atribución de Android. La API de Reporting con los siguientes ajustes:

    • Para registrar una fuente de app que se espera que genere conversiones en un sitio web, el El encabezado de respuesta Attribution-Reporting-Register-Source debe incluir un (eTLD+1) en lugar de un destino de app.
    Attribution-Reporting-Register-Source: {
    "web_destination": "https://advertiser.example",
    ...
}
      .
    • Es posible que algunos anunciantes utilicen varios proveedores de medición (por ejemplo, una herramienta de medición de terceros o una herramienta de estadísticas) mediante 302 cadenas de redireccionamiento. En algunos casos, la API de Attribution Reporting seguirá la ruta de redireccionamiento. se especifica en el encabezado Attribution-Reporting-Redirect en segundo plano y en al mismo tiempo que la ruta de redireccionamiento 302 se ejecuta en primer plano en una búsqueda las solicitudes de navegación. Estas solicitudes irán a la misma URL y podrían provocar en el proveedor de medición externo que cuenta dos veces los registros. Para evitar el recuento doble de registros, las tecnologías publicitarias pueden modificar el comportamiento de redireccionamiento para enviar el registro de la API de Attribution Reporting a una alternativa aún una URL determinista.

    • Para habilitar este comportamiento, las plataformas de tecnología publicitaria deben incluir un encabezado HTTP nuevo cuando para responder a una solicitud de registro:

      • El encabezado es Attribution-Reporting-Redirect-Config
      • El valor del encabezado debe ser redireccionar-302-a-well-known
      Attribution-Reporting-Redirect-Config: redirect-302-to-well-known

    • El resto del proceso de registro de la fuente es el mismo que un estándar registro de fuentes de app a app.

  2. La tecnología publicitaria en el sitio web del anunciante registra el activador solicitando Chrome delegue el registro a la API de Attribution Reporting de Android:

    • Una vez que un usuario completa una conversión en un sitio web, la tecnología publicitaria realizará una solicitud para registrar el activador con Chrome

      1. Se puede usar una solicitud de fetch() o píxel para registrar un gatillo

      2. Chrome muestra el encabezado de la solicitud Attribution-Reporting-Support a la tecnología publicitaria. Si la API está habilitada en el navegador Chrome y en la En un dispositivo Android, el encabezado mostrará os, web.

      Attribution-Reporting-Support: os, web

    • Luego, la tecnología publicitaria debe indicarle a Chrome que delegue al SO mediante el Attribution-Reporting-Register-OS-Trigger que hace lo siguiente:

      1. Le indica a Chrome que delegue el registro al SO

      2. Chrome delega el registro al SO llamando a la función de la API del SO registerWebTrigger()

        • La llamada a registerWebTrigger() ocurre de forma interna, la tecnología publicitaria no necesita llamar directamente a registerWebTrigger()

      3. La API de SO inicia una llamada a la API secundaria al URI de tecnología publicitaria que se pasa desde el navegador

      Attribution-Reporting-Register-OS-Trigger: "https://adtech.example/register-trigger",
"https://other-adtech.example/register-trigger"

    • En algunos casos, el encabezado Attribution-Reporting-Support no está disponible. no se pueden enviar. Cuando esto sucede, la tecnología publicitaria aún puede establecer plataforma para manejar el registro del activador incluyendo el Encabezado Attribution-Reporting-Info. La clave es la plataforma preferida y la los valores permitidos son os y web. El navegador usará la plataforma preferida. cuando estén disponibles y recurrirá a la plataforma web cuando el SO no disponible.

    Attribution-Reporting-Info: preferred-platform=os
    • Para completar el registro del activador, el extremo de la tecnología publicitaria debe responder a la solicitud a la API de Attribution Reporting de Android con el encabezado de respuesta.
    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"]}
    ],
    ...
}

Registra una fuente web y un activador de apps

En el caso de algunas campañas, es posible que aparezca una fuente en un sitio en un navegador para dispositivos móviles, mientras que se produce en una app en el mismo dispositivo.

Ejemplo

Un usuario navega en un sitio con el navegador Chrome en su teléfono Android. Ve un anuncio de un suéter de una de sus tiendas favoritas. Hacen clic y se los redirecciona a la app que ya descargaron. La tecnología publicitaria sitio web en el que se publicó el anuncio registra la fuente del clic indicándole a Chrome para delegar el registro a la API de Attribution Reporting de Android en lugar de con la API de Attribution Reporting en Chrome. El usuario compra el suéter en la aplicación de compras. Luego, la tecnología publicitaria en la app del anunciante registra activador de conversión con la API de Attribution Reporting de Android. El nivel de SO La API de Attribution Reporting puede hacer coincidir la fuente web con el activador de la aplicación y enviar los informes relevantes.

Flujo de atribución de la Web a la aplicación
Flujo de atribución de la Web a la aplicación

Registro de fuentes web:

  1. La tecnología publicitaria registra una fuente y comprueba la disponibilidad del SO API de Attribution Reporting

  2. La ARA web devuelve información sobre la plataforma compatible

  3. El encabezado OS-Source le indica a la API de la ARA web que llame a la API de la ARA del SO. Función registerWebSource()

  4. La llamada a registerWebSource() ocurre de forma interna y el desarrollador lo hace no es necesario llamar a registerWebSource() directamente con el SO

  5. La ARA del SO toma el control y envía una solicitud a la URL del servidor de tecnología publicitaria proporcionada por el encabezado Attribution-Reporting-Register-OS-Source

  6. La tecnología publicitaria completará el registro de la fuente con la API del SO.

Registro de activadores de la app:

  1. El SDK de tecnología publicitaria de la app para Android de la tienda de ropa registra el activador con la ARA del SO

  2. La API de Attribution Reporting en Android envía una solicitud al servidor de tecnología publicitaria. Se proporcionó una URL a registerTrigger()

  3. El servidor de tecnología publicitaria responde con el Attribution-Reporting-Register-Trigger. encabezado para completar el registro del activador

  4. La ARA del SO realizará la atribución según la misma lógica aplicada la atribución de apps<>y enviar los mismos informes

Flujo de trabajo

En los siguientes pasos, se incluyen más detalles para completar la tarea:

  1. La tecnología publicitaria del sitio web del publicador registra la fuente indicando Chrome delegue el registro a la API de Attribution Reporting de Android:

    • En un caso de uso de la Web a las apps, cuando se registra una fuente, la atribución El parámetro fuente debe especificarse directamente, ya sea mediante Etiqueta attributionsrc o mediante el registro de JavaScript
    • En el siguiente ejemplo, se usa la etiqueta attributionsrc para especificar la Parámetro de origen:
    <img src="https://adtech.example/conversionpixel"
attributionsrc="https://adtech.example/register-source?purchase=12">

  2. Chrome devuelve el encabezado de la solicitud Attribution-Reporting-Support al la tecnología publicitaria. Si la API está habilitada en el navegador Chrome y en el dispositivo Android, el encabezado mostrará os, web.

    Attribution-Reporting-Support: os, web

  3. La tecnología publicitaria debe indicarle a Chrome que delegue a la API a nivel del SO con el Attribution-Reporting-Register-OS-Source que hace lo siguiente:

    1. Le indica a Chrome que delegue el registro al SO
    2. Chrome delega el registro al SO llamando a la función de la API del SO registerWebSource()
    3. La llamada a registerWebSource() ocurre de forma interna, y la tecnología publicitaria sí lo hace no necesitas llamar directamente a registerWebSource()
    4. La API de SO inicia una llamada a la API secundaria al URI de tecnología publicitaria que se pasa desde el navegador
    Attribution-Reporting-Register-OS-Source: "https://adtech.example/register-source"
    • En algunos casos, el encabezado Attribution-Reporting-Support no está disponible. Cuando esto sucede, la plataforma de tecnología publicitaria aún puede establecer una plataforma preferida para administrar el registro de la fuente incluyendo el encabezado Attribution-Reporting-Info. La clave es la plataforma preferida y los valores permitidos son os y web. El navegador usará la plataforma preferida cuando esté disponible y recurrirá la plataforma web cuando el SO no está disponible.
    Attribution-Reporting-Info: preferred-platform=os
    • Para completar el registro de la fuente, el extremo de la tecnología publicitaria debe responder a la solicitud de la API de Attribution Reporting de Android con el encabezado de respuesta Attribution-Reporting-Register-Source La respuesta también debe especificar el destino de la app en el campo de destino.
    Attribution-Reporting-Register-Source: {
    "source_event_id":"123001",
    "destination":"android-app://com.example.advertiser",
    ...
}
    • Para admitir redireccionamientos para el registro de fuentes, Chrome seguirá las y llama a las APIs de Web Context para cada salto de redireccionamiento.
    • El resto del registro de fuente no cambia.

  4. La tecnología publicitaria de la app del anunciante registra un activador con el SDK de API de Attribution Reporting:

    • Para los activadores que ocurren en las apps, estas registran los activadores con el API de Attribution Reporting de Android como de costumbre.

Campañas que tienen destinos potenciales tanto para aplicaciones como para la Web

  1. Cómo configurar destinos dobles

    • Algunas campañas pueden estar configuradas para generar conversiones en la aplicación del anunciante en la página web del anunciante según diversos factores, como si el usuario tiene la app instalada.
    • En estos casos, se recomienda delegar el registro de la fuente al SO cuando esté disponible para que la fuente se pueda atribuir correctamente sin importar de dónde ocurre el activador. Cuando registres la fuente en el SO, el destino web y de la app se pueden especificar en los parámetros respectivos.
    • El destino de la app debe estar en el campo destination
    • El destino web debe estar en el campo web_destination
    • Los desarrolladores de Chrome deben tener en cuenta que el campo destination del SO La API de Attribution Reporting debe ser un paquete de aplicación y no una URL.
    Attribution-Reporting-Register-Source: {
    "source_event_id":"123001",
    "destination":"android-app://com.example.advertiser",
    "web_destination": "https://example.advertiser"
    ...
}
    • En la siguiente sección sobre informes generales, se explicará cómo el uso de destinos duales podría afectar el ruido en tus informes.

  2. Usa informes generales para reducir el ruido en los informes a nivel del evento para dobles fuentes de destino:

    • Si se especificaron un SO (app) y un destino web en el origen registro, los informes a nivel del evento especificarán si la activación ocurrió en un destino web o de app de forma predeterminada. Sin embargo, para mantener límites de privacidad, se agregará ruido adicional a estos informes.
    • Las tecnologías publicitarias pueden usar el campo coarse_event_report_destinations en el Encabezado Attribution-Reporting-Register-Source para activar los informes generales y reducir el ruido. Si una fuente con coarse_event_report_destinations campo especificado gana la atribución, el informe resultante incluye tanto la aplicación y destinos web sin distinguir dónde se encuentra el activador pero con menos ruido que los informes en los que la app o el destino web una regla de firewall.
    • Los informes globales no se modifican.

Apps que utilizan pestañas personalizadas de Chrome

Algunas apps pueden usar pestañas personalizadas para renderizar contenido web. Comportamiento de las pestañas personalizadas de manera similar a una página web normal cuando se miden en apps y sitios web móviles.

  1. Registra una fuente de app y un activador de pestaña personalizada:
  2. Registra una fuente de pestaña personalizada y un activador de la aplicación:
  3. Registra una fuente y un activador de CCT

Para apps que usan WebView

Algunas apps pueden usar WebView para mostrar contenido. Hay una gran variedad de casos de uso para WebView, como la renderización de anuncios, el hosting de contenido web o las apps personalizadas y funciones que se adaptan mejor a un formato web.

  1. Solo la atribución a nivel del SO está disponible en WebView. El El encabezado Attribution-Reporting-Support mostrará solo el SO y solo si La API de Attribution Reporting de Android está disponible.

  2. Cuando se delegue al SO, WebView puede usar registerSource o registerWebSource y registerTrigger o registerWebTrigger. ¿Cuáles son los métodos que usa WebView es establecida por la app que renderiza la WebView y se determina en por WebView.

    • ¿Cuál es la diferencia entre registerSource y registerWebSource? fuente se registra como el publicador. Con registerSource, se registra la app como publicador; Un ejemplo de cuándo usar registerSource sería App de publicador que muestra un anuncio renderizado mediante WebView. Con registerWebSource, el sitio web alojado en WebView se registra como el publicador; Un ejemplo de cuándo usar registerWebSource sería una app que aloja una WebView, y el sitio web que renderiza esta WebView mostrando anuncios. registerTrigger y registerWebTrigger se comportan de manera similar. El del gráfico del elemento núm. 3, en el que se detallan diferentes situaciones en las que un desarrollador de apps o SDK debes configurar la API para que use registerSource o registerWebSource y registerTrigger o registerWebTrigger.

  3. De forma predeterminada, WebView usará registerSource y registerWebTrigger cuando llamar a la API de Attribution Reporting de Android. Esto asocia las fuentes con la app y los activadores con el origen de nivel superior de la URL en WebView cuando se produce el activador.

    • Si una app requiere un comportamiento diferente, deberán usar un método nuevo. setAttributionRegistrationBehavior en androidx.webkit.WebViewSettingsCompat clase. Este método especificará si WebView debe llamar a registerWebSource(). o registerWebTrigger() en lugar de registerSource() o registerTrigger().
      • Deberás establecer este comportamiento para cada WebView que se inicie.
      • Si el SDK de tecnología publicitaria inicia WebView, deberá configurar este comportamiento predeterminado.
      • Para las apps que quieran usar registerWebSource() para asociar la fuente registros con el sitio web en WebView en lugar de la app, deben unirse a la lista de aplicaciones web permitidas. Completa este formulario para unirte a la lista de entidades permitidas. El de la lista de entidades permitidas es mitigar las consideraciones de privacidad establecer la confianza en el contexto de la Web.
    • Opciones para setAttributionRegistrationBehavior
    Valor Descripción Ejemplo de caso de uso
    APP_SOURCE_AND_WEB_TRIGGER (predeterminada) Permite que las apps registren fuentes de apps (fuentes asociadas con el nombre del paquete de la app) y activadores web (activadores asociados con eTLD+1) desde WebView. Apps que usan WebView para publicar anuncios en lugar de habilitar la navegación web
    WEB_SOURCE_AND_WEB_TRIGGER Permite que las apps registren fuentes web y activadores web desde WebView. Aplicaciones para navegadores basadas en WebView, en las que las impresiones de anuncios y las conversiones podrían ocurrir en sitios web en WebView
    APP_SOURCE_AND_APP_TRIGGER Permite que las apps registren fuentes y activadores de apps desde WebView. Aplicaciones basadas en WebView en las que las impresiones de anuncios y las conversiones siempre deben asociarse con la app, en lugar del eTLD+1 de WebView
    INHABILITADO Inhabilita el registro de la fuente y del activador desde WebView.

  4. Registros de fuente y activador de WebView

    • Las tecnologías publicitarias deben responder a los registros de fuentes con el Encabezado Attribution-Reporting-Register-OS-Source. Según el comportamiento establecido para WebView, se llamará a registerSource() o registerWebSource(). con el SO e iniciar una llamada a la API secundaria desde la atribución de Android API de Reporting para el URI de tecnología publicitaria

      • Para completar el registro de la fuente, el extremo de la tecnología publicitaria debe responder a la solicitud a la API de Attribution Reporting de Android con el encabezado de respuesta.
      Attribution-Reporting-Register-OS-Source: {
    "source_event_id":"123001",
    "destination":"android-app://com.example.advertiser",
    ...
}

    • El resto del registro de fuente no cambia.

  5. Las tecnologías publicitarias deben responder para activar registros con el Encabezado Attribution-Reporting-Register-OS-Trigger. Según el comportamiento establecido para WebView, se llamará a registerTrigger() o registerWebTrigger(). con el SO e iniciar una llamada a la API secundaria desde Rb al URI de tecnología publicitaria.

    • Para completar el registro del activador, el extremo de la tecnología publicitaria debe responder a la solicitud de la API de Attribution Reporting de Android con la respuesta encabezado.
    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"]}
    ],
    ...
}

Depurar

Cuando configuras una implementación de app a la Web, se recomienda configurar la depuración informes para verificar si las fuentes y los activadores se registran correctamente, y si no están registrados, para saber por qué.

Para conocer los pasos generales de depuración de Attribution Reporting, consulta la guía de soluciones de depuración.