Supporto della mediazione in SDK Runtime

La mediazione è un modo comune per le piattaforme pubblicitarie lato vendite di offrire la gestione del rendimento. In un flusso di lavoro di mediazione, l'SDK di mediazione ("mediatore") richiama più reti pubblicitarie ("mediatee" o "mediatees") per ottenere l'annuncio migliore per un determinato spazio. In alcuni casi, sia il mediatore sia le reti pubblicitarie che richiama richiedono che i relativi SDK siano presenti sul dispositivo e interagiscano.

Questo documento illustra le modifiche principali ai flussi di lavoro di mediazione nell'ambiente di runtime SDK. Gli argomenti trattati sono i seguenti:

  • Differenze tra i flussi di mediazione precedenti e il supporto della mediazione in fase di runtime dell'SDK attuale
  • Azioni di configurazione per i flussi di lavoro di mediazione nel runtime dell'SDK e le diverse fasi di transizione
  • Indicazioni su come gestire gli scenari in cui non è stata eseguita la migrazione di tutti gli SDK al runtime

Il supporto per gli annunci indiretti in SDK Runtime è disponibile a partire da AGP 8.5 e dalle seguenti versioni delle librerie Jetpack di SDK Runtime:

Raccolta Androidx Versione
androidx.privacysandbox.activity 1.0.0-alpha01
androidx.privacysandbox.sdkruntime 1.0.0-alpha13
androidx.privacysandbox.tools 1.0.0-alpha08
androidx.privacysandbox.ui 1.0.0-alpha09

Glossario

I seguenti termini sono fondamentali per comprendere la mediazione nel runtime dell'SDK:

  • SDK abilitato per il runtime (RE SDK): un SDK progettato per essere eseguito nell'ambiente SDK Runtime e comunicare con l'app tramite la comunicazione interprocesso (IPC).
  • SDK consapevole del runtime (RA SDK): un SDK non abilitato per il runtime, collegato all'app staticamente, che può contenere il codice SDK esistente e nuovo codice da chiamare nell'SDK abilitato per il runtime.
  • SDK in-app:un SDK che viene eseguito collegato all'app in modo statico e non è consapevole di SDK Runtime. Potrebbe trattarsi di una rete pubblicitaria che non ha eseguito la transizione all'ambiente di runtime dell'SDK o di un adattatore personalizzato di un publisher.
  • Mediatore:SDK di mediazione degli annunci che fornisce un servizio di mediazione on-device interagisce con altri SDK di reti pubblicitarie.
  • Mediatee:SDK della rete pubblicitaria chiamato dal Mediatore per fornire e eseguire il rendering di un annuncio.
  • Adattatore di mediazione:SDK utilizzati dall'SDK Mediator per fornire la traduzione dell'interfaccia API al fine di interoperare con vari SDK mediatee, in genere forniti dal mediatore. Possono essere a conoscenza del runtime o non a conoscenza del runtime.

Flussi di mediazione tipici

Se il tuo SDK deve supportare i casi d'uso della mediazione nel runtime dell'SDK, dovrai implementare alcune modifiche. Questa sezione esamina gli elementi chiave dei flussi di mediazione per consentirci di affrontare le modifiche richieste per i mediatori e i soggetti mediati.

I flussi descritti rappresentano una versione semplificata della mediazione on-device con più SDK di reti pubblicitarie e servono da base per la discussione sulle modifiche necessarie per rendere i percorsi di mediazione compatibili con il runtime dell'SDK.

Data la variabilità delle implementazioni dei flussi di mediazione, ci concentriamo sui seguenti due flussi principali:

  • Inizializzazione (inclusa la rilevamento delle reti pubblicitarie e la comunicazione)
  • Presentazione dell'interfaccia utente (UI) dell'annuncio

Inizializzazione

Di seguito è riportato un flusso di comunicazione, di inizializzazione e di scoperta della rete pubblicitaria standard:

  1. L'app client avvia il mediatore
  2. Il mediatore rileva e inizializza gli oggetti mediatee e gli adattatori pertinenti
  3. Il mediatore utilizza i propri adattatori per comunicare con ogni mediato
  4. L'app client richiede al mediatore di caricare un annuncio
  5. L'app client richiede al mediatore di mostrare questo annuncio

Presentazione dell'interfaccia utente dell'annuncio

Per quanto riguarda il rendering dell'annuncio dopo la richiesta finale nel passaggio precedente, il flusso dipende dal tipo di annuncio:

Annunci banner Annunci a schermo intero Annunci nativi
L'SDK Mediatore crea una visualizzazione annuncio che racchiude la visualizzazione annuncio del Mediatoe vincente.

Potrebbe anche impostare gli ascoltatori in questa visualizzazione o aggiornare automaticamente l'annuncio (utilizzando lo stesso intermediario o un altro).		 L'SDK del mediatore richiede un annuncio a schermo intero al mediatee, che a sua volta avvia un'attività. Il publisher gestisce la gestione e l'inflazione delle visualizzazioni utilizzando i componenti restituiti dall'SDK mediatore.

Flussi di mediazione in SDK Runtime

Il funzionamento della mediazione all'interno del runtime dell'SDK è diverso a seconda che il mediatee sia abilitato per il runtime o meno. In base a questo, possiamo avere i seguenti scenari:

  • Sia il mediatore che il mediatee si trovano in SDK Runtime: RE mediatee
  • Il mediatore si trova in SDK Runtime e il mediato è in-app: Mediato in-app

RE Mediatee

Il seguente diagramma di architettura mostra una panoramica generale dell'interazione degli SDK RE (runtime-enabled) e RA (runtime-aware) del mediatore, degli adattatori di mediazione RE e degli SDK RE dei mediatee.

Gli adattatori di mediazione devono trovarsi nello stesso processo del Mediatee con cui interagiscono, pertanto dovranno eseguire la migrazione anche al runtime dell'SDK.

Diagramma dell'architettura che mostra una panoramica generale dell'interazione degli SDK abilitati per il runtime (RE) e attenti al runtime (RA) del mediatore, degli adattatori di mediazione RE e degli SDK RE dei mediati.
Figura 1. Sia il mediatore che il mediato sono SDK RE.

Inizializzazione

Se prendiamo in considerazione l'inizializzazione, il rilevamento e la comunicazione sia del mediatore sia del mediato abilitato per il runtime, il flusso seguirà questi passaggi:

  1. L'app (o l'SDK RA) carica e inizializza l'SDK Mediator utilizzando SdkSandboxManager#loadSdk.
  2. Durante l'inizializzazione, l'SDK mediatore carica e inizializza eventuali mediatori richiesti in SDK Runtime utilizzando SdkSandboxController#loadSdk.
  3. L'SDK RE può rilevare tutti gli SDK caricati nel runtime chiamando SdkSandboxController#getSandboxedSdks.
Diagramma di sequenza della mediazione RE - RE che mostra il flusso descritto in precedenza.
Figura 2. Flusso per inizializzare un mediato RE.

Presentazione dell'interfaccia utente dell'annuncio

La sezione seguente illustra il caricamento di banner e annunci a schermo intero da un intermediario RE.

Annunci banner RE Mediatee

Data una richiesta da parte dell'app di caricare un annuncio banner, il flusso per completare il rendering è il seguente:

  1. Il mediatore seleziona il mediatee vincente per questo annuncio.
  2. Il mediatore ottiene un SandboxedUiAdapter dalla persona mediata.
  3. Il mediatore inoltra UiAdapter all'app.
Procedura per completare il rendering di un annuncio banner nella mediazione RE-RE.
Figura 3. Flusso per completare il rendering di un annuncio banner da un mediato RE.

Scopri di più sull'utilizzo di SandboxedUiAdapter e della libreria SDK Runtime UI.

Overlay per gli annunci banner

Se i mediatori vogliono aggiungere un overlay all'annuncio, devono modificare il flusso come segue:

  1. Il mediatore crea un layout con il relativo overlay e un SandboxedSdkView.
  2. Il mediatore seleziona il mediatee vincente per questo annuncio.
  3. Il mediatore ottiene un SandboxedUiAdapter dal mediatee.
  4. Il mediatore imposta il valore UiAdapter del mediatee su SandboxedSdkView.
  5. Il mediatore condivide la vista compilata con l'app.
Flusso per sovrapporre una visualizzazione su un annuncio banner ottenuto da un Mediatee RE.
Flusso per sovrapporre una visualizzazione su un annuncio banner ottenuto da un Mediatore RE.
Informazioni sugli annunci a schermo intero di Mediatee

Quando l'app richiede di caricare un annuncio a schermo intero, il flusso segue questi passaggi:

  1. L'app (o l'SDK RA) passa un SdkActivityLauncher al mediatore con la richiesta di caricare un annuncio.
    1. Il client può limitare la creazione di attività utilizzando un predicato.
  2. Il mediatore seleziona il mediatee vincente per questo annuncio.
  3. Il mediatore richiede al mediatee di caricare un annuncio, passando il SdkActivityLauncher dall'app.
  4. Il mediatee registra un gestore delle attività e riceve un token di identificatore per l'attività registrata.
  5. Il mediatee utilizza il valore SdkActivityLauncher per richiedere l'avvio di un'attività utilizzando questo token.
  6. Se il predicato dell'app client lo consente, SDK Runtime avvierà questa attività nel processo dedicato.
Flusso per visualizzare un'app a schermo intero mediata da un Mediatee RE.
Figura 4. Diagramma di flusso che illustra come caricare un annuncio a schermo intero mediato da un Mediatee RE.

Scopri di più sul supporto dell'attività per gli annunci a schermo intero in SDK Runtime.

Mediatee in-app

Il seguente diagramma di architettura mostra una panoramica generale dell'interazione degli SDK RE e RA del mediatore, degli adattatori di mediazione ignari dell'ambiente di runtime dell'SDK e degli SDK dei mediati collegati in modo statico all'app (anche ignari dell'ambiente di runtime).

Diagramma dell'architettura che mostra una panoramica generale dell'interazione degli SDK RE e RA del mediatore, degli adattatori di mediazione che non sono a conoscenza dell'ambiente di runtime dell'SDK e degli SDK dei mediati collegati in modo statico all'app (anche non a conoscenza dell'ambiente di runtime).
Figura 5. Il mediatee è collegato in modo statico all'app, anche se è a conoscenza dell'SDK RE.

Inizializzazione

Poiché in questo scenario i mediatori sono collegati in modo statico all'app e non è ancora stata eseguita la migrazione a SDK Runtime, l'SDK abilitato per il runtime del mediatore dovrebbe avere un processo per registrarli.

Questa registrazione dovrebbe essere accessibile utilizzando l'API del mediatore, ma i dettagli di implementazione sono a discrezione di ciascun mediatore. Chiamiamo questa API MediationSandboxedSdk#registerInAppMediatee.

Quando si considera l'inizializzazione, il rilevamento e la comunicazione di un SDK mediatore RE e di SDK mediatee in-app, il flusso segue questi passaggi:

  1. L'app carica e inizializza l'SDK del mediatore consapevole del runtime.
  2. L'SDK RA del mediatore:
    1. Inizializza l'SDK RE del mediatore utilizzando SdkSandboxManager#loadSdk.
    2. Inizializza tutti gli SDK mediatee in-app.
    3. Individua e registra gli SDK mediatee in-app utilizzando l'API fornita dall'SDK RE, MediationSandboxedSdk#registerInAppMediate.

Oltre ad avere registrato tutti gli SDK mediatee in-app, l'SDK RE del mediatore può rilevare tutti gli SDK caricati in SDK Runtime utilizzando SdkSandboxController#getSandboxedSdks.

Sequenza che illustra il flusso descritto per inizializzare un Mediatee in-app.
Figura 6. Tieni presente che utilizziamo l'API del mediatore suggerito per registrare il riferimento ai mediatori in-app.

Presentazione dell'interfaccia utente dell'annuncio

La sezione seguente illustra il caricamento di banner e annunci a schermo intero da un mediate in-app.

Annunci banner mediatee in-app

Data una richiesta da parte dell'app di caricare un annuncio banner, il flusso per completare il rendering è il seguente:

  1. L'SDK del mediatore che è consapevole del runtime inoltra la richiesta dell'app al suo SDK supportato dal runtime.
  2. L'SDK RE del mediatore seleziona il mediatee pertinente.
  3. L'SDK RE del mediatore recupera il riferimento al mediato e richiede di caricare un annuncio tramite l'SDK RA.
  4. L'SDK RA ottiene una vista dal mediatee in-app.
  5. L'SDK RA crea un SandboxedUiAdapter per la visualizzazione ricevuta.
  6. L'SDK RA inoltra il UiAdapter all'SDK RE.
  7. L'SDK RE inoltra il UiAdapter all'app.
Flusso per completare il rendering degli annunci banner da un mediatore in-app
Figura 7. Tieni presente che il mediatore non deve sovrapporre le visualizzazioni alla V1 quando la ottiene da un mediato in-app.
Annunci a schermo intero mediatee in-app

In seguito a una richiesta dell'app di caricare un annuncio a schermo intero, il flusso segue questi passaggi:

  1. L'app passa un SdkActivityLauncher all'SDK RA del mediatore con la richiesta di caricare un annuncio.
    1. Il client può limitare la creazione di attività utilizzando un predicato.
  2. L'SDK RA del mediatore inoltra la richiesta dell'app al proprio SDK RE.
  3. L'SDK RE del mediatore:
    1. Consente di selezionare il mediatore pertinente.
    2. Recupera il riferimento al mediato in-app.
    3. Richieste di caricamento di un annuncio tramite l'SDK RA.
  4. L'SDK RA richiede al mediatee di caricare un annuncio.
  5. Il mediatore avvia direttamente l'attività. Il predicato dell'app non verrà rispettato.
Flusso di caricamento degli annunci a schermo intero quando il mediato è nel processo dell'app.
Figura 8. Il predicato verrà ignorato dal mediatee in-app.

Coinvolgere e condividere feedback

Privacy Sandbox su Android è un progetto in corso e questo documento riflette il suo design attuale. Il tuo feedback è fondamentale per noi perché ci consente di sviluppare e migliorare le funzionalità di questo strumento. Segnala un bug per fornire un feedback.