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 visualizzare gli annunci, la piattaforma espone un'API SandboxedSdkProvider.getView all'SDK per ottenere una visualizzazione dell'annuncio e la pacchettizza come SurfacePackage da inviare tramite IPC (comunicazione tra processi) all'applicazione client. Questo presenta diversi svantaggi, descritti di seguito. Il documento presenterà una proposta di libreria Jetpack che viene creata per risolvere queste sfide.

Motivazione per potenziare le API della piattaforma

Le API framework sono progettate per garantire flessibilità e lasciano il compito di creare un canale laterale tra la presentazione dell'interfaccia utente e l'app e l'SDK. Questo canale secondario svolge le seguenti operazioni:

  1. Consente all'SDK di gestire più visualizzazioni di annunci durante il ciclo di vita e di capire cosa succede all'interfaccia utente dell'annuncio dopo che è stata creata dall'SDK.
  2. Disaccoppia la creazione della visualizzazione e l'associazione dei contenuti. L'utilizzo del canale laterale consente all'SDK di restituire all'app un oggetto che corrisponde alla richiesta di annuncio (i contenuti), che può essere associato al contenitore di annunci ogni volta che l'app lo ritiene appropriato.
  3. Astrae i costrutti della piattaforma sottostanti utilizzati per mostrare l'interfaccia utente nei vari processi. La piattaforma attualmente utilizza un SurfaceControlViewhost e genera un SurfacePackage da questo.
  4. Consente agli SDK per gli annunci in SDK Runtime di ricevere automaticamente notifiche quando l'interfaccia utente del contenitore di annunci cambia. Se un publisher modifica il layout del contenitore di annunci, l'SDK non è a conoscenza di queste modifiche, a meno che il publisher non chiami esplicitamente un'API per inviargli notifica.
  5. Sincronizza i ridimensionamenti dell'interfaccia utente dell'annuncio e del contenitore dell'annuncio senza alcun jank visibile 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 alcun runtime dell'SDK e l'SDK è locale del processo per il publisher, è uno spreco creare un SurfacePackage per un annuncio quando è possibile ottenere una visualizzazione direttamente dall'SDK. Il canale laterale astrae questa complessità lontano dall'SDK e dal codice sviluppatore dell'app.
  7. Consente all'interfaccia utente degli annunci di integrarsi perfettamente con i componibili. Gli sviluppatori di Jetpack Compose che non utilizzano le viste possono anche continuare a ospitare l'UI generata dagli sviluppatori dell'SDK che utilizzano ancora le viste.

Librerie UI

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

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

Le API

Ecco le API per la presentazione dell'interfaccia utente di SDK Runtime:

SandboxedUiAdapter: creata dall'SDK per ottenere contenuti da visualizzare nell'interfaccia utente dell'editore.

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

Session: creata dall'SDK in risposta al SandboxedUiAdapter.openSession(). Rappresenta una sessione UI. chiamata. Costituisce l'estremità dell'SDK del tunnel di comunicazione tra l'SDK e il publisher e riceve notifiche relative alle modifiche apportate al criterio SandboxedSdkView, come scollegamenti delle finestre, ridimensionamenti o modifiche alla configurazione.

SessionClient: creato dalla libreria client, rappresenta la fine del tunnel di comunicazione tra l'SDK e l'editore.

SandboxedSdkUiSessionStateChangedListener: creata dal publisher. Un ascoltatore per le modifiche allo stato della sessione UI associata a SandboxedSdkView.

Illustrazione che mostra le relazioni dell'API di presentazione dell'interfaccia utente di SDK Runtime.
Relazioni tra le API di presentazione dell'interfaccia utente di SDK Runtime.

Per ulteriori dettagli su queste API, leggi la documentazione di riferimento dell'interfaccia utente privacysandbox.

Flusso di controllo

I seguenti diagrammi mostrano l'interazione tra le librerie UI del client e del provider in vari scenari:

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

Illustrazione che mostra il processo di sessione aperta.
Ottieni la UI dall'SDK.

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

Modifica dell'interfaccia utente avviata dal publisher.

Questo diagramma illustra in che modo l'SDK può richiedere una modifica del contenitore di annunci utilizzando i metodi su SessionClient. Questa API viene attivata quando l'SDK vuole ridimensionare l'annuncio e richiede al publisher di ridimensionare il contenitore di annunci per adattarsi alle nuove dimensioni. Questo potrebbe accadere in risposta a un'interazione dell'utente, ad esempio mraid.resize().

Modifica della UI avviata dall'SDK.

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

Chiusura della sessione UI.

Ordine Z

La libreria UI client utilizza internamente un SurfaceView per ospitare l'UI dell'SDK. SurfaceView può utilizzare l'ordine Z per mostrare la propria UI sopra o sotto la finestra del publisher. Ciò è controllato 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, vengono inviati all'editore. Per impostazione predefinita, gli eventi di movimento vengono inviati all'SDK.

In genere i publisher non hanno bisogno di modificare l'ordine Z predefinito delle visualizzazioni di annunci. Tuttavia, quando mostri una UI che copre un annuncio, ad esempio un menu a discesa, l'ordine Z deve essere temporaneamente invertito rispetto all'ordine predefinito e poi ripristinato quando l'elemento UI che copre la UI viene ignorato. Stiamo esplorando dei modi per automatizzare questo processo nella libreria UI client.

Scorrimento

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

  1. I gesti di scorrimento verticale vengono inviati al contenitore dell'editore e gestiti dal contenitore. Ciò fornisce una buona esperienza utente quando il contenitore del publisher in cui è inserita l'interfaccia utente dell'annuncio è scorrevole verticalmente. Ciò non richiede alcun intervento aggiuntivo da parte dell'SDK o del publisher.
  2. I gesti di scorrimento orizzontale e di scorrimento vengono inviati all'SDK e gestiti. Ciò offre una buona esperienza utente quando l'UI stessa degli annunci può scorrere in orizzontale (ad esempio in un carosello di annunci).

Guida all'implementazione

L'SDK deve implementare quanto segue:

  • SandboxedUiAdapter: viene restituito al publisher in risposta a un'API definita dall'SDK, come loadAd. Il metodo openSession() di questa implementazione deve essere usato per effettuare una richiesta di annuncio ai server dell'SDK e preparare una visualizzazione di annuncio per questa richiesta.
  • Session**: viene restituito in risposta alla chiamata SandboxedUiAdapter.openSession. Consente alla libreria client di ottenere l'interfaccia utente degli annunci e di notificare all'SDK le modifiche apportate a questa API. Tutti i metodi Session devono essere implementati qui.

Il publisher deve procedere come segue:

  1. Crea un oggetto SandboxedSdkView tramite XML o in modo programmatico.
  2. Collega un elemento SandboxedSdkUiSessionStateChangedListener a SandboxedSdkView per osservare le modifiche nella UI.
  3. Allega a SandboxedSdkView un SDK fornito (SandboxedUiAdapter).
  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. Al momento opportuno, reagire ai cambiamenti dello stato segnalati da SandboxedSdkUiSessionChangedListener. Ad esempio, se l'SDK chiude la sessione in modo imprevisto, il publisher può sostituire SandboxedSdkView con un'immagine statica o rimuoverla dalla propria gerarchia delle visualizzazioni.
  6. Quando esegui transizioni che potrebbero coprire l'interfaccia utente dell'annuncio, ad esempio un menu a discesa, imposta temporaneamente orderProviderUiAboveClientUi su falso per posizionare l'interfaccia utente sotto la finestra del publisher. Quando il menu a discesa viene ignorato, chiama orderProviderUiAboveClientUi al numero true.

Il futuro delle API delle piattaforme

Una volta che le librerie UI diventeranno beta, ritireremo le API della piattaforma di runtime dell'SDK relative alla presentazione dell'interfaccia utente, ovvero SdkSandboxManager.requestSurfacePackage() e SandbxedSdkProvider.getView().

Domande aperte

  1. Esistono casi d'uso più comuni dell'interfaccia utente che le librerie UI devono gestire automaticamente?
  2. Quali framework dell'interfaccia utente utilizzi per mostrare l'interfaccia utente degli annunci? Prevedi problemi nell'integrazione delle librerie UI con questi framework?
  3. L'UI dell'annuncio scorrevole inserita in un contenitore del publisher scorrevole è un caso d'uso comune? Qual è la direzione di scorrimento per l'interfaccia utente dell'annuncio e il contenitore in questo caso? Quale comportamento ci si aspetta quando l'utente avvia uno scorrimento nell'interfaccia utente dell'annuncio?