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 che utilizza 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. Ciò include le API View di Android come getLocationOnScreen, getLocationInWindow o getVisibility, che non restituiscono i valori previsti.

Il supporto della misurazione della visibilità degli annunci è un requisito fondamentale di SDK Runtime. Questa proposta di progettazione mira a ottenere il supporto per Open Measurement e servizi di misurazione simili. Le soluzioni discusse qui potrebbero essere applicabili anche alle API Attribution Reporting.

Funzionalità

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

Illustrazione che mostra l'interoperabilità dei componenti della visibilità di SDK Runtime — 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 di SandboxedSdkView in fase di rendering.
alpha [float]: l'opacità di SandboxedSdkView in fase di rendering.
onScreenGeometry [Rect]: il sottoinsieme di uiContainerGeometry che non viene ritagliato dalle visualizzazioni principali, fino a viewport incluso.
occludedGeometry [Rect]: le parti di onScreenGeometry che sono ostruite da qualsiasi visualizzazione nella gerarchia dell'applicazione. Include un Rect per ogni occlusione, corrispondente a zero, una o più visualizzazioni di app che si intersecano con SandboxedSdkView onScreenGeometry

Requisiti

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

Proposta di progettazione

Questa proposta si basa sul funzionamento della presentazione della UI utilizzando le librerie UI client e 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 Funzionalità. Gli SDK di misurazione nell'SDK runtime (implementazioni OMID e MRAID) possono collegare questo osservatore alla sessione UI, in modo che queste 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 utilizzano script di misurazione inseriti nella creatività dell'annuncio) per generare eventi di visibilità JavaScript.

La libreria client ascolta le modifiche nell'interfaccia utente dell'annuncio tramite listener di eventi come ViewTreeObserver. Ogni volta che rileva che l'interfaccia utente 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 è maggiore della latenza consentita (configurabile dall'SDK, fino a un minimo di 200 ms su dispositivo mobile), 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 dalla maggior parte delle implementazioni OMID su Android oggi.

API

Alla libreria privacysandbox.ui.core verranno aggiunti i seguenti elementi:

SessionObserver: in genere implementato dall'SDK per la misurazione, allegato alla sessione restituita dall'SDK tramite privacysandbox.ui. Questa interfaccia consentirà inoltre all'SDK di misurazione di attivare determinate categorie di indicatori di visibilità. Ciò consente alla libreria client UI di raccogliere solo gli indicatori a cui è interessato l'osservatore, il che è meglio per la salute generale del sistema.
registerObserver(): aggiunto alla classe Session, questo metodo consente a chiunque abbia accesso alla sessione di registrare un osservatore. Se l'osservatore viene registrato dopo l'apertura della sessione dell'interfaccia utente, gli verrà inviato immediatamente il valore AdContainerInfo memorizzato nella cache. Se registrati prima dell'apertura della sessione, riceveranno AdContainerInfo all'apertura della sessione.
AdContainerInfo: una classe con metodi getter che consente all'osservatore di ottenere informazioni sul contenitore dell'annuncio di sola lettura per i tipi di dati elencati nella sezione Funzionalità precedente. I valori restituiti da questi getter corrisponderanno, ove possibile, ai valori restituiti serializzabili dai getter esistenti su View e sulle relative sottoclassi. Se il contenitore dell'annuncio è stato creato utilizzando Jetpack Compose, vengono esposte le proprietà semantiche del contenitore. Questa classe può essere utilizzata per calcolare gli eventi MRAID e OMID relativi alla visibilità.
SessionObserverotifyAdContainerChanged(): utilizzato per inviare una notifica all'osservatore ogni volta che la visibilità cambia. Passa un oggetto AdContainerInfo. Viene chiamato ogni volta che vengono rilevati eventi che influiscono sui tipi di dati elencati nella sezione Funzionalità. Nota: questo metodo potrebbe essere chiamato in aggiunta ai metodi in Session. Ad esempio, Session.notifyResized() viene chiamato per richiedere all'SDK di ridimensionare l'annuncio e SessionObserver.notifyAdContainerChanged() viene chiamato anche quando ciò accade.
SessionObserverotifySessionClosed(): notifica all'osservatore che la sessione è stata chiusa.

Nota: la durata del SessionObserver è legata a quella della sessione. Se la sessione viene chiusa, SessionObserver riceverà una chiamata notifySessionClosed() e non gli verranno inviati altri metodi. Poiché la sessione può essere chiusa dall'SDK del fornitore dell'interfaccia utente o quando SandboxedSdkView viene separato dalla finestra dell'app publisher, è importante che l'SDK di misurazione distingua tra la sessione dell'interfaccia utente e la sessione dell'annuncio. Potrebbero esserci più sessioni per cui viene mostrato l'annuncio. Ad esempio, se l'editore non gestisce le rotazioni del dispositivo, la sua attività verrà riavviata ogni volta che il dispositivo ruota. Quando l'attività viene eliminata, SandboxedSdkView viene staccato dalla finestra e la sessione UI viene chiusa. Se il publisher salva l'adattatore UI tra i riavvii dell'attività, potrebbe essere in grado di collegare lo stesso adattatore a un nuovo SandboxedSdkView e aprire una nuova sessione dopo l'avvio dell'attività. Il partner di misurazione potrà allegare un osservatore alla nuova sessione e potrebbe scegliere di riutilizzare l'osservatore allegato a una sessione precedente per garantire la continuità della misurazione.

Miglioramenti futuri

Qualsiasi codice in esecuzione nella procedura di applicazione, incluso il codice della libreria privacysandbox.ui.client, può essere modificato se l'applicazione è compromessa. Pertanto, qualsiasi logica di raccolta dei segnali eseguita nel processo dell'applicazione è soggetta a manomissione da parte del codice dell'applicazione. Ciò vale anche per il codice SDK implementato prima della disponibilità di Privacy Sandbox che viene eseguito nel processo dell'applicazione. Di conseguenza, la raccolta di indicatori da parte della libreria UI non peggiora la situazione di sicurezza.

Inoltre, il codice nell'SDK Runtime può utilizzare un'API della piattaforma chiamata setTrustedPresentationCallback che può fornire garanzie più solide dal framework sulla presentazione della UI dell'annuncio. setTrustedPresentationCallback funziona a livello di superficie e può contribuire a fare asserzioni sulla superficie contenente l'interfaccia utente dell'annuncio specificando soglie minime per la presentazione, ad esempio la percentuale di pixel visibili, il tempo sullo schermo o la scala. Questi dati possono essere controllati rispetto ai dati di visibilità forniti dalla libreria client UI, spiegati in precedenza. Poiché i dati forniti dal framework sono più affidabili, tutti gli eventi della libreria UI i cui dati non corrispondono a quelli del framework possono essere eliminati. Ad esempio, se il listener fornito a setTrustedPresentationCallback viene richiamato con una notifica che indica che sullo schermo non vengono visualizzati pixel dell'interfaccia utente dell'annuncio e la libreria UI client mostra un numero di pixel diverso da zero sullo schermo, i dati di quest'ultima possono essere eliminati.

Domande aperte

Quali indicatori di visibilità ti interessano e non sono menzionati in questa spiegazione?
L'attuale proposta prevede l'aggiornamento della visibilità almeno ogni 200 millisecondi, a condizione che si verifichi una modifica pertinente nell'interfaccia utente. Questa frequenza è accettabile per te? In caso contrario, con quale frequenza preferiresti riceverli?
Preferisci analizzare le informazioni di setTrustedPresentationCallback o che la libreria UI del fornitore elimini i dati dalla libreria UI client quando non corrispondono ai dati di setTrustedPresentationCallback?
Come vengono utilizzati gli indicatori di visibilità? Aiutaci a comprendere i tuoi casi d'uso inviando un feedback che risponda a queste domande.