Supporto attività per annunci a schermo intero

L'SDK Runtime impone limitazioni al modo in cui gli SDK possono avviare nuove attività. Ciò rappresenta una sfida per i formati degli annunci a schermo intero che in genere si basano sull'avvio di un'attività separata per un maggiore controllo e una migliore esperienza utente. Per risolvere questo problema, l'SDK Runtime introduce un nuovo meccanismo per le attività in sandbox.

Gli SDK caricati nell'ambiente SDK Runtime non possono definire direttamente i tag <activity> nel proprio manifest né avviare le proprie attività. Viene invece introdotta una nuova azione di intent, START_SANDBOXED_ACTIVITY.

Sebbene anche gli SDK non possano avviare intent con questa azione, possono richiedere all'app client di avviare questo intent. Il sistema crea quindi un'attività definita dalla piattaforma e la trasmette all'SDK. Questa attività verrà eseguita nello stesso processo dell'SDK.

L'SDK può quindi utilizzare questa attività per implementare e gestire l'esperienza dell'annuncio a schermo intero.

L'attività fornita dalla piattaforma è un intent standard android.app.Activity, avviato nell'ambito dell'attività dell'app client.

Creazione di attività in SDK Runtime

Esistono due metodi principali per creare attività: utilizzare le librerie Activity Jetpack semplificate o interagire direttamente con le API della piattaforma.

Ti consigliamo di utilizzare le librerie di attività, in quanto semplificano la creazione di attività astraendo la complessità sottostante.

Librerie di attività

Le librerie di attività offrono diversi vantaggi:

Astrai i dettagli interni della registrazione dei gestori di attività e della condivisione dei relativi identificatori con le app client.
Consente agli sviluppatori di app di avere un maggiore controllo su come gli SDK creano attività all'interno delle loro app, consentendo loro di impostare le condizioni (predicati) da soddisfare.
Crea un modo unificato per gli SDK di definire le API che avviano le attività.

Esistono tre librerie di attività: principale, client e fornitore.

La libreria core fornisce le interfacce utilizzate dalle app client e dalle librerie del fornitore.
La libreria provider fornisce API per gli SDK per avviare attività.
La libreria client fornisce API per le app client per creare un launcher di attività, che gli SDK possono utilizzare per richiedere alle app di avviare attività.

Queste librerie introducono le seguenti API:

SdkActivityLauncher: l'avvio attività consente agli SDK di gestire l'avvio di attività dall'app client. Le app client devono creare un launcher e passarlo come parametro alle API dell'SDK che avviano le attività.
<T : Activity & LifecycleOwner> T.createSdkActivityLauncher(() -> Boolean ): Una funzione di estensione che l'app client può chiamare dalle sue attività per creare Avvio app.
SdkActivityLauncher.launchSdkActivity(IBinder): un metodo utilizzato dall'SDK per richiedere all'app di avviare attività.

Il flusso di avvio delle attività con le librerie di attività è il seguente:

L'SDK aggiunge un parametro di tipo SdkActivityLauncher a qualsiasi API che avvierà attività.
L'app client chiama createSdkActivityLauncher su una delle sue attività per creare un launcher che può essere passato all'SDK nelle chiamate API.
L'SDK chiama SdkSandboxControllerCompat.registerSdkSandboxActivityHandler(SdkSandboxActivityHandlerCompat) e recupera il token identificatore.
L'SDK chiama launchSdkActivity per avviare l'attività.

Il seguente diagramma mostra il flusso in caso di utilizzo delle librerie di attività.

Diagramma di sequenza della libreria di attività — Diagramma di sequenza che mostra il flusso di avvio di un'attività utilizzando le librerie di attività.

API della piattaforma

La piattaforma introduce le seguenti API per facilitare la creazione e la gestione di attività in sandbox all'interno di SDK Runtime:

SdkSandboxActivityHandler: L'Activity Handler viene utilizzato per comunicare all'SDK quando viene creata un'attività e viene registrato dall'SDK.
Per facilitare la registrazione dei gestori di attività, l'SDK può utilizzare i seguenti metodi in SdkSandboxController:
- .registerSdkSandboxActivityHandler(SdkSandboxActivityHandler): Registra un'istanza di SdkSandboxActivityHandler, che restituisce un identificatore IBinder.
- .unregisterSdkSandboxActivityHandler(SdkSandboxActivityHandler): Annulla la registrazione di un'istanza registrata di SdkSandboxActivityHandler utilizzando il relativo identificatore.
SdkSandboxManager.startSdkSandboxActivity(Activity, IBinder): Chiamato dall'app client, questo metodo attiva la creazione di attività per l'SDK. L'app client deve passare come parametri l'attività iniziale scelta e l'identificatore del gestore attività dell'SDK.

Per avviare un'attività utilizzando le API della piattaforma, gli SDK devono seguire questo flusso:

L'SDK registra un gestore di attività utilizzando le API fornite e ottiene un identificatore.
L'SDK condivide questo identificatore con la sua app client.
L'app client chiama il metodo per avviare un'attività in SDK Runtime con l'API della piattaforma startSdkSandboxActivity(Activity, IBinder), passando come parametri l'attività iniziale scelta per questa nuova attività e l'identificatore dell'handler di attività.
La piattaforma avvia un'attività e invia una notifica all'SDK tramite un callback nel gestore delle attività (SdkSandboxActivityHandler.onActivityCreated(Activity)).
L'SDK utilizza l'attività per riempirla con un annuncio.

L'utilizzo delle API della piattaforma rende l'SDK responsabile della condivisione dell'identificatore di SdkSandboxActivityHandler con l'app client tramite le sue API al momento opportuno e guida le app client su come utilizzarlo.

Nel seguente diagramma di flusso, l'SDK di esempio ha un metodo launchActivity(AppCallback) che prevede un callback (definito come parte dell'API dell'SDK). Questo callback viene utilizzato dall'SDK per condividere l'identificatore dell'Activity Handler (SdkSandboxActivityHandler) con l'app client.

Diagramma di sequenza delle API della piattaforma — Diagramma di sequenza che mostra il flusso di avvio di un'attività utilizzando le API della piattaforma.

Visibilità

All'interno di SDK Runtime, gli annunci integrati nella gerarchia di visualizzazione dell'app client utilizzano canali laterali per eseguire il rendering delle visualizzazioni dell'SDK dal processo dell'SDK al processo dell'app client.

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 (visibilità).

Al contrario, l'attività fornita dalla piattaforma viene eseguita in modo nativo all'interno del processo SDK Runtime, eliminando la necessità di canali secondari e consentendo agli SDK di utilizzare le API standard di Android Activity e View.

A causa di queste diverse implementazioni, gli sforzi in corso mirano a unificare le interfacce per recuperare gli indicatori di visibilità indipendentemente dal contesto di caricamento degli annunci.

Lifecycle

ActivityHolder passato all'SDK tramite SdkSandboxActivityHandlerCompat.onActivityCreated(ActivityHolder) implementa LifecycleOwner e può essere utilizzato per conoscere Lifecycle.Event.

Navigazione a ritroso

Il metodo ActivityHolder.getOnBackPressedDispatcher() restituisce OnBackPressedDispatcher che può essere utilizzato per registrare istanze OnBackPressedCallback per gestire la navigazione indietro.