Suporte à mediação no SDK Runtime

A mediação é uma maneira comum de as plataformas de publicidade de venda oferecerem gerenciamento de receita. Em um fluxo de trabalho de mediação, o SDK de mediação ("mediador") invoca várias redes de publicidade ("mediado" ou "mediados") para receber o melhor anúncio para um determinado espaço. Em alguns casos, tanto o mediador quanto as redes de publicidade que ele invoca precisam que os SDKs estejam no dispositivo e interajam.

Este documento descreve as principais mudanças nos fluxos de trabalho de mediação no SDK Runtime. Ele abrange os seguintes tópicos:

  • Diferenças entre os fluxos de mediação anteriores e o suporte atual à mediação do SDK Runtime
  • Configurar ações para fluxos de trabalho de mediação no SDK Runtime e nas diferentes etapas de transição
  • Orientações sobre como lidar com cenários em que nem todos os SDKs foram migrados para o Runtime

O suporte para anúncios mediados no SDK Runtime está disponível no AGP 8.5 e nas seguintes versões das bibliotecas do Jetpack do SDK Runtime:

Biblioteca AndroidX Versão
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

Glossário

Os termos a seguir são essenciais para entender a mediação no SDK Runtime:

  • SDK ativado pelo ambiente de execução (RE SDK): um SDK criado para ser executado no ambiente do SDK Runtime e se comunicar com o app por comunicação entre processos (IPC).
  • SDK compatível com o ambiente de execução (RA SDK): um SDK não ativado no ambiente de execução, vinculado ao app de forma estática, que pode conter seu código de SDK atual e um novo código para fazer chamadas ao SDK ativado no ambiente de execução.
  • SDK no app:um SDK que é executado vinculado ao app de forma estática e não tem conhecimento do SDK Runtime. Pode ser uma rede de publicidade que não fez a transição para o SDK Runtime ou um adaptador personalizado de um editor.
  • Mediador:SDK de mediação de anúncios que fornece um serviço de mediação no dispositivo ao interagir com outros SDKs de rede de publicidade.
  • Mediado:SDK de rede de publicidade chamado pelo mediador para fornecer e renderizar um anúncio.
  • Adaptador de mediação:SDKs usados pelo SDK de mediação para fornecer tradução de interface de API e interoperar com vários SDKs de mediadores, geralmente fornecidos pelo mediador. Eles podem ser compatíveis ou não com o tempo de execução.

Fluxos típicos de mediação

Se o SDK precisar oferecer suporte a casos de uso de mediação no SDK Runtime, será necessário implementar algumas mudanças. Esta seção analisa os principais elementos dos fluxos de mediação para que possamos abordar as mudanças necessárias para mediadores e mediandos.

Os fluxos que descrevemos representam uma versão simplificada da mediação no dispositivo com vários SDKs de rede de publicidade e servem como base para a discussão sobre as mudanças necessárias para tornar as jornadas de mediação compatíveis com o SDK Runtime.

Devido à variação nas implementações de fluxo de mediação, vamos nos concentrar nos dois fluxos principais a seguir:

  • Inicialização (incluindo descoberta de redes de publicidade e comunicação)
  • Apresentação da interface do usuário (UI) de anúncios

Inicialização

O seguinte representa uma inicialização padrão, descoberta de rede de publicidade e fluxo de comunicação:

  1. O app cliente inicia o mediador
  2. O mediador descobre e inicializa os mediatees e adaptadores relevantes.
  3. O mediador usa os adaptadores para se comunicar com cada mediado.
  4. O app cliente pede ao mediador para carregar um anúncio.
  5. O app cliente pede ao mediador para mostrar esse anúncio

Apresentação da interface do anúncio

Quando se trata de renderizar o anúncio após a solicitação final na etapa anterior, o fluxo depende do tipo de anúncio:

Anúncios de banner Anúncios de tela cheia Anúncios nativos
O SDK do mediador cria uma visualização de anúncio, que envolve a visualização de anúncio do mediador vencedor.

Ele também pode definir listeners nessa visualização ou atualizar automaticamente o anúncio (usando o mesmo mediador ou um diferente).		 O SDK mediador solicita um anúncio em tela cheia do mediado, que por sua vez inicia uma atividade. O editor gerencia o processamento e a inclusão de visualizações usando componentes retornados pelo SDK do mediador.

Fluxos de mediação no SDK Runtime

O funcionamento da mediação no SDK Runtime varia de acordo com se o mediado está ativado pelo ambiente de execução ou não. Com base nisso, podemos ter os seguintes cenários:

  • O mediador e o mediado estão no SDK Runtime: mediado ativado pelo ambiente de execução
  • O mediador está no SDK Runtime, e o mediado está no app: Mediado no app

RE Mediatee

O diagrama de arquitetura a seguir mostra uma visão geral de alto nível da interação dos SDKs ativados pelo ambiente de execução (RE) e compatíveis com o ambiente de execução (RA) do mediador, dos adaptadores de mediação RE e dos SDKs RE dos mediadores.

Os adaptadores de mediação precisam estar no mesmo processo que o mediado com que estão interagindo. Portanto, eles também precisam migrar para o SDK Runtime.

Diagrama de arquitetura mostrando uma visão geral de alto nível da interação dos SDKs ativados pelo ambiente de execução (RE) e compatíveis com o ambiente de execução (RA) do mediador, dos adaptadores de mediação RE e dos SDKs RE dos mediadores.
Figura 1. Tanto o mediador quanto o mediado são SDKs ativados pelo ambiente de execução.

Inicialização

Ao considerar a inicialização, a descoberta e a comunicação do mediador e do mediatee habilitados para tempo de execução, o fluxo vai seguir estas etapas:

  1. O app (ou o SDK de RA) carrega e inicializa o SDK do mediador usando SdkSandboxManager#loadSdk.
  2. Durante a inicialização, o SDK do mediador carrega e inicializa todos os mediatees necessários no SDK Runtime usando SdkSandboxController#loadSdk.
  3. O SDK RE pode descobrir todos os SDKs carregados no ambiente de execução chamando SdkSandboxController#getSandboxedSdks.
RE - Diagrama de sequência de mediação de RE mostrando o fluxo descrito anteriormente.
Figura 2. Fluxo para inicializar um mediador de RE.

Apresentação da interface do anúncio

A seção a seguir aborda o carregamento de banners e anúncios em tela cheia de um mediador de RE.

Anúncios de banner da RE Mediatee

Quando o app solicita o carregamento de um anúncio de banner, o fluxo para concluir a renderização é o seguinte:

  1. O mediador seleciona o mediado vencedor para esse anúncio.
  2. O mediador recebe um SandboxedUiAdapter do mediado.
  3. O mediador encaminha o UiAdapter para o app.
Fluxo para concluir a renderização de um anúncio de banner na mediação RE-RE.
Figura 3. Fluxo para concluir a renderização de um anúncio de banner de um mediador de RE.

Saiba mais sobre o uso de SandboxedUiAdapter e a biblioteca de interface do SDK Runtime.

Sobreposições em anúncios de banner

Se os mediadores quiserem adicionar uma sobreposição ao anúncio, eles precisarão modificar o fluxo da seguinte maneira:

  1. O mediador cria um layout com a sobreposição e um SandboxedSdkView.
  2. O mediador seleciona o mediado vencedor para esse anúncio.
  3. O mediador recebe um SandboxedUiAdapter do mediado.
  4. O mediador define o UiAdapter do mediado como SandboxedSdkView.
  5. O mediador compartilha a visualização preenchida com o app.
Fluxo para sobrepor uma visualização a um anúncio de banner obtido de um RE Mediatee.
Fluxo para sobrepor uma visualização a um anúncio de banner obtido de um RE Mediatee.
RE: anúncios de tela cheia da Mediatee

Quando o app solicita o carregamento de um anúncio em tela cheia, o fluxo segue estas etapas:

  1. O app (ou o SDK do RA) transmite um SdkActivityLauncher ao mediador com a solicitação para carregar um anúncio.
    1. O cliente pode restringir a criação de atividades usando um predicado.
  2. O mediador seleciona o mediado vencedor para esse anúncio.
  3. O mediador pede que o mediado carregue um anúncio, transmitindo o SdkActivityLauncher do app.
  4. O mediador registra um manipulador de atividades e recebe um token de identificador para a atividade registrada.
  5. O mediador usa o SdkActivityLauncher para solicitar o início de uma atividade usando esse token.
  6. Se o predicado do app cliente permitir, o SDK Runtime vai iniciar essa atividade no processo dedicado.
Fluxo para mostrar um app mediado em tela cheia de um RE Mediatee.
Figura 4. Diagrama de fluxo que ilustra como carregar um anúncio de tela cheia mediado de um RE Mediatee.

Saiba mais sobre o suporte à atividade para anúncios em tela cheia no SDK Runtime.

Mediatee no app

O diagrama de arquitetura a seguir mostra uma visão geral de alto nível da interação dos SDKs RE e RA do mediador, dos adaptadores de mediação que não conhecem o SDK Runtime e dos SDKs dos mediatees vinculados estaticamente ao app (também sem reconhecimento do ambiente de execução).

Diagrama de arquitetura que mostra uma visão geral de alto nível da interação dos SDKs RE e RA do mediador, dos adaptadores de mediação que não conhecem o SDK Runtime e dos SDKs dos mediadores vinculados estaticamente ao app (também sem reconhecimento do ambiente de execução).
Figura 5. O mediatee é vinculado estaticamente ao app, mesmo que esteja ciente do SDK RE.

Inicialização

Como nesse cenário os mediatees são vinculados de forma estática ao app e ainda não foram migrados para o SDK Runtime, o SDK ativado pelo ambiente de execução do mediador precisa ter um processo para registrá-los.

Esse registro precisa estar acessível usando a API do mediador, mas os detalhes da implementação ficam a critério de cada mediador. Chamamos essa API de MediationSandboxedSdk#registerInAppMediatee.

Ao considerar a inicialização, a descoberta e a comunicação de um SDK mediador RE e SDKs mediados no app, o fluxo segue estas etapas:

  1. O app carrega e inicializa o SDK compatível com o tempo de execução do mediador.
  2. SDK de RA do mediador:
    1. Inicializa o SDK do RE do mediador usando SdkSandboxManager#loadSdk.
    2. Inicializa todos os SDKs de mediação no app.
    3. Descobre e registra os SDKs de mediadores no app usando a API fornecida pelo SDK do RE, MediationSandboxedSdk#registerInAppMediate.

Além de ter todos os SDKs de mediação no app registrados, o SDK RE do mediador pode descobrir todos os SDKs carregados no SDK Runtime usando SdkSandboxController#getSandboxedSdks.

Sequência que ilustra o fluxo descrito para inicializar um mediador in-app.
Figura 6. Observação: usamos a API do mediador sugerido para registrar a referência aos mediadores no app.

Apresentação da interface do anúncio

A seção a seguir aborda o carregamento de banners e anúncios em tela cheia de um mediador no app.

Anúncios de banner de mediador no app

Quando o app solicita o carregamento de um anúncio de banner, o fluxo para concluir a renderização é o seguinte:

  1. O SDK compatível com o ambiente de execução do mediador encaminha a solicitação do app para o SDK ativado pelo ambiente de execução.
  2. O SDK de RE do mediador seleciona o mediado relevante.
  3. O SDK RE do mediador recupera a referência ao mediado e solicita o carregamento de um anúncio pelo SDK RA.
  4. O SDK do RA recebe uma visualização do mediador no app.
  5. O SDK de RA cria um SandboxedUiAdapter para a visualização recebida.
  6. O SDK RA encaminha o UiAdapter para o SDK RE.
  7. O SDK RE encaminha o UiAdapter para o app.
Fluxo para concluir a renderização de anúncios de banner de um mediador no app
Figura 7. O mediador não pode sobrepor visualizações sobre V1 ao obtê-lo de um mediador no app.
Anúncios de tela cheia mediados no app

Quando o app solicita o carregamento de um anúncio em tela cheia, o fluxo segue estas etapas:

  1. O app transmite um SdkActivityLauncher ao SDK de RA do mediador com a solicitação para carregar um anúncio.
    1. O cliente pode restringir a criação de atividades usando um predicado.
  2. O SDK RA do mediador encaminha a solicitação do app para o SDK RE.
  3. SDK de RE do mediador:
    1. Seleciona o mediado relevante.
    2. Recupera a referência ao mediador no app.
    3. Solicitações para carregar um anúncio pelo SDK do RA.
  4. O SDK do RA pede que o mediador carregue um anúncio.
  5. O mediado inicia a atividade diretamente. O predicado do app não será respeitado.
Fluxo de carregamento de anúncios em tela cheia quando o mediador está no processo do app.
Figura 8. O predicado será ignorado pelo mediador no app.

Interagir e compartilhar feedback

O Sandbox de privacidade no Android é um projeto em andamento, e este documento reflete o design atual dele. Seu feedback é essencial para continuarmos desenvolvendo e aprimorando os recursos. Envie um bug para dar feedback.