Supporto attività per annunci a schermo intero

Nota: Privacy Sandbox su Android è un progetto in corso e questo documento riflette la sua progettazione attuale. Il tuo feedback è fondamentale per noi perché ci aiuta a sviluppare e migliorare le funzionalità di questo strumento.

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.

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

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

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:

1. L'SDK aggiunge un parametro di tipo SdkActivityLauncher a tutte le API che avviano attività.
2. 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.
3. L'SDK chiama SdkSandboxControllerCompat.registerSdkSandboxActivityHandler(SdkSandboxActivityHandlerCompat) e recupera il token di 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 di predicato durante la creazione del programma di avvio. 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 di avvio di un'attività utilizzando le 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 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 dell'attività di gestione dell'SDK.

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

1. L'SDK registra un gestore delle 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à 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à.
4. La piattaforma avvia un'attività e invia una notifica all'SDK tramite un callback nell'Activity Handler (SdkSandboxActivityHandler.onActivityCreated(Activity)).
5. L'SDK utilizza l'attività per compilarla con un annuncio.

Nota: onActivityCreated(Activity) viene chiamato tramite Activity.onCreate(Bundle), in questa fase gli SDK dovrebbero compilare la visualizzazione dei contenuti.

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.

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

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.