Proposition de conception de la visibilité du SDK Runtime

Les SDK publicitaires du SDK Runtime ne peuvent pas accéder à la hiérarchie des vues d'un éditeur. Au lieu de cela, les SDK dans le SDK Runtime ont leurs propres vues. Le SDK ne peut pas utiliser les mêmes API View qu'en dehors du SDK Runtime pour déterminer si l'annonce est visible par l'utilisateur, car le visionnage de l'annonce n'est pas joint à la fenêtre de l'application. Cela inclut les API View Android telles que getLocationOnScreen, getLocationInWindow ou getVisibility, qui ne renvoient pas les valeurs attendues.

La prise en charge de la mesure de la visibilité des annonces est une exigence essentielle du SDK Runtime. Cette proposition de conception vise à assurer la compatibilité avec Open Measurement et des services de mesure similaires. Les solutions présentées ici peuvent également s'appliquer aux API Attribution Reporting. N'hésitez pas à nous faire part de vos commentaires sur cette proposition.

Fonctionnalités

Cette conception vise à permettre aux SDK publicitaires ou aux partenaires de mesure de calculer les données de visibilité suivantes (les noms sont provisoires et susceptibles de changer) :

Présentation de la visibilité du SDK Runtime.

• viewport [Rect] : représente l'écran de l'appareil ou la géométrie de la fenêtre de l'application, en fonction des fonctionnalités de la plate-forme.
• uiContainerGeometry [Rect] : géométrie de l'élément SandboxedSdkView affiché.
• alpha [float] : opacité de la vue SandboxedSdkView affichée.
• onScreenGeometry [Rect] : sous-ensemble de uiContainerGeometry qui n'est pas rogné par les vues parentes, jusqu'au viewport (inclus).
• occludedGeometry [Rect] : parties de onScreenGeometry qui sont masquées par des vues dans la hiérarchie de l'application. Inclut un élément Rect pour chaque masquage, correspondant à aucune, une ou plusieurs vues d'application qui se croisent avec SandboxedSdkView onScreenGeometry.

Conditions requises

• Les valeurs de uiContainerGeometry, onScreenGeometry et occludedGeometry sont exprimées dans l'espace de coordonnées du viewport.
• Les rapports sur les changements de visibilité sont générés avec un temps de latence minimal.
• La visibilité est mesurable sur l'ensemble du cycle de vie du visionnage de l'annonce, de sa première apparition à sa dernière.

Proposition de conception

Cette proposition s'appuie sur le fonctionnement de la présentation de l'UI à l'aide des bibliothèques d'interface utilisateur du client et du fournisseur. Nous allons étendre les bibliothèques de l'UI pour permettre au SDK d'enregistrer un ou plusieurs observateurs de la session d'UI. L'observateur reçoit des informations de visibilité chaque fois que des événements pertinents qui modifient les types de données présents dans la section capabilities sont détectés. Les SDK de mesure dans le SDK Runtime (implémentations OMID et MRAID) peuvent associer cet observateur à la session d'UI afin que ces informations puissent leur être envoyées directement. Les partenaires de mesure peuvent combiner des informations obtenues auprès des bibliothèques d'UI avec des données relatives à du contenu déjà disponible (par exemple, lors de l'utilisation de scripts de mesure injectés dans la création publicitaire) afin de générer des événements de visibilité JavaScript.

Flux de contrôle de la visibilité

La bibliothèque cliente suit les modifications apportées à l'UI de l'annonce via des écouteurs d'événements tels que ViewTreeObserver. Chaque fois qu'elle détermine que l'UI de l'annonce a changé d'une manière pouvant affecter la mesure de sa visibilité, la bibliothèque cliente vérifie à quel moment la dernière notification a été envoyée à l'observateur. Si la dernière modification dépasse la valeur de latence autorisée (configurable par le SDK, jusqu'à 200 ms sur mobile), un nouvel objet AdContainerInfo est créé et une notification est envoyée à l'observateur. Ce modèle basé sur les événements est meilleur pour l'intégrité du système que l'interrogation effectuée par la plupart des implémentations OMID sur Android aujourd'hui.

API

Les éléments suivants seront ajoutés à la bibliothèque privacysandbox.ui.core :

• SessionObserver : généralement implémenté par le SDK de mesure et associé à la session renvoyée par le SDK via privacysandbox.ui. Cette interface permettra également au SDK de mesure d'activer certaines catégories de signaux de visibilité. Cela permet à la bibliothèque cliente de l'interface utilisateur de ne collecter que les signaux qui intéressent l'observateur, ce qui est préférable pour l'intégrité générale du système.
• registerObserver() : ajoutée à la classe Session, cette méthode permet à toute personne ayant accès à la session d'enregistrer un observateur. Si l'observateur est enregistré après l'ouverture de la session d'UI, il reçoit immédiatement les AdContainerInfo mis en cache. S'il est enregistré avant l'ouverture de la session, il reçoit les AdContainerInfo à l'ouverture de la session.
• AdContainerInfo : une classe avec des getters qui permet à l'observateur d'obtenir des informations sur le conteneur d'annonces en lecture seule pour les types de données figurant dans la section Fonctionnalités ci-dessus. Les valeurs renvoyées par ces getters correspondront, dans la mesure du possible, aux valeurs parcelables renvoyées par les getters existants dans View et ses sous-classes. Si le conteneur d'annonces a été créé à l'aide de Jetpack Compose, les propriétés sémantiques du conteneur sont exposées. Cette classe peut être utilisée pour calculer des événements MRAID et OMID liés à la visibilité.
• SessionObserverotifyAdContainerChanged() : permet d'informer l'observateur chaque fois que la visibilité change. Elle transmet un objet AdContainerInfo. Cette méthode est appelée chaque fois que des événements affectant les types de données listés dans la section "Fonctionnalités" sont détectés. Remarque : Cette méthode peut être appelée en plus des méthodes sur Session. Par exemple, Session.notifyResized() est appelé pour demander au SDK de redimensionner l'annonce, et SessionObserver.notifyAdContainerChanged() est également appelé dans ce cas.
• SessionObserverotifySessionClosed() : informe l'observateur que la session a été fermée.

Remarque : La durée de vie de SessionObserver est liée à celle de la session. Si la session est fermée, le SessionObserver reçoit un appel notifySessionClosed() et aucune autre méthode ne lui sera envoyée. Étant donné que la session peut être fermée par le SDK du fournisseur d'UI ou lorsque la SandboxedSdkView est dissociée de la fenêtre de l'application de l'éditeur, il est important que le SDK de mesure fasse la distinction entre la session d'UI et la session publicitaire. L'annonce peut être diffusée pour plusieurs sessions. Par exemple, si l'éditeur ne gère pas les rotations de l'appareil, son activité redémarre à chaque rotation de l'appareil. Lorsque l'activité est détruite, la SandboxedSdkView est dissociée de la fenêtre et la session d'UI est fermée. Si l'éditeur enregistre l'adaptateur d'UI lors des redémarrages d'activité, il peut être en mesure de connecter le même adaptateur à une nouvelle SandboxedSdkView et ouvrir une nouvelle session une fois l'activité démarrée. Le partenaire de mesure peut associer un observateur à la nouvelle session et peut choisir de réutiliser l'observateur associé à une session précédente pour assurer la continuité des mesures.

Améliorations futures

Tout code exécuté dans le processus de l'application, y compris le code de la bibliothèque privacysandbox.ui.client, peut être modifié si l'application est compromise. Par conséquent, toute logique de collecte des signaux exécutée dans le processus d'application est susceptible d'être altérée par le code d'application. Cela s'applique également au code du SDK déployé avant la mise à disposition de la Privacy Sandbox qui s'exécute dans le processus de l'application. Par conséquent, la collecte des signaux par la bibliothèque de l'UI n'aggrave pas la situation en matière de sécurité.

De plus, le code du SDK Runtime peut utiliser une API de plate-forme appelée setTrustedPresentationCallback, qui peut lui fournir des garanties renforcées de la part du framework concernant la présentation de l'UI de l'annonce. setTrustedPresentationCallback fonctionne au niveau de la surface et permet d'effectuer des assertions concernant la surface contenant l'UI de l'annonce, en spécifiant des seuils minimaux pour la présentation, tels que le pourcentage de pixels visibles, le temps à l'écran ou l'échelle. Ces données peuvent être comparées aux données de visibilité fournies par la bibliothèque cliente de l'UI, comme expliqué ci-dessus. Comme les données fournies par le framework sont plus fiables, tout événement de la bibliothèque d'interface utilisateur dont les données ne sont pas en accord avec les données du framework peut être supprimé. Par exemple, si l'écouteur fourni à setTrustedPresentationCallback est appelé avec une notification indiquant qu'aucun pixel de l'UI de l'annonce n'est affiché à l'écran, mais que la bibliothèque de l'UI cliente affiche une valeur de pixels affichés à l'écran non nulle, ces dernières données peuvent être supprimées.

Questions ouvertes

Nous vous invitons à nous envoyer vos commentaires sur les points suivants :

1. Quels sont les signaux de visibilité qui vous intéressent et qui ne sont pas mentionnés dans cette explication ?
2. La proposition actuelle consiste à mettre à jour la visibilité au moins toutes les 200 millisecondes, à condition que l'interface utilisateur soit modifiée de façon pertinente. Cette fréquence est-elle acceptable pour vous ? Si ce n'est pas le cas, quelle fréquence préféreriez-vous ?
3. Préférez-vous analyser les informations de setTrustedPresentationCallback vous-même ou que la bibliothèque de l'UI du fournisseur supprime les données de la bibliothèque d'UI cliente lorsqu'elles ne correspondent pas aux données de setTrustedPresentationCallback ?
4. Comment utilisez-vous les signaux de visibilité ? Aidez-nous à comprendre vos cas d'utilisation en répondant à ces questions.