Supporto attività per annunci a schermo intero

SDK Runtime impone delle restrizioni sul modo in cui gli SDK possono avviare nuove attività. Ciò rappresenta una sfida per i formati di annunci a schermo intero che in genere si basano sull'avvio di un'attività separata per un maggiore controllo e un'esperienza utente. Per risolvere questo problema, SDK Runtime introduce un nuovo meccanismo per le attività con 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 per intent, START_SANDBOXED_ACTIVITY.

Anche se gli SDK non possono lanciare intent con questa azione, gli SDK possono richiedere all'app del 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, lanciato come parte dell'attività dell'app client.

Attenzione: l'attività fornita (android.app.Activity) ha un supporto limitato con alcune librerie AndroidX sul lato SDK, in particolare Compose.

Attenzione: il valore Context di questa attività non deve essere utilizzato direttamente dall'SDK. Gli SDK devono utilizzare SandboxedSdkProvider#getContext() per ottenere il contesto appropriato per le loro operazioni.

Creazione di attività in SDK Runtime

Hai due metodi principali per creare attività: utilizzare le librerie attività Jetpack semplificate o interagire direttamente con le API Platform.

Ti consigliamo di utilizzare le librerie attività perché semplificano la creazione delle attività astraendo la complessità di base.

Librerie attività

Le librerie delle attività offrono diversi vantaggi:

• Astrai i dettagli interni per la registrazione dei gestori di attività e la condivisione dei loro identificatori con le app client.
• Offre agli sviluppatori di app un maggiore controllo sul modo in cui gli SDK creano attività all'interno delle loro app, consentendo loro di impostare le condizioni (predicati) da soddisfare.
• Crea un modo unificato per consentire agli SDK di definire le API che avviano le attività.

Esistono tre librerie di attività: core, client e provider.

• La libreria core fornisce le interfacce utilizzate dalle app client e dalle librerie dei provider.
• La libreria provider fornisce le API per gli SDK per avviare le attività.
• La libreria client fornisce le API per le app client per creare un'Avvio attività, che gli SDK possono usare per richiedere alle app di avviare attività.

Queste librerie introducono le seguenti API:

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

Il flusso per avviare le attività con raccolte di attività è il seguente:

1. L'SDK aggiunge un parametro del tipo SdkActivityLauncher a tutte le API che avvieranno le attività.
2. L'app client chiama createSdkActivityLauncher per una delle sue attività per creare un'Avvio app che possa essere passato all'SDK durante le chiamate API.
3. L'SDK chiama SdkSandboxControllerCompat.registerSdkSandboxActivityHandler(SdkSandboxActivityHandlerCompat) e recupera il token dell'identificatore.
4. L'SDK chiama launchSdkActivity per avviare l'attività.

Nota: se l'app client vuole aggiungere una condizione per consentire agli SDK di creare attività, può passare un'espressione del predicato durante la creazione di Avvio app. Se l'app non vuole condizionare la creazione di attività, può fare in modo che il predicato restituisca sempre true.

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

Diagramma di sequenza che mostra il flusso per avviare un'attività utilizzando le librerie attività.

API della piattaforma

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

• SdkSandboxActivityHandler: Il gestore di attività viene utilizzato per inviare una notifica all'SDK quando viene creata un'attività e quando questa viene registrata 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): richiamato dall'app client, questo metodo attiva la creazione di attività per l'SDK. L'app client deve passare come parametri l'attività di avvio scelta e l'identificatore del gestore attività dell'SDK.

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

1. L'SDK registra un gestore di attività utilizzando le API fornite e ottiene un identificatore.
2. L'SDK condivide questo identificatore con la sua app client.
3. 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à di avvio scelta per la nuova attività e l'identificatore del gestore di attività.
4. La piattaforma avvia un'attività e invia una notifica all'SDK tramite un callback nel gestore di attività (SdkSandboxActivityHandler.onActivityCreated(Activity)).
5. L'SDK usa l'attività per completarla con un annuncio.

Nota: onActivityCreated(Activity) viene chiamato tramite Activity.onCreate(Bundle), in questa fase è previsto che la visualizzazione del contenuto venga compilata dagli SDK.

L'utilizzo delle API della piattaforma rende l'SDK responsabile di condividere l'identificatore di SdkSandboxActivityHandler con l'app client tramite le sue API al momento opportuno e guidare 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 del gestore attività (SdkSandboxActivityHandler) con l'app client.

Diagramma di sequenza che mostra il flusso per avviare un'attività utilizzando le API della piattaforma.

Visibilità

In SDK Runtime, gli annunci integrati nella gerarchia delle visualizzazioni dell'app client utilizzano i canali laterali per eseguire il rendering delle visualizzazioni dell'SDK dal processo dell'SDK a quello dell'app client.

L'SDK non può utilizzare le stesse API View che utilizzano 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 nel processo SDK Runtime, eliminando la necessità di canali laterali e consentendo agli SDK di utilizzare le API Android Activity e View standard.

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

Lifecycle

Il ActivityHolder trasmesso 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 le istanze OnBackPressedCallback al fine di gestire la navigazione a ritroso.