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 "mediatee") per ottenere l'annuncio migliore per un determinato slot. In alcuni casi, sia il mediatore sia le reti pubblicitarie che richiama devono avere i propri SDK sul dispositivo e interagire.

Questo documento descrive le modifiche chiave ai flussi di lavoro di mediazione in SDK Runtime. Gli argomenti trattati sono i seguenti:

  • Differenze tra i flussi di mediazione precedenti e il supporto della mediazione SDK Runtime attuale
  • Configura le azioni per i flussi di lavoro di mediazione in SDK Runtime e le diverse fasi di transizione
  • Indicazioni su come gestire gli scenari in cui non tutti gli SDK sono stati migrati al runtime

Il supporto degli annunci con mediazione in SDK Runtime è disponibile a partire da AGP 8.5 e dalle seguenti versioni delle librerie Jetpack di SDK Runtime:

Libreria 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 in SDK Runtime:

  • SDK abilitato per il runtime (RE SDK): un SDK creato per essere eseguito nell'ambiente SDK Runtime e comunicare con l'app tramite la comunicazione interprocesso (IPC).
  • SDK runtime-aware (RA SDK): un SDK non abilitato per il runtime, collegato staticamente all'app, che può contenere il codice SDK esistente e il nuovo codice per chiamare l'SDK abilitato per il runtime.
  • SDK in-app: un SDK che viene eseguito in modo statico collegato all'app e non ha alcuna conoscenza di SDK Runtime. Potrebbe trattarsi di un network pubblicitario che non è stato migrato a SDK Runtime o di un adattatore personalizzato di un publisher.
  • Mediatore:SDK di mediazione degli annunci che fornisce un servizio di mediazione sul dispositivo interagendo con altri SDK di reti pubblicitarie.
  • Mediatore:SDK della rete pubblicitaria chiamato dal mediatore per fornire e visualizzare un annuncio.
  • Adattatore di mediazione:SDK utilizzati dall'SDK di mediazione per fornire la traduzione dell'interfaccia API per interagire con vari SDK di mediazione, di solito forniti dal mediatore. Questi possono essere runtime-aware o runtime-unaware.

Flussi di mediazione tipici

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

I flussi che descriviamo rappresentano una versione semplificata della mediazione on-device con più SDK di reti pubblicitarie e fungono da base per la discussione sulle modifiche necessarie per rendere i percorsi di mediazione compatibili con l'SDK Runtime.

Data la variazione nelle implementazioni del flusso di mediazione, ci concentriamo sui seguenti due flussi principali:

  • Inizializzazione (inclusa la scoperta delle reti pubblicitarie e la comunicazione)
  • Presentazione dell'interfaccia utente (UI) degli annunci

Inizializzazione

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

  1. L'app client avvia il mediatore
  2. Il mediatore rileva e inizializza i mediati e gli adattatori pertinenti
  3. Il mediatore utilizza i propri adattatori per comunicare con ogni mediatore
  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 l'ultima richiesta del passaggio precedente, il flusso dipende dal tipo di annuncio:

Annunci banner Annunci a schermo intero Annunci nativi
L'SDK di mediazione crea una visualizzazione annuncio, che racchiude la visualizzazione annuncio del mediatore vincente.

Potrebbe anche impostare listener su questa visualizzazione o aggiornare automaticamente l'annuncio (utilizzando lo stesso o un diverso mediatee).		 L'SDK mediatore richiede un annuncio a schermo intero al mediatore, che a sua volta avvia un'attività. Il publisher gestisce la gestione e l'espansione delle visualizzazioni utilizzando i componenti restituiti dall'SDK di mediazione.

Flussi di mediazione in SDK Runtime

Il funzionamento della mediazione all'interno di SDK Runtime varia a seconda che l'SDK di mediazione sia abilitato per il runtime o meno. In base a questo, possiamo avere i seguenti scenari:

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

RE Mediatee

Il seguente diagramma dell'architettura mostra una panoramica di alto livello dell'interazione degli SDK abilitati per l'esecuzione (RE) e consapevoli dell'esecuzione (RA) del mediatore, degli adattatori di mediazione RE e degli SDK RE dei mediatee.

Gli adattatori di mediazione devono trovarsi nello stesso processo della mediazione con cui interagiscono, quindi dovranno anche eseguire la migrazione a SDK Runtime.

Diagramma dell'architettura che mostra una panoramica di alto livello dell'interazione degli SDK runtime-enabled (RE) e runtime-aware (RA) del mediatore, degli adattatori di mediazione RE e degli SDK RE dei mediatee.
Figura 1. Sia il mediatore che il mediato sono SDK RE.

Inizializzazione

Quando si considera l'inizializzazione, l'individuazione e la comunicazione sia del mediatore sia del mediatee abilitati all'runtime, il flusso seguirà questi passaggi:

  1. L'app (o l'SDK RA) carica e inizializza l'SDK mediatore utilizzando SdkSandboxManager#loadSdk.
  2. Durante l'inizializzazione, l'SDK di mediazione carica e inizializza tutti i mediatee richiesti in SDK Runtime utilizzando SdkSandboxController#loadSdk.
  3. RE SDK può rilevare tutti gli SDK caricati nel runtime chiamando SdkSandboxController#getSandboxedSdks.
RE - RE mediation sequence diagram showing the flow described previously.
Figura 2. Flusso per inizializzare un mediatore RE.

Presentazione dell'interfaccia utente dell'annuncio

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

RE Mediatee banner ads

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

  1. Il mediatore seleziona il mediatore vincente per questo annuncio.
  2. Il mediatore ottiene un SandboxedUiAdapter dalla persona che ha richiesto la mediazione.
  3. Il mediatore inoltra UiAdapter all'app.
Flusso 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 mediatore RE.

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

Overlay per gli annunci banner

Se i mediatori vogliono aggiungere una sovrapposizione all'annuncio, devono modificare il flusso nel seguente modo:

  1. Il mediatore crea un layout con la relativa sovrapposizione e un SandboxedSdkView.
  2. Il mediatore seleziona il mediatore vincente per questo annuncio.
  3. Il mediatore ottiene un SandboxedUiAdapter dalla persona che ha richiesto la mediazione.
  4. Il mediatore imposta UiAdapter del mediatore su SandboxedSdkView.
  5. Il mediatore condivide la visualizzazione compilata con l'app.
Flusso per sovrapporre una visualizzazione a un annuncio banner ottenuto da un RE Mediatee.
Flusso per sovrapporre una visualizzazione a un annuncio banner ottenuto da un RE Mediatee.
RE: Annunci a schermo intero Mediatee

Data una richiesta dell'app 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 mediatore vincente per questo annuncio.
  3. Il mediatore chiede al mediatore di caricare un annuncio, passando il SdkActivityLauncher dall'app.
  4. Il mediatee registra un gestore di attività e ottiene un token identificatore per l'attività registrata.
  5. Il mediatore utilizza SdkActivityLauncher per richiedere di avviare un'attività utilizzando questo token.
  6. Se il predicato dell'app client lo consente, l'SDK Runtime avvierà questa attività nel processo dedicato.
Flusso per visualizzare un'app a schermo intero con mediazione da un mediatore RE.
Figura 4. Diagramma di flusso che illustra come caricare un annuncio a schermo intero con mediazione da un RE Mediatee.

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

Mediatee in-app

Il seguente diagramma dell'architettura mostra una panoramica generale dell'interazione degli SDK RE e RA del mediatore, degli adattatori di mediazione che non conoscono l'SDK Runtime e degli SDK dei mediatee collegati staticamente all'app (anch'essi non compatibili con il runtime).

Diagramma dell'architettura che mostra una panoramica di alto livello dell'interazione degli SDK RE e RA del mediatore, degli adattatori di mediazione che non conoscono SDK Runtime e degli SDK dei mediatee collegati staticamente all'app (anch'essi non compatibili con SDK Runtime).
Figura 5. Il mediatore è collegato staticamente all'app, anche se è a conoscenza dell'SDK RE.

Inizializzazione

Poiché in questo scenario le mediazioni sono collegate staticamente all'app e non sono ancora state migrate a SDK Runtime, l'SDK abilitato per l'runtime del mediatore deve avere una procedura per registrarle.

Questa registrazione deve essere accessibile tramite l'API del mediatore, ma i dettagli di implementazione sono lasciati alla discrezione di ciascun mediatore. Chiamiamo questa API MediationSandboxedSdk#registerInAppMediatee.

Quando si considera l'inizializzazione, l'individuazione e la comunicazione di un SDK mediatore RE e degli SDK mediatore in-app, il flusso seguirà questi passaggi:

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

Oltre ad avere tutti gli SDK mediatore in-app registrati, 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 mediatore 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 una mediazione in-app.

Annunci banner di mediazione in-app

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

  1. L'SDK runtime-aware dell'intermediario inoltra la richiesta dell'app al suo SDK abilitato per il runtime.
  2. L'SDK RE dell'intermediario seleziona il mediatore pertinente.
  3. L'SDK RE del mediatore recupera il riferimento al mediatee e richiede di caricare un annuncio tramite l'SDK RA.
  4. L'SDK RA ottiene una visualizzazione dalla mediazione in-app.
  5. L'SDK RA crea un SandboxedUiAdapter per la visualizzazione ricevuta.
  6. L'SDK RA inoltra UiAdapter all'SDK RE.
  7. L'SDK RE inoltra l'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 versione 1 quando le ottiene da un mediatore in-app.
Annunci a schermo intero di mediazione in-app

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

  1. L'app trasmette 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 dell'intermediario inoltra la richiesta dell'app al proprio SDK RE.
  3. SDK RE del mediatore:
    1. Seleziona il mediatore pertinente.
    2. Recupera il riferimento al mediatore in-app.
    3. Richieste di caricamento di un annuncio tramite l'SDK RA.
  4. L'SDK RA richiede al mediatore di caricare un annuncio.
  5. La persona che ha richiesto la mediazione inizia l'attività direttamente. Il predicato dell'app non verrà rispettato.
Flusso di caricamento degli annunci a schermo intero quando il mediatore si trova nel processo dell'app.
Figura 8. Il predicato verrà ignorato dal mediatore in-app.

Partecipare e condividere feedback

Privacy Sandbox su Android è un progetto in corso e questo documento riflette il suo design attuale. Il tuo feedback è fondamentale per continuare a sviluppare e migliorare le sue funzionalità. Segnala un bug per fornire feedback.