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 entre apps y la Web para las fuentes y los activadores que ocurren en el mismo dispositivo. Los navegadores, como Chrome, pueden delegar los registros de fuentes y activadores a la API de Attribution Reporting para Android en lugar de controlar esos registros en el navegador. Esto permite que Android coincida con las fuentes y los activadores en los sitios y las apps.

En esta guía, aprenderás a configurar la atribución web y entre apps.

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

Registra fuentes y activadores con el SO Android

La atribución entre apps y la Web solo estará disponible si la API de Attribution Reporting está habilitada en el navegador y en el SO Android en el mismo dispositivo. La disponibilidad de la API de Attribution Reporting de Android se envía a través del encabezado Attribution-Reporting-Support. Este encabezado mostrará el SO, la Web o ambos, según lo que esté disponible en ese dispositivo. Si ambos están disponibles, las tecnologías publicitarias tendrán la opción de registrar fuentes y activadores web 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.

  • En el caso de las campañas solo web, las tecnologías publicitarias aún pueden registrar fuentes y activadores con la API de Attribution Reporting de Chrome o elegir delegar ambos al SO. En el caso de las campañas solo web en las que la fuente o el activador pueden ocurrir en un WebView, las tecnologías publicitarias deben delegar los registros de la fuente y del activador al SO. Consulta la sección sobre WebViews para obtener más información.

  • Las tecnologías publicitarias deben evitar registrar fuentes y activadores con las APIs de Chrome y Android de forma simultánea para evitar crear informes de atribución duplicados.

  • La atribución se realiza por separado para los navegadores y el SO. Si una fuente está registrada con el navegador, pero el activador está registrado con el SO, no se pueden hacer coincidir, y viceversa.

  • En el caso de las fuentes que pueden generar un activador web o de app, se recomienda que la tecnología publicitaria delegue los registros de la fuente web y del activador a la API de Attribution Reporting de Android.

  • En el caso de los activadores que pueden haberse generado a partir de fuentes basadas en aplicaciones, la tecnología publicitaria puede optar por delegar el registro de activadores web a la API de Attribution Reporting de Android.

  • En el caso de las campañas en las que la fuente y el activador ocurren en una app, ambos deberán registrarse con la API de Attribution Reporting del SO.

Registra una fuente de aplicación y un activador web

En algunas campañas, la fuente puede ocurrir en una app, mientras que el activador se produce en un sitio web en el navegador para dispositivos móviles del mismo dispositivo.

Ejemplo

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

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

Registro de la fuente de la app:

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

  2. La API de Attribution Reporting en Android envía una solicitud a la URL del servidor de tecnología publicitaria proporcionada a registerSource().

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

Registro de activadores web:

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

  2. La ARA web muestra información sobre qué plataforma es compatible.

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

  4. La llamada a registerWebTrigger() se realiza en segundo plano, y el desarrollador no necesita llamar a registerWebTrigger() directamente con el SO.

  5. El ARA del SO se hace cargo y envía una solicitud a la URL del servidor de tecnología publicitaria que proporciona el encabezado Attribution-Reporting-Register-OS-Trigger.

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

  7. El ARA del SO realizará la atribución según la misma lógica que se aplica a la atribución de app<>app 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 API de Attribution Reporting de Android con los siguientes ajustes:

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

    • Para habilitar este comportamiento, las tecnologías publicitarias deben incluir un encabezado HTTP nuevo cuando respondan a una solicitud de registro:

      • El encabezado es Attribution-Reporting-Redirect-Config.
      • El valor del encabezado debe ser redirect-302-to-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 registro de fuente estándar de app a app.

  2. La tecnología publicitaria en el sitio web del anunciante registra el activador pidiéndole a Chrome que 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 enviará una solicitud para registrar el activador con Chrome.

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

      2. Chrome muestra el encabezado de solicitud Attribution-Reporting-Support a 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

    • Luego, la tecnología publicitaria debe indicarle a Chrome que delegue al SO con el encabezado 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() se realiza de forma interna, y la tecnología publicitaria no necesita llamar a registerWebTrigger() directamente.

      3. La API del 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 y no se puede enviar. Cuando esto sucede, la tecnología publicitaria aún puede configurar una plataforma preferida para controlar el registro del activador si incluye el encabezado Attribution-Reporting-Info. La clave es preferred-platform y los valores permitidos son os y web. El navegador usará la plataforma preferida cuando esté disponible y recurrirá a la plataforma web cuando el SO no esté 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 de 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 aplicación

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

Ejemplo

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

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

Registro de fuentes web:

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

  2. La ARA web muestra información sobre qué plataforma es compatible.

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

  4. La llamada a registerWebSource() se realiza en segundo plano, y el desarrollador no necesita llamar a registerWebSource() directamente con el SO.

  5. El ARA del SO se hace cargo y envía una solicitud a la URL del servidor de tecnología publicitaria que proporciona el encabezado Attribution-Reporting-Register-OS-Source.

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

Registro del activador de apps:

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

  2. La API de Attribution Reporting en Android envía una solicitud a la URL del servidor de tecnología publicitaria proporcionada a registerTrigger().

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

  4. El ARA del SO realizará la atribución según la misma lógica que se aplica a la atribución de app<>app 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 en el sitio web del publicador registra la fuente instruyendo a Chrome para que delegue el registro a la API de Attribution Reporting de Android:

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

  2. Chrome devuelve el encabezado de solicitud Attribution-Reporting-Support a 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 encabezado 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() se realiza de forma interna, y la tecnología publicitaria no necesita llamar a registerWebSource() directamente.
    4. La API del 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 tecnología publicitaria aún puede establecer una plataforma preferida para controlar el registro de la fuente si incluye el encabezado Attribution-Reporting-Info. La clave es preferred-platform y los valores permitidos son os y web. El navegador usará la plataforma preferida cuando esté disponible y recurrirá a 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 un destino de app en el campo de destino.
    Attribution-Reporting-Register-Source: {
    "source_event_id":"123001",
    "destination":"android-app://com.example.advertiser",
    ...
}
    • Para admitir redireccionamientos para registros de fuentes, Chrome seguirá los redireccionamientos y llamará a las APIs de Web Context para cada salto de redireccionamiento.
    • El resto del registro de la fuente sigue siendo el mismo.

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

    • En el caso de los activadores que se producen en las apps, estas registran activadores con la API de Attribution Reporting de Android como de costumbre.

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

  1. Configura destinos dobles

    • Algunas campañas se pueden configurar para generar conversiones en la app o en la página web del anunciante, según varios factores, como si el usuario tiene instalada la app.
    • En estos casos, se recomienda delegar el registro de la fuente al SO cuando esté disponible para que la fuente se pueda atribuir correctamente, independientemente de dónde se produzca el activador. Cuando se registra la fuente con el SO, se pueden especificar un destino web y una app en los parámetros correspondientes.
    • 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 de la API de Attribution Reporting del SO 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 detallados, se explicará cómo el uso de destinos dobles puede afectar el ruido en tus informes.

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

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

Para apps que usan pestañas personalizadas de Chrome

Es posible que algunas apps usen pestañas personalizadas para renderizar contenido web. Las pestañas personalizadas se comportan de manera similar a una página web normal cuando se miden en apps y sitios web para dispositivos móviles.

  1. Registra una fuente de aplicación y un activador de pestañas personalizadas:

  2. Registra una fuente de pestañas personalizadas y un activador de aplicación:

  3. Registra una fuente y un activador de CCT

Para apps que usan WebView

Es posible que algunas apps usen WebView para mostrar contenido. Hay una variedad de casos de uso para WebView, como renderizar anuncios, alojar contenido web o funciones personalizadas de la app que se adaptan mejor a un formato web.

  1. Para permitir que WebViews use la API de Attribution Reporting, la app de incorporación debe configurarse con los permisos correctos.

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

  3. Cuando se delega al SO, WebView puede usar registerSource o registerWebSource, y registerTrigger o registerWebTrigger. La app que renderiza WebView establece qué métodos usa WebView y se determina por WebView.

    • La diferencia entre registerSource y registerWebSource es qué fuente se registra como el publicador. Con registerSource, la app se registra como el publicador. Un ejemplo de cuándo usar registerSource sería una app de publicador que muestra un anuncio que se renderiza con 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 un WebView y el sitio web que renderiza WebView muestra anuncios. registerTrigger y registerWebTrigger se comportan de manera similar. El diagrama del punto 3 detalla diferentes situaciones en las que un desarrollador de apps o SDKs querría configurar la API para usar registerSource o registerWebSource, y registerTrigger o registerWebTrigger.
    • De forma predeterminada, WebView usará registerSource y registerWebTrigger cuando llame a la API de Attribution Reporting de Android. De esta manera, se asocian las fuentes con la app y los activadores con el origen de nivel superior de la URL en WebView cuando se activa.

      • Si una app requiere un comportamiento diferente, deberá usar un nuevo método setAttributionRegistrationBehavior en la clase androidx.webkit.WebViewSettingsCompat. Este método especificará si WebView debe llamar a registerWebSource() o registerWebTrigger() en lugar de registerSource() o registerTrigger().

      • Este comportamiento se deberá establecer para cada WebView que se inicie.

      • Si el SDK de tecnología publicitaria inicia WebView, el SDK deberá configurar este comportamiento predeterminado.

      • En el caso de las apps que quieran usar registerWebSource() para asociar registros de origen con el sitio web en WebView en lugar de la app, deben unirse a la lista de entidades permitidas de WebApp. Completa este formulario para unirte a la lista de entidades permitidas. El objetivo de la lista de entidades permitidas es mitigar las consideraciones de privacidad en torno al establecimiento de la confianza para el contexto de la Web.

      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 fuente y activador desde WebView.
    1. Registros de fuentes y activadores desde WebView

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

      • 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-OS-Source: {
  "source_event_id":"123001",
  "destination":"android-app://com.example.advertiser",
  ...
}

    3. El resto del registro de la fuente sigue siendo el mismo.

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

    5. 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 el encabezado de respuesta.

    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 configures una implementación de app a la Web, te recomendamos que configures informes de depuración para verificar si las fuentes y los activadores se registran correctamente y, si no es así, recibir información sobre el motivo.

Para conocer los pasos generales de depuración de los informes de atribución, consulta el libro de recetas de depuración.