API di presentazione dell'interfaccia utente di SDK Runtime

SDK Runtime consente l'esecuzione degli SDK per gli annunci in un ambiente con sandbox, impedendo loro di eseguire non sarà in grado 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 impacchetta come SurfacePackage da inviare tramite IPC (comunicazione inter-processo) all'applicazione client. Questo contiene diversi alcuni svantaggi, descritti di seguito. Questo documento presenterà una proposta La libreria Jetpack viene creata per affrontare queste sfide.

Motivazione per l'aumento delle API di piattaforma

Le API del framework sono progettate per offrire flessibilità e lasciano il compito di creare un canale laterale dalla presentazione dell'interfaccia utente all'app e all'SDK. Questa parte del canale esegue le seguenti operazioni:

  1. Consente all'SDK di gestire più visualizzazioni dell'annuncio durante il loro ciclo di vita e di capire cosa succede all'interfaccia utente dell'annuncio dopo che è stata creata dall'SDK.
  2. Separa la creazione della visualizzazione e il collegamento dei contenuti. L'uso del canale laterale consente l'SDK per restituire un oggetto che corrisponde alla richiesta di annuncio all'app (i contenuti), che possono essere associati al contenitore degli annunci ogni volta che l'app lo ritiene appropriato.
  3. Astrae i costrutti della piattaforma di base utilizzati per mostrare l'interfaccia utente tra i processi. Attualmente la piattaforma utilizza un SurfaceControlViewhost e genera un SurfacePackage.
  4. Consente agli SDK per gli annunci in SDK Runtime di ricevere automaticamente le notifiche quando cambia l'interfaccia utente del contenitore di annunci. Se un publisher modifica il layout nel contenitore degli annunci, l'SDK non è a conoscenza di queste modifiche, a meno che l'editore chiama esplicitamente un'API per inviarle una notifica.
  5. Sincronizza le ridimensionamenti dell'interfaccia utente dell'annuncio e del contenitore dell'annuncio senza alcun disturbo visibile all'utente.
  6. Gestisce automaticamente la compatibilità con le versioni precedenti. SurfacePackage non è disponibili prima del livello API 30. Inoltre, sui dispositivi in cui non è presente un ambiente di runtime dell'SDK e l'SDK è locale per il processo del publisher, è uno spreco creare un SurfacePackage per un annuncio quando una visualizzazione può essere ottenuta direttamente dall'SDK. Il canale laterale astrae questa complessità dall'SDK e dall'app il codice sviluppatore.
  7. Consente l'integrazione perfetta dell'interfaccia utente dell'annuncio con i Composable. Anche gli sviluppatori di Jetpack Compose che non utilizzano le visualizzazioni possono continuare a ospitare l'interfaccia utente generata dall'autore dell'SDK che continua a utilizzare le visualizzazioni.

Librerie UI

Le librerie dell'interfaccia utente astraggono via le complessità descritte sopra e forniscono canale laterale che il publisher e l'SDK possono utilizzare per mostrare l'UI in tutti i processi. aggiornalo man mano che l'utente interagisce con questo 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. Provider UI (in genere l'SDK) dipende dalla libreria del provider e dal consumer dell'interfaccia utente (in genere l'editore) dipende dalla libreria client. Insieme, il cliente e le librerie dei provider costituiscono il canale laterale necessario per la creazione nella gestione di una sessione della UI.

Le API

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

SandboxedUiAdapter: viene creato dall'SDK per fornire contenuti. da visualizzare nell'interfaccia utente del publisher.

SandboxedSdkView: creato dal publisher, si tratta di un contenitore che contiene contenuti ottenuti tramite SandboxedUiAdapter.

Session: creato dall'SDK in risposta a SandboxedUiAdapter.openSession(). Rappresenta una chiamata alla sessione dell'interfaccia utente. Questo costituisce il lato SDK del tunnel di comunicazione tra l'SDK e il publisher e riceve notifiche relative alle modifiche in SandboxedSdkView, ad esempio scollegamento delle finestre, ridimensionamenti o modifiche alla configurazione.

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

SandboxedSdkUiSessionStateChangedListener: creato dal publisher. R un listener per le modifiche allo stato della sessione UI associata a SandboxedSdkView.

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

Leggi la documentazione di riferimento privacysandbox-ui per ulteriori dettagli su queste API.

Flusso di controllo

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

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

Illustrazione che mostra la procedura di apertura della sessione.
Ottieni l'UI dall'SDK.

Questo diagramma mostra come, se l'attività dell'editore gestisce le modifiche di configurazione, la libreria client si occupa di inoltrare la modifica 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 il publisher dichiara di gestire le modifiche di configurazione nella sua attività impostando android:configChanges=["orientation"].

Modifica dell'interfaccia utente avviata dal publisher.

Questo diagramma illustra in che modo l'SDK può richiedere una modifica nel contenitore dell'annuncio utilizzando metodi su SessionClient. Questa API viene attivata quando l'SDK vuole ridimensionare l'annuncio e deve essere ridimensionato dal publisher per adattarlo al nuovo dimensioni. Ciò potrebbe accadere in risposta all'interazione dell'utente, ad esempio mraid.resize().

Modifica dell'interfaccia utente avviata dall'SDK.

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

Chiusura della sessione dell'interfaccia utente.

Ordine Z

La libreria dell'interfaccia utente client utilizza internamente un SurfaceView per ospitare l'interfaccia utente dell'SDK. SurfaceView può utilizzare l'ordine Z per mostrare la propria UI sopra le o sotto di essa. Questo viene 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 relativi al movimento vengono inviati all'SDK.

In genere, i publisher non devono modificare l'ordine Z predefinito delle visualizzazioni degli annunci. Tuttavia, se mostri un'interfaccia utente che copre un annuncio, come un menu a discesa, la macro L'ordine Z deve essere temporaneamente invertito e ripristinato l'elemento UI di copertura viene ignorato. Stiamo studiando dei modi per automatizzare questo processo nella libreria UI del client.

Scorrimento

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

  1. I gesti di scorrimento verticale e scorrimento vengono inviati e gestiti dal containerizzato. Ciò garantisce una buona UX quando il contenitore del publisher dell'annuncio in cui è posizionata, è possibile scorrere verticalmente. Non è richiesta alcuna operazione aggiuntiva da parte dell'SDK o del publisher.
  2. I gesti di scorrimento e scorrimento orizzontale vengono inviati e gestiti dall'SDK. Questo offre un'esperienza utente positiva quando l'interfaccia utente dell'annuncio è scorrevole orizzontalmente (ad esempio 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, 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 la richiesta.
  • Session**: viene restituito in risposta alla Chiamata SandboxedUiAdapter.openSession. Fornisce un modo per la libreria client di ottenere l'interfaccia utente dell'annuncio e di 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 tramite programmazione.
  2. Collega SandboxedSdkUiSessionStateChangedListener a SandboxedSdkView, per osservare le modifiche nella UI.
  3. Collega un SDK SandboxedUiAdapter fornito a SandboxedSdkView.
  4. Aggiungi SandboxedSdkView alla finestra come di consueto e lascia che la libreria client si occupa di creare e gestire la sessione dell'interfaccia utente con l'SDK.
  5. Reagisci ai cambiamenti nello stato segnalato nei momenti opportuni SandboxedSdkUiSessionChangedListener. Ad esempio, se l'SDK chiude la finestra sessione inaspettatamente, il publisher può sostituire SandboxedSdkView con un 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 orderProviderUiAboveClientUi temporaneamente su false per posizionare l'interfaccia utente dell'annuncio sotto la finestra del publisher. Una volta ignorato il menu a discesa, richiama Da orderProviderUiAboveClientUi a true.

Il futuro delle API di piattaforma

Una volta che le librerie UI saranno diventate beta, pianificheremo di ritirare il runtime dell'SDK le API delle piattaforme relative alla presentazione dell'interfaccia utente, ovvero SdkSandboxManager.requestSurfacePackage() e SandbxedSdkProvider.getView().

Domande aperte

  1. Esistono casi d'uso più comuni dell'UI degli annunci che le librerie UI dovrebbero gestire automaticamente?
  2. Quali framework UI utilizzi per mostrare l'UI degli annunci, prevedi che ci siano problemi con integrare le librerie dell'interfaccia utente con questi framework?
  3. L'interfaccia utente dell'annuncio scorrevole posizionata in un contenitore del publisher scorrevole è un caso d'uso comune per te? Qual è la direzione di scorrimento dell'interfaccia utente dell'annuncio container in questo caso? Quale comportamento ti aspetti quando l'utente avvia una scorrere l'interfaccia utente dell'annuncio?