Compatibilidad con la mediación en el entorno de ejecución de SDK

La mediación es una forma común en que las plataformas de anuncios orientadas a la venta ofrecen la administración de ingresos. En un flujo de trabajo de mediación, el SDK de mediación ('mediador') invoca varias redes de publicidad ('mediado' o 'mediados') para obtener el mejor anuncio para un espacio publicitario determinado. En algunos casos, tanto el mediador como las redes de publicidad que invoca necesitan que sus SDKs estén en el dispositivo y que interactúen.

En este documento, se describen los cambios clave en los flujos de trabajo de mediación en el entorno de ejecución del SDK. Abarca los siguientes temas:

• Diferencias entre los flujos de mediación anteriores y la compatibilidad actual con la mediación del entorno de ejecución del SDK
• Acciones de configuración para flujos de trabajo de mediación en el entorno de ejecución de SDK y las diferentes etapas de transición
• Orientación para controlar situaciones en las que no todos los SDKs migraron al entorno de ejecución

La compatibilidad con los anuncios mediados en el entorno de ejecución de SDK está disponible a partir de AGP 8.5 y de las siguientes versiones de las bibliotecas de Jetpack del entorno de ejecución de SDK:

Biblioteca de AndroidX	Versión
androidx.privacysandbox.activity	1.0.0-alpha01
androidx.privacysandbox.sdkruntime	1.0.0-alpha13
androidx.privacysandbox.tools	1.0.0-alpha08
androidx.privacysandbox.ui	1.0.0-alpha09

Glosario

Los siguientes términos son clave para comprender la mediación en el entorno de ejecución de SDK:

• SDK habilitado para el entorno de ejecución (SDK de RE): Es un SDK diseñado para ejecutarse en el entorno de ejecución de SDK y comunicarse con la app a través de la comunicación entre procesos (IPC).
• SDK compatible con el entorno de ejecución (SDK de RA): Es un SDK que no está habilitado para el entorno de ejecución, vinculado a la app de forma estática, que puede contener el código de tu SDK existente, así como código nuevo para llamar a tu SDK habilitado para el entorno de ejecución.
• SDK integrado en la app: Es un SDK que se ejecuta vinculado a la app de forma estática y que no tiene conocimiento del entorno de ejecución de SDK. Puede ser una red de publicidad que no realizó la transición al entorno de ejecución de SDK o el adaptador personalizado de un publicador.
• Mediador: Es un SDK de mediación de anuncios que proporciona un servicio de mediación integrado en el dispositivo a través de la interacción con otros SDKs de redes de publicidad.
• Mediatee: Es el SDK de la red de publicidad al que llama el mediador para proporcionar y renderizar un anuncio.
• Adaptador de mediación: Son los SDKs que usa el SDK de Mediator para proporcionar traducción de interfaz de API para interoperar con varios SDKs de mediatee, que suele proporcionar el mediador. Pueden ser conscientes o no del entorno de ejecución.

Flujos de mediación típicos

Si tu SDK necesita admitir casos de uso de mediación en el entorno de ejecución de SDK, deberás implementar algunos cambios. En esta sección, se revisan los elementos clave de los flujos de mediación para que podamos abordar los cambios necesarios para los mediadores y los mediados.

Los flujos que describimos representan una versión simplificada de la mediación integrada en el dispositivo con varios SDKs de redes publicitarias y sirven como base para analizar los cambios necesarios para que los recorridos de mediación sean compatibles con el entorno de ejecución de SDK.

Dada la variación en las implementaciones de flujos de mediación, nos enfocamos en los siguientes dos flujos principales:

• Inicialización (incluida la detección de redes de publicidad y la comunicación)
• Presentación de la interfaz de usuario (IU) del anuncio

Inicialización

A continuación, se muestra una inicialización estándar, el descubrimiento de redes de anuncios y el flujo de comunicación:

1. La app cliente inicia el mediador
2. El mediador descubre e inicializa los mediadores y adaptadores relevantes.
3. El mediador usa sus adaptadores para comunicarse con cada mediado.
4. La app cliente solicita al mediador que cargue un anuncio.
5. La app cliente le solicita al mediador que muestre este anuncio.

Nota: En este flujo, se supone que la app cliente depende del SDK del mediador, de los SDKs de los mediadores y de los adaptadores de mediación, y que se compila con ellos.

Presentación de la IU del anuncio

Cuando se trata de renderizar el anuncio después de la solicitud final en el paso anterior, el flujo depende del tipo de anuncio:

Anuncios de banner	Anuncios de pantalla completa	Anuncios nativos
El SDK del mediador crea una vista de anuncio, que une la vista de anuncio del mediado ganador. También puede establecer objetos de escucha en este objeto View o actualizar automáticamente el anuncio (con el mismo mediador o con uno diferente).	El SDK del mediador solicita un anuncio de pantalla completa al mediado, que a su vez inicia una actividad.	El publicador administra el control y el aumento de la vista con los componentes que devuelve el SDK del mediador.

Flujos de mediación en el entorno de ejecución de SDK

El funcionamiento de la mediación dentro del entorno de ejecución de SDK es diferente según si el medio está habilitado para el entorno de ejecución o no. En función de esto, podemos tener las siguientes situaciones:

• El mediador y el objeto mediado se encuentran en el entorno de ejecución de SDK: objeto mediado de RE
• El mediador está en el entorno de ejecución de SDK y el mediado está en la app: Mediado en la app

RE Mediatee

En el siguiente diagrama de arquitectura, se muestra una descripción general de alto nivel de la interacción de los SDKs habilitados para el entorno de ejecución (RE) y conscientes del entorno de ejecución (RA) del mediador, los adaptadores de mediación de RE y los SDKs de RE de los mediadores.

Los adaptadores de mediación deben estar en el mismo proceso que el mediado con el que interactúan, por lo que también deberán migrar al entorno de ejecución de SDK.

Figura 1: Tanto el mediador como el mediado son SDKs de RE.

Inicialización

Cuando se considera la inicialización, el descubrimiento y la comunicación del mediador y del mediado habilitados para el entorno de ejecución, el flujo seguirá estos pasos:

1. La app (o el SDK de RA) carga e inicializa el SDK del mediador con SdkSandboxManager#loadSdk.
2. Durante su inicialización, el SDK del mediador carga e inicializa cualquier mediado requerido en el tiempo de ejecución del SDK con SdkSandboxController#loadSdk.
3. El SDK de RE puede descubrir todos los SDKs cargados en el entorno de ejecución llamando a SdkSandboxController#getSandboxedSdks.

Figura 2: Flujo para inicializar un mediado de RE.

Nota: Usa las clases *Compat Runtime Manager y Controller para asegurarte de que tu SDK habilitado para el entorno de ejecución sea retrocompatible.

Presentación de la IU del anuncio

En la siguiente sección, se describe cómo cargar banners y anuncios de pantalla completa desde un mediatee de RE.

Anuncios de banner de RE Mediatee

Dada una solicitud de la app para cargar un anuncio de banner, el flujo para completar la renderización es el siguiente:

1. El mediador selecciona el mediado ganador para este anuncio.
2. El mediador obtiene un SandboxedUiAdapter del mediado.
3. El mediador reenvía el UiAdapter a la app.

Figura 3: Flujo para completar la renderización de un anuncio de banner desde un mediador de RE.

Obtén más información sobre el uso de SandboxedUiAdapter y la biblioteca de IU del entorno de ejecución de SDK.

Superposiciones en los anuncios de banner

Si los mediadores quieren agregar una superposición al anuncio, deben modificar el flujo de la siguiente manera:

1. El mediador crea un diseño con su superposición y un SandboxedSdkView.
2. El mediador selecciona el mediado ganador para este anuncio.
3. El mediador obtiene un SandboxedUiAdapter del mediado.
4. El mediador establece el UiAdapter del objeto mediado en SandboxedSdkView.
5. El mediador comparte la vista propagada con la app.

Flujo para superponer una vista sobre un anuncio de banner obtenido de un Mediatee de RE.

Anuncios de pantalla completa de Mediatee

Cuando la app realiza una solicitud para cargar un anuncio de pantalla completa, el flujo sigue estos pasos:

1. La app (o el SDK de RA) pasa un SdkActivityLauncher al mediador con la solicitud de cargar un anuncio.
   1. El cliente puede restringir la creación de actividades con un predicado.
2. El mediador selecciona el mediado ganador para este anuncio.
3. El mediador solicita al mediado que cargue un anuncio y pasa el SdkActivityLauncher de la app.
4. El objeto mediado registra un controlador de actividad y obtiene un token de identificador para la actividad registrada.
5. El objeto mediado usa SdkActivityLauncher para solicitar el inicio de una actividad con este token.
6. Si el predicado de la app cliente lo permite, el entorno de ejecución de SDK iniciará esta actividad en el proceso dedicado.

Figura 4: Diagrama de flujo que ilustra cómo cargar un anuncio de pantalla completa mediado desde un Mediatee de RE.

Nota: Todos los eventos del ciclo de vida de la actividad están disponibles para el objeto mediado con el ActivityHolder que usó cuando se registró el controlador de actividad.

Obtén más información sobre la compatibilidad de Activity con los anuncios de pantalla completa en el entorno de ejecución del SDK.

Mediatee integrado en la app

En el siguiente diagrama de arquitectura, se muestra una descripción general de alto nivel de la interacción de los SDK de RA y RE del mediador, de los adaptadores de mediación que no conocen el entorno de ejecución del SDK y de los SDK de los mediadores vinculados de forma estática a la app (también sin conocimiento del entorno de ejecución).

Figura 5: El objeto mediado está vinculado de forma estática a la app, incluso si conoce el SDK de RE.

Inicialización

Dado que, en esta situación, los mediadores están vinculados de forma estática a la app y aún no se migraron al entorno de ejecución de SDK, el SDK habilitado para el entorno de ejecución del mediador debe tener un proceso para registrarlos.

Se debe poder acceder a este registro con la API del mediador, pero los detalles de la implementación quedan a discreción de cada mediador. Llamamos a esta API MediationSandboxedSdk#registerInAppMediatee.

Cuando se considera la inicialización, el descubrimiento y la comunicación de un SDK de mediador de RE y de SDKs mediados en la app, el flujo seguirá estos pasos:

1. La app carga e inicializa el SDK del mediador que admite el entorno de ejecución.
2. SDK de RA del mediador:
   1. Inicializa el SDK de RE del mediador con SdkSandboxManager#loadSdk.
   2. Inicializa todos los SDKs de mediatee integrados en la aplicación.
   3. Descubre y registra los SDKs de mediatee integrados en la app con la API que proporciona el SDK de RE, MediationSandboxedSdk#registerInAppMediate.

Además de tener todos los SDKs mediatizados en la app registrados, el SDK de RE del mediador puede descubrir todos los SDKs cargados en el entorno de ejecución de SDK con SdkSandboxController#getSandboxedSdks.

Figura 6: Ten en cuenta que usamos la API del mediador sugerido para registrar la referencia a los mediadores integrados en la app.

Presentación de la IU del anuncio

En la siguiente sección, se describe cómo cargar banners y anuncios de pantalla completa desde un mediatee integrado en la app.

Anuncios de banner mediatizados en la aplicación

Dada una solicitud de la app para cargar un anuncio de banner, el flujo para completar la renderización es el siguiente:

1. El SDK del mediador que reconoce el entorno de ejecución reenvía la solicitud de la app a su SDK habilitado para el entorno de ejecución.
2. El SDK de RE del mediador selecciona el mediado relevante.
3. El SDK de RE del mediador recupera la referencia al medio y solicita cargar un anuncio a través del SDK de RA.
4. El SDK de RA obtiene una vista del mediado en la aplicación.
5. El SDK de RA crea un SandboxedUiAdapter para la vista que recibió.
6. El SDK de RA reenvía el UiAdapter al SDK de RE.
7. El SDK de RE reenvía el UiAdapter a la app.

Precaución: Dado que este SandboxedUiAdapter se recibe del proceso de la app, no recomendamos agregar superposiciones a esta vista, ya que podría generar problemas de latencia, rendimiento y comportamiento.

Figura 7: Ten en cuenta que el mediador no debe superponer vistas sobre la V1 cuando la obtiene de un mediado en la app.

Anuncios de pantalla completa mediatizados en la aplicación

Cuando la app realiza una solicitud para cargar un anuncio de pantalla completa, el flujo sigue estos pasos:

1. La app pasa un SdkActivityLauncher al SDK de RA del mediador con la solicitud de cargar un anuncio.
   1. El cliente puede restringir la creación de actividades con un predicado.
2. El SDK de RA del mediador reenvía la solicitud de la app a su SDK de RE.
3. SDK de RE del mediador:
   1. Selecciona el mediador relevante.
   2. Recupera la referencia al mediador integrado en la app.
   3. Solicita cargar un anuncio a través del SDK de RA.
4. El SDK de RA solicita al mediado que cargue un anuncio.
5. El objeto mediado inicia la actividad directamente. No se respetará el predicado de la app.

Figura 8: El mediador integrado en la app ignorará el predicado.

Nota: Todos los eventos relacionados con la actividad están disponibles para el mediador como lo estaban antes del entorno de ejecución de SDK.

Interactúa y comparte comentarios

Privacy Sandbox en Android es un proyecto en curso, y este documento refleja su diseño actual. Tus comentarios son esenciales a medida que seguimos desarrollando y mejorando sus funciones. Informa un error para enviar comentarios.