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

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

Cuando configures la atribución en aplicaciones y en la Web, te recomendamos que también te familiarices con las soluciones de depuración disponibles para verificar que tu configuración funcione según lo previsto.

Registra fuentes y activadores con el SO Android

La atribución en la Web y en apps solo estará disponible si la API de Attribution Reporting está habilitada en el navegador y en el SO de 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 devolverá os, web o ambos, según lo que esté disponible en ese dispositivo. Si ambos están disponibles, las tecnologías publicitarias podrán registrar fuentes web 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 para la Web, las tecnologías publicitarias aún pueden registrar tanto las fuentes como los activadores con la API de Attribution Reporting de Chrome o elegir delegar ambos en el SO. En el caso de las campañas solo para la 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 el activador en 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 las APIs de Chrome y Android de forma simultánea para no crear informes de atribución duplicados.

  • La atribución se realiza por separado para los navegadores y el SO. Si una fuente se registra en el navegador, pero el activador se registra en el SO, no se pueden correlacionar, y viceversa.

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

  • 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 en la API de Android Attribution Reporting.

  • En el caso de las campañas en las que tanto la fuente como el activador se producen 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 produciría 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 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 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 indicándole a Chrome que delegue el registro en el 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 correlacionar la fuente de la app y el activador web, y enviar los informes pertinentes.

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

Registro de la fuente de la app:

  1. El SDK de tecnología publicitaria en la app para Android de Daily News 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 del activador web:

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

  2. La ARA web devuelve 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 de forma interna, y el desarrollador no necesita llamar a registerWebTrigger() con el SO directamente.

  5. El 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. El OS ARA realizará la atribución según la misma lógica que se aplica a la atribución de aplicación a aplicación 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 la app 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 la 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) 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 de terceros cuente dos veces los registros. Para evitar el doble recuento de registros, las tecnologías publicitarias pueden modificar el comportamiento de redireccionamiento para enviar el registro de la API de Attribution Reporting a una URL alternativa y determinística.

    • Para habilitar este comportamiento, las tecnologías publicitarias deben incluir un encabezado HTTP nuevo cuando responden 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 el de un registro de fuente estándar de app a app.

  2. La tecnología publicitaria en el sitio web del anunciante registra el activador solicitando a Chrome que delegue el registro en 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 en Chrome.

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

      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 devolverá os, web.

      Attribution-Reporting-Support: os, web

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

      1. Indica a Chrome que delegue el registro en el 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, por lo que 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 pasó 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 establecer 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 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 navega por un sitio en su navegador Chrome en su teléfono Android. Ve un anuncio de un suéter de una de sus tiendas favoritas. Hacen clic en el anuncio y se los dirige a la app que ya descargaron. La tecnología publicitaria del sitio web en el que se publicó el anuncio registra la fuente del clic indicándole a Chrome que delegue el registro en 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 Android Attribution Reporting. La API de Attribution Reporting a nivel del SO puede correlacionar la fuente web y el activador de la app, y enviar los informes pertinentes.

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

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 devuelve 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 de forma interna, y el desarrollador no necesita llamar a registerWebSource() con el SO directamente.

  5. El 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 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 OS ARA realizará la atribución según la misma lógica que se aplica a la atribución de aplicación a aplicación 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 indicándole a Chrome que delegue el registro en la API de Android Attribution Reporting:

    • En el caso de uso de Web a aplicación, cuando se registra una fuente, el parámetro de fuente de atribución debe especificarse 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 devolverá os, web.

    Attribution-Reporting-Support: os, web

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

    1. Indica a Chrome que delegue el registro en el 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, por lo que 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 pasó 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 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 Android Attribution Reporting con el encabezado de respuesta Attribution-Reporting-Register-Source. La respuesta también debe especificar un 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 los 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 los activadores con la API de Android Attribution Reporting de forma normal.

Campañas que tienen destinos potenciales tanto en la aplicación como en la Web

  1. Cómo configurar destinos duales

    • Algunas campañas se pueden configurar para generar conversiones en la app del anunciante o en su página web, según diversos factores, como si el usuario tiene instalada la app.
    • En estos casos, se recomienda delegar el registro de la fuente en el 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 en el SO, se puede especificar un destino web y un destino de app 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 de la API de Attribution Reporting del SO debe ser un paquete de la app 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 aproximados, se explicará cómo el uso de destinos dobles puede afectar el ruido en tus informes.

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

    • 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 en un destino 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 aproximados y reducir el ruido. Si una fuente con el campo coarse_event_report_destinations especificado gana la atribución, el informe resultante incluye los destinos web y de aplicaciones 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 aplicaciones.
    • Los informes agregados no cambian.

Para las apps que usan pestañas personalizadas de Chrome

Es posible que algunas apps usen Custom Tabs para renderizar contenido web. Las pestañas personalizadas se comportan de manera similar a una página web normal cuando se realizan mediciones en aplicaciones 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 aplicaciones:

  3. Registra una fuente y un activador de CCT

Para apps que usan WebView

Es posible que algunas apps usen WebView para mostrar contenido. Existen diversos casos de uso para WebView, como renderizar anuncios, alojar contenido web o funciones personalizadas de la app más adecuadas para un formato web.

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

  2. En WebView, solo está disponible la atribución a nivel del SO. El encabezado Attribution-Reporting-Support solo devolverá el SO y solo si la API de Attribution Reporting de Android está disponible.

  3. Cuando se delega en el SO, WebView puede usar registerSource o registerWebSource y registerTrigger o registerWebTrigger. Los métodos que usa WebView los establece la app que renderiza el WebView y se determinan para cada WebView.

    • La diferencia entre registerSource y registerWebSource es qué fuente se registra como publicador. Con registerSource, la app se registra como publicador. Un ejemplo de cuándo usar registerSource sería una app de publicador que muestra un anuncio renderizado 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 el WebView muestra anuncios. registerTrigger y registerWebTrigger se comportan de manera similar. El gráfico del elemento núm. 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 Android Attribution Reporting. 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, deberá establecer este comportamiento predeterminado.

      • Las apps que deseen usar registerWebSource() para asociar registros de fuentes con el sitio web en WebView en lugar de con 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 restablecimiento 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 Android Attribution Reporting 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 Android Attribution Reporting 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 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 Android Attribution Reporting 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 la app al sitio web, te recomendamos que configures informes de depuración para verificar si las fuentes y los activadores se registran correctamente y, si no se registran, para recibir información sobre el motivo.

Para conocer los pasos generales de depuración de Attribution Reporting, consulta el libro de cocina de depuración.