Il runtime SDK impone limitazioni su come 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 un'esperienza utente migliorata. Per risolvere il problema, 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 file manifest o avviare le proprie attività.
Viene invece introdotta una nuova azione di intent, START_SANDBOXED_ACTIVITY
.
Anche gli SDK non possono avviare intent con questa azione, ma possono chiedere all'app client di avviare questo intent. Il sistema crea quindi un'attività definita dalla piattaforma e la passa all'SDK. Questa attività verrà eseguita nello stesso processo dell'SDK.
L'SDK può quindi utilizzare questa attività per implementare e gestire l'esperienza pubblicitaria a schermo intero.
L'attività fornita dalla piattaforma è un android.app.Activity
standard, avviato nell'ambito dell'attività dell'app client.
Creazione di attività nell'ambiente di runtime dell'SDK
Esistono due metodi principali per creare attività: utilizzare le librerie Activity semplificate di Jetpack o interagire direttamente con le API di piattaforma.
Ti consigliamo di utilizzare le librerie di attività perché semplificano la creazione delle attività astraendo la complessità sottostante.
Librerie di attività
Le librerie di attività offrono diversi vantaggi:
- Astrae i dettagli interni della registrazione degli handler delle attività e della condivisione dei relativi identificatori con le app client.
- Offre agli sviluppatori di app un maggiore controllo su come gli SDK creano attività all'interno delle loro app consentendo loro di impostare condizioni (predicati) da soddisfare.
- Creare un modo unificato per consentire agli SDK di definire API che lanciano attività.
Esistono tre librerie di attività: core, client e provider.
- La libreria core fornisce le interfacce utilizzate dalle app client e dalle librerie del provider.
- La libreria provider fornisce API per consentire agli SDK di lanciare attività.
- La libreria client fornisce API per le app client per creare un programma di avvio delle attività, che gli SDK possono utilizzare per richiedere alle app di avviare le attività.
Queste librerie introducono le seguenti API:
SdkActivityLauncher
: il programma di lancio delle attività consente agli SDK di gestire il lancio delle attività dall'app client. Le app client devono creare un programma di lancio 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 lancio delle attività con le librerie di attività è il seguente:
- L'SDK aggiunge un parametro di tipo
SdkActivityLauncher
a tutte le API che avviano attività. - L'app client chiama
createSdkActivityLauncher
in una delle sue attività per creare un programma di avvio che può essere passato all'SDK durante le chiamate API. - L'SDK chiama
SdkSandboxControllerCompat.registerSdkSandboxActivityHandler(SdkSandboxActivityHandlerCompat)
e recupera il token di identificatore. - L'SDK chiama
launchSdkActivity
per avviare l'attività.
Il seguente diagramma mostra il flusso in caso di utilizzo delle librerie di attività.
API di piattaforma
La piattaforma introduce le seguenti API per facilitare la creazione e la gestione delle attività in sandbox all'interno di SDK Runtime:
SdkSandboxActivityHandler
: l'Activity Handler viene utilizzato per notificare all'SDK la creazione di un'attività e viene registrato dall'SDK.- Per facilitare la registrazione degli Activity Handler, l'SDK può utilizzare i seguenti metodi in
SdkSandboxController
:.registerSdkSandboxActivityHandler(SdkSandboxActivityHandler)
: registra un'istanza diSdkSandboxActivityHandler
, che restituisce un identificatoreIBinder
..unregisterSdkSandboxActivityHandler(SdkSandboxActivityHandler)
: annulla la registrazione di un'istanza registrata diSdkSandboxActivityHandler
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 dell'attività di gestione dell'SDK.
Per avviare un'attività utilizzando le API di piattaforma, gli SDK devono seguire questo flusso:
- L'SDK registra un gestore delle 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à nell'ambiente di runtime dell'SDK con l'API della piattaforma
startSdkSandboxActivity(Activity, IBinder)
, passando come parametri l'attività iniziale scelta per questa nuova attività e l'identificatore dell'handler dell'attività. - La piattaforma avvia un'attività e invia una notifica all'SDK tramite un callback nell'Activity Handler (
SdkSandboxActivityHandler.onActivityCreated(Activity)
). - L'SDK utilizza l'attività per compilarla con un annuncio.
L'utilizzo delle API di piattaforma rende l'SDK responsabile della condivisione dell'identificatore di SdkSandboxActivityHandler con l'app client tramite le sue API in un momento opportuno e di fornire alle app client indicazioni su come utilizzarlo.
Nel seguente diagramma di flusso, l'SDK di esempio ha un metodo launchActivity(AppCallback)
che prevede un callback (definito nell'ambito dell'API dell'SDK). Questo callback viene utilizzato dall'SDK per condividere l'identificatore dell'attività Handler (SdkSandboxActivityHandler
) con l'app client.
Visibilità
In SDK Runtime, gli annunci integrati nella gerarchia delle visualizzazioni dell'app client utilizzano canali aside 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 utilizzate 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 laterali e consentendo agli SDK di utilizzare le API Activity
e View
Android standard.
A causa di queste diverse implementazioni, il nostro obiettivo è unificare le interfacce per recuperare gli indicatori di visibilità indipendentemente dal contesto di caricamento dell'annuncio.
Lifecycle
Il valore
ActivityHolder
trasmesso all'SDK tramite
SdkSandboxActivityHandlerCompat.onActivityCreated(ActivityHolder)
implementa
LifecycleOwner
e può essere utilizzato per conoscere il valore
Lifecycle.Event
.
Navigazione a ritroso
Il metodo
ActivityHolder.getOnBackPressedDispatcher()
restituisce
OnBackPressedDispatcher
che può essere utilizzato per registrare
OnBackPressedCallback
istanze per gestire la navigazione a ritroso.