API di presentazione dell'interfaccia utente di SDK Runtime

SDK Runtime consente agli SDK per gli annunci di essere eseguiti in un ambiente sandbox, impedendo loro di accedere alla gerarchia delle visualizzazioni di un publisher. Per mostrare gli annunci, la piattaforma espone un'API SandboxedSdkProvider.getView all'SDK per ottenere una visualizzazione dell'annuncio e la raggruppa come SurfacePackage da inviare tramite IPC (comunicazione tra processi) all'applicazione client. Questo approccio presenta diversi svantaggi, che vengono discussi di seguito. Questo documento presenterà quindi una libreria Jetpack proposta che è in fase di creazione per affrontare queste sfide.

Motivazione per l'aumento delle API della piattaforma

Le API del framework sono progettate per la flessibilità e lasciano all'app e all'SDK il compito di creare un canale secondario per la presentazione dell'interfaccia utente. Questo canale secondario esegue le seguenti operazioni:

1. Consente all'SDK di gestire più visualizzazioni di annunci durante il loro ciclo di vita e di comprendere cosa succede all'interfaccia utente dell'annuncio una volta creata dall'SDK.
2. Separa la creazione della visualizzazione dall'associazione dei contenuti. L'utilizzo del canale secondario consente all'SDK di restituire un oggetto che corrisponde alla richiesta di annuncio all'app (i contenuti), che può essere associato al contenitore dell'annuncio ogni volta che l'app lo ritiene opportuno.
3. Astrae i costrutti della piattaforma sottostanti utilizzati per mostrare la UI nei vari processi. (La piattaforma utilizza attualmente un SurfaceControlViewhost e genera un SurfacePackage.)
4. Consente agli SDK per gli annunci in SDK Runtime di ricevere automaticamente notifiche quando cambia l'interfaccia utente del contenitore dell'annuncio. Se un editore modifica il layout del contenitore dell'annuncio, l'SDK non è a conoscenza di queste modifiche, a meno che l'editore non chiami esplicitamente un'API per comunicarle.
5. Sincronizza i ridimensionamenti dell'interfaccia utente dell'annuncio e del contenitore dell'annuncio senza problemi di scattosità visibili all'utente.
6. Gestisce automaticamente la compatibilità con le versioni precedenti. SurfacePackage non è disponibile prima del livello API 30. Inoltre, sui dispositivi in cui non è presente SDK Runtime e l'SDK è locale per il publisher, è uno spreco creare un SurfacePackage per un annuncio quando una visualizzazione può essere ottenuta direttamente dall'SDK. Il canale laterale astrae questa complessità dal codice dell'SDK e dello sviluppatore dell'app.
7. Consente all'UI degli annunci di integrarsi perfettamente con i componenti componibili. Gli sviluppatori di Jetpack Compose che non lavorano con le visualizzazioni possono anche continuare a ospitare l'interfaccia utente generata dallo sviluppatore dell'SDK che lavora ancora con le visualizzazioni.

Librerie UI

Le librerie UI astraggono le complessità descritte sopra e forniscono il canale laterale che l'editore e l'SDK possono utilizzare per mostrare la UI nei processi e mantenerla aggiornata man mano che l'utente interagisce con essa e con il dispositivo.

Esistono tre librerie UI: core, client e provider. La libreria principale fornisce le interfacce utilizzate dalle librerie client e provider. Il fornitore dell'interfaccia utente (in genere l'SDK) dipende dalla libreria del fornitore, mentre il consumer dell'interfaccia utente (in genere l'editore) dipende dalla libreria client. Insieme, le librerie client e provider formano il canale laterale necessario per creare e gestire una sessione UI.

Le API

Le API per la presentazione dell'interfaccia utente di SDK Runtime sono le seguenti:

SandboxedUiAdapter: creato dall'SDK, fornisce un modo per ottenere contenuti da visualizzare nell'interfaccia utente del publisher.

SandboxedSdkView: creato dall'editore, è un contenitore che include i contenuti ottenuti tramite SandboxedUiAdapter.

Session: creato dall'SDK in risposta a SandboxedUiAdapter.openSession(). Rappresenta una sessione della UI. call. Questo modulo costituisce l'estremità SDK del tunnel di comunicazione tra l'SDK e il publisher e riceve notifiche sulle modifiche apportate a SandboxedSdkView, ad esempio distacchi, ridimensionamenti o modifiche alla configurazione della finestra.

SessionClient: creato dalla libreria client, costituisce l'estremità del publisher del tunnel di comunicazione tra l'SDK e il publisher.

SandboxedSdkUiSessionStateChangedListener: creato dall'editore. Un listener per le modifiche allo stato della sessione UI associata a SandboxedSdkView.

Per ulteriori dettagli su queste API, leggi la documentazione di riferimento di privacysandbox-ui.

Flusso di controllo

I seguenti diagrammi mostrano l'interazione tra le librerie dell'interfaccia utente client e provider in vari scenari:

Il diagramma precedente mostra come il publisher può creare un SandboxedSdkView in modo programmatico o tramite il proprio XML e allegarlo a un SdkSandboxUiAdapter ottenuto dall'SDK tramite un'API definita dall'SDK. Per osservare tutte le modifiche dello stato dell'interfaccia utente, il publisher deve aggiungere un SandboxedSdkUiSessionStateChangedListener a SandboxedSdkView prima di collegare SdkSandboxUiAdapter.

Questo diagramma mostra come, se l'attività dell'editore gestisce le modifiche alla configurazione, la libreria client si occupa di inoltrare la modifica della configurazione all'SDK, in modo che possa aggiornare la propria UI di conseguenza. Ad esempio, questo flusso può essere attivato quando l'utente ruota il dispositivo e l'editore dichiara la gestione delle modifiche alla configurazione nella propria attività, impostando android:configChanges=["orientation"].

Questo diagramma illustra come l'SDK può richiedere una modifica del contenitore dell'annuncio utilizzando i metodi su SessionClient. Questa API viene attivata quando l'SDK vuole ridimensionare l'annuncio e ha bisogno che il publisher ridimensioni il contenitore dell'annuncio per adattarlo alle nuove dimensioni. Ciò potrebbe accadere in risposta all'interazione dell'utente, ad esempio mraid.resize().

Questo diagramma mostra come viene chiusa la sessione quando SandboxedSdkView viene staccato dalla finestra. La sessione può essere chiusa in qualsiasi momento (ad es. quando l'utente perde la connettività di rete) dall'SDK richiamando SessionClient.onSessionError().

Ordine Z

La libreria UI client utilizza internamente un SurfaceView per ospitare la UI dell'SDK. SurfaceView può utilizzare l'ordine Z per mostrare la propria UI sopra o sotto la finestra del publisher. Questa operazione è controllata dal metodo SandboxedSdkView.orderProviderUiAboveClientUi(), che accetta un valore booleano setOnTop.

Quando setOnTop è true, ogni android.view.MotionEvent su SandboxedSdkView viene inviato all'SDK. Quando false, questi vengono inviati all'editore. Per impostazione predefinita, gli eventi di movimento vengono inviati all'SDK.

In genere, i publisher non devono modificare l'ordine Z predefinito delle visualizzazioni degli annunci. Tuttavia, quando viene mostrata un'interfaccia utente che copre un annuncio, ad esempio un menu a discesa, l'ordine Z deve essere temporaneamente invertito rispetto a quello predefinito e poi ripristinato quando l'elemento dell'interfaccia utente che copre l'annuncio viene chiuso. Stiamo esplorando modi per automatizzare questo processo nella libreria dell'interfaccia utente client.

Scorrimento

Quando l'interfaccia utente dell'annuncio è ordinata Z sopra la finestra del publisher, MotionEvents dall'interfaccia utente dell'annuncio vengono inviati all'SDK. I gesti di scorrimento e scorrimento rapido avviati nell'interfaccia utente dell'annuncio ricevono un trattamento speciale:

1. Lo scorrimento verticale e i movimenti rapidi vengono inviati e gestiti dal contenitore del publisher. Ciò garantisce una buona esperienza utente quando il contenitore del publisher in cui è posizionata l'interfaccia utente dell'annuncio è scorrevole verticalmente. Non richiede alcun lavoro aggiuntivo da parte dell'SDK o del publisher.
2. I gesti di scorrimento orizzontale e scorrimento rapido vengono inviati e gestiti dall'SDK. In questo modo si ottiene una buona esperienza utente quando l'interfaccia utente dell'annuncio è scorrevole orizzontalmente (ad esempio un carosello di annunci).

Guida all'implementazione

L'SDK deve implementare quanto segue:

• SandboxedUiAdapter: questo valore viene restituito al publisher in risposta a un'API definita dall'SDK, ad esempio loadAd. Il metodo openSession() di questa implementazione deve essere utilizzato per inviare una richiesta di annuncio ai server dell'SDK e preparare una visualizzazione dell'annuncio per questa richiesta.
• Session**: Questo valore viene restituito in risposta alla chiamata SandboxedUiAdapter.openSession. Fornisce un modo per la libreria client di ottenere l'interfaccia utente dell'annuncio e notificare all'SDK le modifiche a questa API. Tutti i metodi Session devono essere implementati qui.

L'editore deve:

1. Crea un SandboxedSdkView tramite XML o in modo programmatico.
2. Allega un SandboxedSdkUiSessionStateChangedListener al SandboxedSdkView per osservare le modifiche alla UI.
3. Collega un SDK fornito da SandboxedUiAdapter a SandboxedSdkView.
4. Aggiungi SandboxedSdkView alla finestra come di consueto e lascia che la libreria client si occupi di creare e gestire la sessione UI con l'SDK.
5. Nei momenti opportuni, reagisci ai cambiamenti di stato segnalati da SandboxedSdkUiSessionChangedListener. Ad esempio, se l'SDK chiude la sessione in modo imprevisto, l'editore può sostituire SandboxedSdkView con un'immagine statica o rimuoverla dalla gerarchia di visualizzazione.
6. Quando esegui transizioni che potrebbero coprire l'interfaccia utente dell'annuncio, ad esempio un menu a discesa, imposta temporaneamente orderProviderUiAboveClientUi su false per posizionare l'interfaccia utente dell'annuncio sotto la finestra del publisher. Una volta chiuso il menu a discesa, chiama orderProviderUiAboveClientUi al numero true.

Il futuro delle API della piattaforma

Una volta che le librerie UI saranno in versione beta, prevediamo di ritirare le API della piattaforma di runtime dell'SDK relative alla presentazione della UI, ovvero SdkSandboxManager.requestSurfacePackage() e SandbxedSdkProvider.getView().

Domande aperte

1. Esistono altri casi d'uso comuni dell'interfaccia utente degli annunci che le librerie UI dovrebbero gestire automaticamente?
2. Quali framework UI utilizzi per mostrare la UI degli annunci? Prevedi problemi di integrazione delle librerie UI con questi framework?
3. L'interfaccia utente dell'annuncio scorrevole inserita in un contenitore editore scorrevole è un caso d'uso comune per te? Qual è la direzione di scorrimento per la UI dell'annuncio e per il contenitore in questo caso? Quale comportamento ti aspetti quando l'utente avvia lo scorrimento nell'interfaccia utente dell'annuncio?