Prise en charge de la médiation dans le SDK Runtime

La médiation est une méthode courante pour les plates-formes publicitaires côté vente d'offrir une gestion des revenus. Dans un workflow de médiation, le SDK de médiation (le "médiateur") appelle plusieurs réseaux publicitaires (le "médiateur" ou les "médiateurs") pour obtenir la meilleure annonce pour un espace publicitaire donné. Dans certains cas, le médiateur et les réseaux publicitaires qu'il appelle ont besoin que leurs SDK soient présents sur l'appareil et interagissent.

Ce document décrit les principales modifications apportées aux workflows de médiation dans le SDK Runtime. Il aborde les sujets suivants :

• Différences entre les flux de médiation précédents et la prise en charge actuelle de la médiation du SDK Runtime
• Actions de configuration pour les workflows de médiation dans le SDK Runtime et différentes étapes de transition
• Conseils pour gérer les scénarios où tous les SDK n'ont pas été migrés vers l'environnement d'exécution

La prise en charge des annonces médiatées dans le SDK Runtime est disponible à partir de la version AGP 8.5 et des versions suivantes des bibliothèques Jetpack du SDK Runtime:

Bibliothèque AndroidX	Version
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

Glossaire

Les termes suivants sont essentiels pour comprendre la médiation dans le SDK Runtime:

• SDK compatible avec l'environnement d'exécution (SDK RE) : SDK conçu pour s'exécuter dans l'environnement SDK Runtime et communiquer avec l'application via la communication inter-processus (IPC).
• SDK compatible avec l'environnement d'exécution (SDK RA) : SDK non compatible avec l'environnement d'exécution, associé de manière statique à l'application, qui peut contenir votre code de SDK existant ainsi qu'un nouveau code à appeler dans votre SDK compatible avec l'environnement d'exécution.
• SDK intégré à l'application:SDK qui s'exécute de manière statique en étant associé à l'application et qui n'est pas conscient du SDK Runtime. Il peut s'agir d'un réseau publicitaire qui n'est pas passé au SDK Runtime ou de l'adaptateur personnalisé d'un éditeur.
• Médiateur:SDK de médiation publicitaire qui fournit un service de médiation sur l'appareil en interagissant avec d'autres SDK de réseaux publicitaires.
• Mediatee:SDK du réseau publicitaire appelé par le médiateur pour fournir et afficher une annonce.
• Adaptateur de médiation:SDK utilisés par le SDK de médiateur pour fournir une traduction d'interface API afin d'interagir avec divers SDK de médiateur, généralement fournis par le médiateur. Ils peuvent être conscients de l'environnement d'exécution ou non.

Flux de médiation typiques

Si votre SDK doit prendre en charge les cas d'utilisation de la médiation dans le SDK Runtime, vous devrez apporter quelques modifications. Cette section examine les éléments clés des flux de médiation afin que nous puissions répondre aux modifications requises pour les médiateurs et les médiateurs.

Les flux que nous décrivons représentent une version simplifiée de la médiation sur l'appareil avec plusieurs SDK de réseaux publicitaires. Ils servent de base de discussion sur les modifications requises pour rendre les parcours de médiation compatibles avec le SDK Runtime.

Compte tenu de la variation des implémentations du flux de médiation, nous nous concentrons sur les deux principaux flux suivants:

• Initialisation (y compris la découverte des réseaux publicitaires et la communication)
• Présentation de l'interface utilisateur (UI) des annonces

Initialisation

Ce qui suit représente une initialisation, une détection de réseaux publicitaires et un flux de communication standards:

1. L'application cliente lance le médiateur
2. Le médiateur détecte et initialise les médiateurs et les adaptateurs pertinents.
3. Le médiateur utilise ses adaptateurs pour communiquer avec chaque médiateur.
4. L'application cliente demande au médiateur de charger une annonce.
5. L'application cliente demande au médiateur de diffuser cette annonce.

Remarque :Ce flux suppose que l'application cliente dépend du SDK du médiateur, des SDK des médiateurs et des adaptateurs de médiation, et qu'elle est compilée avec eux.

Présentation de l'UI des annonces

Pour afficher l'annonce après la dernière demande de l'étape précédente, le flux dépend du type d'annonce:

Bannières	Annonces plein écran	Annonces natives
Le SDK de médiation crée une vue d'annonce, qui encapsule la vue d'annonce du médiateur gagnant. Il peut également définir des écouteurs sur cette vue ou actualiser automatiquement l'annonce (à l'aide du même médiateur ou d'un autre).	Le SDK du médiateur demande une annonce plein écran au médiateur, qui lance à son tour une activité.	L'éditeur gère la gestion et le gonflement des vues à l'aide des composants renvoyés par le SDK de médiation.

Flux de médiation dans le SDK Runtime

Le fonctionnement de la médiation dans le SDK Runtime varie selon que le médiateur est compatible avec l'environnement d'exécution ou non. Sur la base de ces informations, nous pouvons avoir les scénarios suivants:

• Le médiateur et le médiateur se trouvent dans le SDK Runtime: médiateur RE
• Le médiateur se trouve dans le SDK Runtime, et le médiaté dans l'application: Médiaté dans l'application

RE Mediatee

Le diagramme d'architecture suivant présente une vue d'ensemble de l'interaction des SDK compatibles avec l'environnement d'exécution (RE) et de l'environnement d'exécution (RA) du médiateur, des adaptateurs de médiation RE et des SDK RE des médiateurs.

Les adaptateurs de médiation doivent se trouver dans le même processus que le médiateur avec lequel ils interagissent. Ils devront donc également migrer vers le SDK Runtime.

Figure 1. Le médiateur et le médiateur sont tous deux des SDK RE.

Initialisation

En ce qui concerne l'initialisation, la découverte et la communication du médiateur et du médiateur compatible avec l'environnement d'exécution, le flux se déroule comme suit:

1. L'application (ou le SDK RA) charge et initialise le SDK de médiation à l'aide de SdkSandboxManager#loadSdk.
2. Lors de son initialisation, le SDK de médiation charge et initialise tous les médiateurs requis dans le SDK Runtime à l'aide de SdkSandboxController#loadSdk.
3. Le SDK RE peut découvrir tous les SDK chargés dans l'environnement d'exécution en appelant SdkSandboxController#getSandboxedSdks.

Figure 2 Flux d'initialisation d'un médiateur RE.

Remarque :Utilisez les classes *Compat Runtime Manager et Controller pour vous assurer que votre SDK compatible avec l'environnement d'exécution est rétrocompatible.

Présentation de l'UI des annonces

La section suivante traite du chargement de bannières et d'annonces en plein écran à partir d'un médiateur RE.

Bannières publicitaires RE Mediatee

Lorsqu'une application demande à charger une bannière publicitaire, le flux de rendu est le suivant:

1. Le médiateur sélectionne le médiateur gagnant pour cette annonce.
2. Le médiateur obtient un SandboxedUiAdapter auprès du médiateur.
3. Le médiateur transfère l'UiAdapter à l'application.

Figure 3 Flux permettant d'afficher une bannière à partir d'un médiateur RE.

En savoir plus sur l'utilisation de SandboxedUiAdapter et de la bibliothèque d'UI du SDK Runtime

Superpositions sur les bannières

Si les médiateurs souhaitent ajouter une superposition à l'annonce, ils doivent modifier le flux comme suit:

1. Le médiateur crée une mise en page avec sa superposition et un SandboxedSdkView.
2. Le médiateur sélectionne le médiateur gagnant pour cette annonce.
3. Le médiateur obtient un SandboxedUiAdapter auprès de la personne médiatée.
4. Le médiateur définit le UiAdapter du médiateur sur SandboxedSdkView.
5. Le médiateur partage la vue renseignée avec l'application.

Flux permettant de superposer une vue à une bannière publicitaire obtenue à partir d'un RE Mediatee.

Annonces plein écran RE Mediatee

Lorsqu'une application demande à charger une annonce en plein écran, le flux se déroule comme suit:

1. L'application (ou le SDK RA) transmet un SdkActivityLauncher au médiateur avec la demande de chargement d'une annonce.
   1. Le client peut limiter la création d'activités à l'aide d'un prédicat.
2. Le médiateur sélectionne le médiateur gagnant pour cette annonce.
3. Le médiateur demande au médiateur de charger une annonce, en transmettant le SdkActivityLauncher à partir de l'application.
4. Le médiateur enregistre un gestionnaire d'activités et obtient un jeton d'identifiant pour l'activité enregistrée.
5. Le tiers utilise SdkActivityLauncher pour demander à démarrer une activité à l'aide de ce jeton.
6. Si le prédicat de l'application cliente le permet, le SDK Runtime démarre cette activité dans le processus dédié.

Figure 4 Diagramme de flux illustrant comment charger une annonce plein écran médiatisée à partir d'un RE Mediatee.

Remarque :Tous les événements de cycle de vie de l'activité sont disponibles pour le médiateur à l'aide de l'ActivityHolder qu'il a utilisé lors de l'enregistrement du gestionnaire d'activité.

En savoir plus sur la prise en charge de l'activité pour les annonces en plein écran dans le SDK Runtime

Mediatee intégré à l'application

Le diagramme d'architecture suivant présente une vue d'ensemble de l'interaction des SDK RE et RA du médiateur, des adaptateurs de médiation qui ne connaissent pas le SDK Runtime et des SDK des médiateurs liés de manière statique à l'application (qui ne connaissent pas non plus l'environnement d'exécution).

Figure 5 : Le médiateur est associé de manière statique à l'application, même s'il connaît le SDK compatible avec l'environnement d'exécution.

Initialisation

Étant donné que, dans ce scénario, les médiateurs sont associés de manière statique à l'application et n'ont pas encore été migrés vers le SDK Runtime, le SDK compatible avec l'environnement d'exécution du médiateur doit disposer d'un processus pour les enregistrer.

Cet enregistrement doit être accessible à l'aide de l'API du médiateur, mais les détails de l'implémentation sont laissés à la discrétion de chaque médiateur. Nous appelons cette API MediationSandboxedSdk#registerInAppMediatee.

Pour l'initialisation, la découverte et la communication d'un SDK de médiateur RE et de SDK de médiation dans l'application, le flux se déroule comme suit:

1. L'application charge et initialise le SDK compatible avec l'environnement d'exécution du médiateur.
2. Le SDK RA du médiateur :
   1. Initialise le SDK RE du médiateur à l'aide de SdkSandboxManager#loadSdk.
   2. Initialise tous les SDK de médiation dans l'application.
   3. Détecte et enregistre les SDK de médiation dans l'application à l'aide de l'API fournie par le SDK RE, MediationSandboxedSdk#registerInAppMediate.

En plus d'enregistrer tous les SDK de médiation dans l'application, le SDK RE du médiateur peut découvrir tous les SDK chargés dans le SDK Runtime à l'aide de SdkSandboxController#getSandboxedSdks.

Figure 6 : Notez que nous utilisons l'API du médiateur suggéré pour enregistrer la référence aux médiateurs intégrés à l'application.

Présentation de l'UI des annonces

La section suivante concerne le chargement de bannières et d'annonces en plein écran à partir d'un médiateur intégré à l'application.

Bannières dans l'application

Lorsqu'une application demande à charger une bannière publicitaire, le flux de rendu est le suivant:

1. Le SDK compatible avec l'environnement d'exécution du médiateur transfère la requête de l'application à son SDK compatible avec l'environnement d'exécution.
2. Le SDK de remarketing du médiateur sélectionne le médiateur concerné.
3. Le SDK RE du médiateur récupère la référence au médiateur et demande à charger une annonce via le SDK RA.
4. Le SDK RA obtient une vue de l'intermédiaire dans l'application.
5. Le SDK RA crée un SandboxedUiAdapter pour la vue qu'il a reçue.
6. Le SDK RA transfère le UiAdapter au SDK RE.
7. Le SDK RE transfère le UiAdapter à l'application.

Attention :Étant donné que cet élément SandboxedUiAdapter est reçu à partir du processus de l'application, nous vous déconseillons d'ajouter des superpositions à cette vue, car cela peut entraîner des problèmes de latence, de performances et de comportement.

Figure 7 : Notez que le médiateur ne doit pas superposer les vues à la version 1 lorsqu'il l'obtient à partir d'un médiateur intégré à l'application.

Annonces plein écran dans l'application

Lorsqu'une application demande à charger une annonce en plein écran, le flux se déroule comme suit:

1. L'application transmet un SdkActivityLauncher au SDK RA du médiateur avec la demande de chargement d'une annonce.
   1. Le client peut limiter la création d'activités à l'aide d'un prédicat.
2. Le SDK RA du médiateur transmet la requête de l'application à son SDK RE.
3. SDK de RE du médiateur :
   1. Sélectionne le médiateur concerné.
   2. Récupère la référence au médiateur dans l'application.
   3. Demandes de chargement d'une annonce via le SDK RA.
4. Le SDK RA demande au médiateur de charger une annonce.
5. Le médiateur lance l'activité directement. Le prédicat de l'application ne sera pas honoré.

Figure 8 Le prédicat sera ignoré par le médiateur intégré à l'application.

Remarque :Tous les événements liés à l'activité sont disponibles pour le médiateur comme avant le SDK Runtime.

Interagir et envoyer des commentaires

La Privacy Sandbox sur Android est un projet en cours, et ce document reflète sa conception actuelle. Vos commentaires sont essentiels pour nous permettre de continuer à développer et à améliorer ses fonctionnalités. Signalez un bug pour nous faire part de vos commentaires.