Proposta di progettazione della visibilità di SDK Runtime

Gli SDK per gli annunci in SDK Runtime non sono in grado di accedere alla gerarchia delle visualizzazioni di un publisher. Gli SDK nel runtime hanno invece le proprie visualizzazioni. L'SDK non può utilizzare le stesse API View usate al di fuori del runtime dell'SDK per determinare se l'annuncio è visibile all'utente perché la visualizzazione dell'annuncio non è collegata alla finestra dell'applicazione. Sono incluse le API View di Android, come getLocationOnScreen, getLocationInWindow o getVisibility, che non restituiscono i valori previsti.

Supportare la misurazione della visibilità degli annunci è un requisito fondamentale di SDK Runtime. Questa proposta di progettazione è finalizzata a supportare il supporto di Open Measurement e servizi di misurazione simili. Le soluzioni trattate qui potrebbero essere applicabili anche alle API Attribution Reporting. Ti invitiamo a fornirci i tuoi feedback su questa proposta.

Funzionalità

Questo design ha lo scopo di supportare gli SDK per gli annunci o i partner di misurazione per il calcolo dei seguenti dati sulla visibilità (i nomi sono provvisori e soggetti a modifica):

Illustrazione che mostra come i componenti della visibilità di SDK Runtime interagiscono tra loro
Panoramica della visibilità di SDK Runtime.
  • viewport [Rect]: rappresenta la geometria dello schermo del dispositivo o della finestra dell'app, a seconda delle funzionalità della piattaforma.
  • uiContainerGeometry [Rect]: la geometria del campo SandboxedSdkView sottoposto a rendering.
  • alpha [float]: l'opacità della colonna SandboxedSdkView visualizzata.
  • onScreenGeometry [Rect]: il sottoinsieme di uiContainerGeometry, che non è tagliato dalle viste principali, fino al viewport incluso).
  • occludedGeometry [Rect]: le parti di onScreenGeometry occulte da qualsiasi vista nella gerarchia dell'applicazione. Include un valore Rect per ogni occlusione, corrispondente a zero, a una o più visualizzazioni di app che si intersecano con SandboxedSdkView onScreenGeometry

Requisiti

  • I valori di uiContainerGeometry, onScreenGeometry e occludedGeometry vengono espressi nello spazio delle coordinate di viewport.
  • I report sulle variazioni della visibilità avvengono con una latenza minima.
  • La visibilità è misurabile per l'intero ciclo di vita della visualizzazione dell'annuncio, dalla sua prima apparizione all'ultima.

Proposta di design

Questa proposta si basa sul funzionamento della presentazione UI utilizzando le librerie UI del client e del provider. Estenderemo le librerie UI per consentire all'SDK di registrare uno o più osservatori della sessione UI. L'osservatore riceverà informazioni sulla visibilità ogni volta che vengono rilevati eventi pertinenti che modificano i tipi di dati nella sezione delle capabilities. Gli SDK di misurazione nel runtime dell'SDK (implementazioni OMID e MRAID) possono collegare questo osservatore alla sessione dell'interfaccia utente, in modo che le informazioni possano essere inviate direttamente. I partner di misurazione possono combinare le informazioni ottenute dalle librerie UI con i dati sui contenuti già disponibili (ad esempio, quando si utilizzano script di misurazione inseriti nella creatività dell'annuncio) per generare eventi di visibilità JavaScript.

Flusso di controllo per la visibilità.
Controllo del flusso per la visibilità.

La libreria client rimane in ascolto delle modifiche nell'interfaccia utente degli annunci tramite listener di eventi come ViewTreeObserver. Ogni volta che stabilisce che la UI dell'annuncio è cambiata in un modo che potrebbe influire sulla misurazione della visibilità, la libreria client controlla quando è stata inviata l'ultima notifica all'osservatore. Se l'ultimo aggiornamento è superiore alla latenza consentita (configurabile dall'SDK, fino a un minimo di 200 ms sui dispositivi mobili), viene creato un nuovo oggetto AdContainerInfo e viene inviata una notifica all'osservatore. Questo modello basato sugli eventi è migliore per l'integrità del sistema rispetto al polling eseguito attualmente dalla maggior parte delle implementazioni OMID su Android.

API

I seguenti elementi verranno aggiunti alla libreria privacysandbox.ui.core:

  • SessionObserver: viene generalmente implementata dall'SDK di misurazione, collegata alla sessione restituita dall'SDK tramite privacysandbox.ui. Questa interfaccia consentirà inoltre all'SDK di misurazione di attivare determinate categorie di indicatori di visibilità. Questo a sua volta consente alla libreria client dell'interfaccia utente di raccogliere solo gli indicatori a cui l'osservatore è interessato, il che è migliore per l'integrità del sistema in generale.
  • registerObserver(): aggiunto alla classe Session, questo metodo consente a chiunque abbia accesso alla sessione di registrare un osservatore. Se l'osservatore si registra dopo l'apertura della sessione UI, riceverà subito la cache AdContainerInfo. Se registrati prima dell'apertura della sessione, verranno inviati AdContainerInfo all'apertura della sessione.
  • AdContainerInfo: una classe con getter che consente all'osservatore di ottenere informazioni sui container di annunci di sola lettura per i tipi di dati elencati nella sezione Funzionalità in alto. I valori restituiti da questi getter corrisponderanno, se possibile, ai valori di restituzione parcelable dei getter esistenti in View e nelle sue sottoclassi. Se il contenitore di annunci è stato creato utilizzando Jetpack Compose, questo espone le proprietà semantiche del container. Questa classe può essere utilizzata per calcolare eventi MRAID e OMID relativi alla visibilità.
  • SessionObserverotifyAdContainerChanged(): utilizzata per avvisare l'osservatore ogni volta che la visibilità cambia. Passa un oggetto AdContainerInfo. Questa chiamata viene richiamata ogni volta che vengono rilevati eventi che interessano i tipi di dati elencati nella sezione Funzionalità. Nota: questo metodo può essere chiamato in aggiunta ai metodi su sessione. Ad esempio, Session.notifyResized() viene chiamato per richiedere all'SDK il ridimensionamento dell'annuncio e anche SessionObserver.notifyAdContainerChanged() viene chiamato in questo caso.
  • SessionObserverotifySessionClosed(): informa l'osservatore che la sessione è stata chiusa.

Miglioramenti futuri

Qualsiasi codice in esecuzione nel processo dell'applicazione, incluso il codice della libreria privacysandbox.ui.client, può essere modificato se l'applicazione viene compromessa. Pertanto, qualsiasi logica di raccolta degli indicatori eseguita nel processo dell'applicazione è soggetta a manomissioni da parte del codice dell'applicazione. Questo vale anche per il codice SDK di cui è stato eseguito il deployment prima della disponibilità di Privacy Sandbox in esecuzione nel processo di applicazione. Di conseguenza, la raccolta di indicatori da parte della libreria UI non aggrava la situazione di sicurezza.

Inoltre, il codice nel runtime dell'SDK può utilizzare un'API della piattaforma denominata setTrustedPresentationCallback in grado di offrire garanzie più efficaci derivanti dal framework sulla presentazione dell'interfaccia utente dell'annuncio. setTrustedPresentationCallback funziona a livello di superficie e può contribuire ad asserzioni sulla superficie contenente l'interfaccia utente dell'annuncio specificando soglie minime per la presentazione, come la percentuale di pixel visibili, il tempo sullo schermo o la scala. Questi dati possono essere verificati in base ai dati sulla visibilità forniti dalla libreria client dell'interfaccia utente, come spiegato in precedenza. Poiché i dati forniti dal framework sono più affidabili, è possibile ignorare gli eventi della libreria UI i cui dati non sono in accordo con i dati del framework. Ad esempio, se il listener fornito a setTrustedPresentationCallback viene richiamato con una notifica che indica che sullo schermo non sono visualizzati pixel dell'interfaccia utente dell'annuncio e la libreria dell'interfaccia utente del client mostra un numero di pixel diverso da zero, i dati di quest'ultimo possono essere eliminati.

Domande aperte

Invitiamo l'utente a ricevere feedback sui seguenti punti:

  1. Quali sono gli indicatori di visibilità che ti interessano e che non sono menzionati in questo video esplicativo?
  2. L'attuale proposta è di aggiornare la visibilità ogni 200 millisecondi, a condizione che ci sia una modifica pertinente nell'interfaccia utente. Trovi questa frequenza? In caso contrario, quale frequenza preferiresti?
  3. Preferisci analizzare le informazioni di setTrustedPresentationCallback stesso o che la libreria UI del provider elimini i dati dalla libreria dell'interfaccia utente del client quando non corrispondono ai dati di setTrustedPresentationCallback?
  4. Come puoi fruire degli indicatori di visibilità? Aiutaci a comprendere i tuoi casi d'uso inviando un feedback che risponda a queste domande.