API de Attribution Reporting: guía de integración

A medida que leas la documentación de Privacy Sandbox en Android, usa el botón Versión preliminar para desarrolladores o Beta para seleccionar la versión del programa con la que estás trabajando, ya que las instrucciones pueden variar.

La API de Attribution Reporting se diseñó para admitir casos de uso clave en la atribución y la medición de conversiones en apps y la Web, sin depender de identificadores de usuario entre partes. En comparación con los diseños comunes de hoy, los implementadores de la API de Attribution Reporting deben tener en cuenta las siguientes consideraciones importantes de carácter general:

  • Los informes a nivel del evento incluyen datos de conversiones de baja fidelidad. Una pequeña cantidad de valores de conversión funciona bien.
  • Los informes agregables incluyen datos de conversiones de mayor fidelidad. Tus soluciones deben diseñar claves de agregación según tus requisitos empresariales y el límite de 128 bits.
  • Los modelos de datos y el procesamiento de tu solución deben tener en cuenta los límites de frecuencia de los activadores disponibles, las demoras para enviar eventos de activación y el ruido que aplica la API.

Para ayudarte con la planificación de integración, esta guía proporciona una vista integral, que puede incluir funciones que aún no se implementaron en la etapa actual de Privacy Sandbox en la Vista preliminar para desarrolladores de Android. En estos casos, se proporciona orientación sobre el cronograma.

En esta página, usamos fuente para representar un clic o una vista, y activador para representar una conversión.

En el siguiente gráfico, se muestran las diferentes opciones de flujo de trabajo para la integración de la atribución. Las secciones que aparecen en la misma columna (enmarcadas en verde) se pueden llevar a cabo en paralelo. Por ejemplo, la participación de los socios se puede hacer al mismo tiempo que la atribución de nivel de evento de app a app.

Diagrama del flujo de trabajo de integración de la atribución

Figura 1: Flujo de trabajo de integración de la atribución.

Requisitos previos y configuración

Completa los pasos de esta sección para mejorar tu comprensión de la API de Attribution Reporting. Con estos pasos, te prepararás para obtener resultados significativos cuando uses la API en el ecosistema de tecnología publicitaria.

Familiarízate con la API

  1. Lee la propuesta de diseño para familiarizarte con la API de Attribution Reporting y sus funciones.
  2. Lee la guía para desarrolladores para obtener información que te permita incorporar el código y las llamadas a la API que necesitarás en tus casos de uso.
  3. Regístrate para recibir actualizaciones sobre la API de Attribution Reporting Esto te ayudará a estar al tanto de las funciones nuevas que se incluirán en versiones futuras.

Configura y prueba la app de ejemplo

  1. Una vez que esté todo listo para comenzar la integración, obtén la Versión preliminar para desarrolladores más reciente en Android Studio.
  2. Configura extremos de servidor simulados para los registros de eventos y las entregas de informes. Brindamos simulaciones que puedes usar en conjunto con las herramientas disponibles en línea.
  3. Descarga y ejecuta el código en nuestra app de ejemplo para familiarizarte con el registro de fuentes y activadores.
    1. Establece el período para enviar informes. La API admite períodos de 2 o 7 días, o un período personalizado de entre 2 y 30 días.
    2. Una vez que ejecutes y uses la app de ejemplo para registrar las fuentes y los activadores, y que el período establecido haya transcurrido, verifica que hayas recibido un informe a nivel de evento y un informe encriptado agregable. Si necesitas depurar informes, puedes generarlos más rápido con la ejecución forzada de trabajos de informes.
    3. Revisa los resultados de la atribución app a app. Confirma que los datos de estos resultados sean los esperados para los casos de último contacto y los posteriores a la instalación.

  4. Una vez que conozcas el funcionamiento en conjunto de la API del cliente y el servidor, usa la app de ejemplo como muestra para guiar tu propia integración. Configura tu propio servidor de producción y agrega llamadas de registro de eventos a tus apps.

Antes de la integración

Registra tu organización con Privacy Sandbox en Android. Esta inscripción se diseñó para evitar la duplicación innecesaria de plataformas de tecnología publicitaria, lo que permitiría el acceso a más información de la necesaria en las actividades del usuario.

Participación de los socios

Los socios de tecnología publicitaria (MMP/SSP/DSP) suelen crear soluciones de atribución integradas. Los pasos que se indican en esta sección te ayudan a prepararte para tener éxito en la interacción con tus socios de tecnología publicitaria.

  1. Programa una conversación con tus principales socios de medición sobre las pruebas y la adopción de la API de Attribution Reporting. Los socios de medición pueden incluir redes de tecnología publicitaria, SSP, DSP, anunciantes o cualquier otro socio con el que trabajes actualmente o con el que desearías trabajar.
  2. Colabora con tus socios de medición para definir los cronogramas de integración, desde las pruebas iniciales hasta la adopción.
  3. Aclara con tus socios de medición las áreas que se abarcarán en el diseño de atribución.
  4. Establece canales de comunicación entre los socios de medición para sincronizar los cronogramas y las pruebas de extremo a extremo.
  5. Diseña flujos de datos de alto nivel entre los socios de medición. Las consideraciones clave incluyen lo siguiente:
    • ¿Cómo registrarán los socios de medición las fuentes de atribución con la API de Attribution Reporting?
    • ¿Cómo registrarán los activadores las redes de tecnología publicitaria con la API de Attribution Reporting?
    • ¿Cómo validará la tecnología publicitaria las solicitudes a la API y mostrará las respuestas para completar los registros de fuentes y activadores?
    • ¿Hay informes que se deban compartir con los socios ajenos a la API de Attribution Reporting?
    • ¿Se necesitan otros puntos de integración o alineación entre los socios? Por ejemplo, ¿tú y tus socios deben trabajar para anular las duplicaciones de conversiones o alinearse con respecto a las claves de agregación?
  6. Si la atribución de app a la Web es aplicable, programa una reunión con los socios de medición en la Web para analizar el diseño, las pruebas y la adopción de la API de Attribution Reporting. Consulta las preguntas del paso anterior cuando inicies las conversaciones con los socios web.

Crea prototipos de atribución de nivel de evento de app a app

Esta sección te ayuda a configurar una atribución básica de app a app con informes a nivel de evento en tu app o SDK. Debes completar esta sección para poder comenzar el prototipado de la atribución del servidor de agregación.

  1. Configura un servidor de recopilación para los registros de eventos. Puedes hacerlo con las especificaciones proporcionadas para generar un servidor simulado o configurar tu propio servidor con el código del servidor de muestra.
  2. Agrega llamadas de registros de eventos fuente a tu SDK o app cuando se muestren los anuncios.
    • Las consideraciones críticas incluyen lo siguiente:
      • Asegúrate de que los IDs del evento fuente estén disponibles y se pasen correctamente a las llamadas a la API de registro de fuente.
      • Asegúrate de pasar también un elemento "InputEvent" para registrar fuentes de clics.
      • Determina el modo en que configurarás la prioridad de la fuente para diferentes tipos de eventos. Por ejemplo, asigna una prioridad alta a los eventos que se consideran de alto valor, como los clics por sobre las vistas.
      • El valor predeterminado para el vencimiento es adecuado para las pruebas. De manera alternativa, se pueden configurar diferentes períodos de vencimiento.
      • Para los filtros y las ventanas de atribución pueden conservarse los valores predeterminados durante las pruebas.
    • Las consideraciones opcionales incluyen lo siguiente:
      • Diseña claves de agregación si tienes todo listo para usarlas.
      • Considera tu estrategia de redireccionamiento cuando establezcas el modo en que deseas trabajar con otros socios de medición.
  3. Agrega eventos de registro de activación a tu SDK o app para registrar eventos de conversión.
    • Las consideraciones críticas incluyen lo siguiente:
    • Las consideraciones opcionales incluyen lo siguiente:
      • Omite la creación de claves de anulación de duplicación hasta que realices pruebas de precisión.
      • Omite la creación de claves y valores de agregación hasta que la compatibilidad con pruebas de simulación esté lista.
      • Omite los redireccionamientos hasta que establezcas el modo en que quieres trabajar con otros socios de medición.
      • La prioridad del activador no es esencial para las pruebas.
      • Es probable que se ignoren los filtros de las pruebas iniciales.
  4. Prueba que los eventos de fuentes se generen para los anuncios y que los activadores dirijan a la creación de informes de eventos.

Pruebas de simulación

En esta sección, se explica el modo para probar el impacto que puede tener en los sistemas de informes y optimización mover las conversiones actuales a informes agregables y eventos. Esto te permitirá iniciar pruebas de impacto antes de finalizar la integración.

Las pruebas se realizan con la simulación de la generación de informes de eventos y agregables basados en los registros de conversiones históricos que tienes y, luego, la obtención de los resultados agregados de un servidor de agregación simulado. Estos resultados se pueden comparar con las cifras de conversión históricas para ver el modo en que cambiaría la precisión de los informes.

Los modelos de optimización, como los cálculos del porcentaje de conversiones estimado, se pueden entrenar en estos informes para comparar la precisión de estos modelos en comparación con los que se basan en datos actuales. Esta también es una oportunidad para experimentar con diferentes estructuras de claves de agregación y su impacto en los resultados.

  1. Configura la Biblioteca de simulación de mediciones en una máquina local.
  2. Lee la especificación sobre el modo en que se debe dar formato a los datos de conversiones para que sean compatibles con el generador de informes simulado.
  3. Diseña tus claves de agregación según los requisitos comerciales.
    • Las consideraciones críticas incluyen lo siguiente:
      • Considera las dimensiones críticas que tus clientes o socios necesitan para agregar y enfocar tu evaluación en ellas.
      • Determina la cantidad mínima de dimensiones y cardinalidades agregadas necesarias para tus requisitos.
      • Asegúrate de que las partes de la clave de la fuente y del activador no superen los 128 bits.
      • Si tus soluciones implican contribuir a varios valores por evento de activador, asegúrate de escalar los valores con el presupuesto de contribución máximo, L1. Esta acción ayudará a minimizar el impacto del ruido.
      • Este es un ejemplo en el que se detalla la configuración de una clave para recopilar recuentos de conversiones agregadas a nivel de la campaña y una clave para recopilar valores de compra agregados a nivel de ubicación geográfica.
  4. Ejecuta el generador de informes para crear informes agregables y de eventos.
  5. Ejecuta los informes agregables a través de los servidores de agregación simulados para obtener informes de resumen
  6. Realiza experimentos de utilidad:
    • Compara los totales de conversiones de los informes a nivel de evento y de resumen con los datos de conversiones históricos para determinar la precisión de los informes de conversiones. Para obtener mejores resultados, ejecuta las pruebas de informes y las comparaciones en una parte amplia y representativa de la base de anunciantes.
    • Vuelve a entrenar tus modelos según los datos de informes a nivel de evento y, potencialmente, los datos de informes del resumen. Compara la exactitud con los modelos basados en datos de entrenamiento históricos.
    • Prueba diferentes estrategias de lote y observa el modo en que afectan tus resultados.
      • Las consideraciones críticas incluyen lo siguiente:
      • Posibilidad de los informes de resumen para ajustar ofertas.
      • Frecuencias promedio de eventos atribuibles al dispositivo. Por ejemplo, los usuarios inactivos que regresan en función de los datos históricos de eventos de compra.
      • Nivel de ruido. Más lotes implica una agregación más pequeña, mientras que una agregación más pequeña implica más ruido.

Crea un prototipo de atribución del servidor de agregación: Configuración

Estos pasos garantizarán que puedas recibir informes agregables de tus eventos de fuente y activadores.

  1. Configura el servidor de agregación:
    • Configura tu cuenta de AWS.
    • Inscríbete en el servicio de agregación con tu coordinador.
    • Configura el servidor de agregación en AWS a partir de los objetos binarios proporcionados.
  2. Diseña tus claves de agregación según los requisitos comerciales. Si ya completaste esta tarea en la sección de nivel de evento de app a app, puedes omitir este paso.
  3. Configura un servidor de recopilación para los informes agregables. Si ya creaste uno en la sección de nivel de evento de app a app, puedes volver a usarlo.

Prototipo de atribución del servidor de agregación: Integración

Para continuar más allá de este punto, debes haber completado la sección Prototipo de atribución del servidor de agregación: Configuración o la sección Crea prototipos de atribución de nivel de evento de app a app**.

  1. Agrega datos clave de agregación a tus eventos de fuentes y activadores. Es probable que debas pasar más datos sobre el evento del anuncio, como el ID de la campaña, a tu SDK o app para incluirlos en la clave de agregación.
  2. Recopila informes agregables de app a app desde los eventos de fuente y activador que registraste con datos de claves de agregación.
  3. Prueba diferentes estrategias de lote a medida que ejecutes estos informes agregables a través del servidor de agregación y observa los efectos en tus resultados.

Itera el diseño con funciones opcionales

Las siguientes son funciones adicionales que puedes incluir en tu solución de medición.

  1. La configuración de una clave de depuración te permitirá recibir un informe sin cambios de un evento de fuente o activador junto con los informes que generó la API de Attribution Reporting. Puedes usar claves de depuración para comparar informes y encontrar errores durante la integración.

Personaliza comportamientos de atribución

  1. Atribución para activadores posteriores a la instalación
    • Esta función se puede usar cuando los activadores posteriores a la instalación tengan que atribuirse a la misma fuente de atribución que generó la instalación, incluso si hay otras fuentes de atribución aptas que ocurrieron recientemente.
    • Por ejemplo, puede haber un caso en el que un usuario hace clic en un anuncio que genera una instalación. Una vez terminada la instalación, el usuario hace clic en otro anuncio y realiza una compra. En este caso, es posible que la empresa de tecnología publicitaria desee atribuir la compra al primer clic en lugar del clic para volver a generar participación.
  2. Usa filtros para ajustar los datos en los informes a nivel del evento
    • Los filtros de conversión se pueden configurar para ignorar los activadores seleccionados y excluirlos de los informes de eventos. Debido a que hay límites en la cantidad de activadores por fuente de atribución, los filtros solo te permiten incluir los activadores que proporcionan la información más útil en tus informes de eventos.
    • Los filtros también se pueden usar para filtrar de manera selectiva algunos activadores y, también, ignorarlos de forma efectiva. Por ejemplo, si tienes una campaña orientada a instalaciones de apps, es posible que desees filtrar los activadores posteriores a la instalación para que no se atribuyan a las fuentes de esa campaña.
    • Los filtros también se pueden usar para personalizar los datos del activador según los datos de la fuente. Por ejemplo, una fuente puede especificar "product" : ["1234"], en el que product es la clave de filtro y 1234 es el valor. Se ignorará cualquier activador con una clave de filtro de "product" que tenga un valor distinto de "1234".
  3. Fuente personalizada y prioridad del activador
    • En el caso de que se puedan asociar varias fuentes de atribución a un activador, o que se puedan atribuir varios activadores a una fuente, puedes usar un número entero de 64 bits firmado para priorizar ciertas atribuciones de fuente/activador por sobre otras.

Cómo trabajar con MMPs y otros

  1. Redirecciona a otros terceros para eventos de fuente y activadores
    • Puedes configurar las URLs de redireccionamiento para permitir que varias plataformas de tecnología publicitaria registren una solicitud. Se puede usar para habilitar la anulación de duplicación entre redes en la atribución.
  2. Claves de anulación de duplicación
    • Cuando un anunciante usa varias plataformas de tecnología publicitaria para registrar el mismo evento de activación, se puede usar una clave de anulación de duplicación para eliminar la ambigüedad en estos informes repetidos. Si no se proporciona una clave de anulación de duplicación, los activadores duplicados se pueden informar a cada plataforma de tecnología publicitaria como únicos.

Cómo trabajar con mediciones multiplataforma

  1. Atribución web y entre apps (disponible a finales del cuarto trimestre)
    • Admite casos de uso en los que un usuario ve un anuncio en una app y, luego, genera una conversión en un navegador para dispositivos móviles o apps, o viceversa.