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 ("mediator") invoca várias redes de publicidade ("mediatee" ou "mediatees") para receber o melhor anúncio para um determinado slot. Em alguns casos, a mediação e as redes de publicidade que ela 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 à mediação do SDK para ambiente de execução atual
• Configurar ações para fluxos de trabalho de mediação no SDK Runtime e os diferentes estágios de transição
• Orientações sobre como lidar com cenários em que nem todos os SDKs foram migrados para o ambiente de execução

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

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 interprocesso (IPC).
• SDK ciente do ambiente de execução (SDK RA): um SDK que não é ativado no momento de execução, vinculado ao app de forma estática, que pode conter o código do SDK atual e um novo código para chamar o SDK ativado no momento de execução.
• SDK no app:um SDK que é executado vinculado ao app de forma estática e não reconhece o SDK Runtime. Pode ser uma rede de publicidade que não fez a transição para o SDK Runtime ou um adaptador personalizado do editor.
• Mediador:SDK de mediação de anúncios que fornece um serviço de mediação no dispositivo interagendo com outros SDKs de rede de publicidade.
• Mediatee:SDK da rede de publicidade que é chamado pelo mediador para fornecer e renderizar um anúncio.
• Adaptador de mediação:SDKs usados pelo SDK Mediator para fornecer a tradução da interface da API e interagir com vários SDKs de mediação, geralmente fornecidos pelo mediador. Eles podem ser conscientes ou não do tempo de execução.

Fluxos de mediação típicos

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 mediados.

Os fluxos descritos 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.

Dada a variação nas implementações do fluxo de mediação, focamos nos seguintes dois fluxos principais:

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

Inicialização

O exemplo a seguir 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 mediadores e adaptadores relevantes.
3. O mediador usa os adaptadores para se comunicar com cada mediado
4. O app cliente solicita que o mediador carregue um anúncio
5. O app cliente solicita que o mediador mostre esse anúncio

Observação: este fluxo pressupõe que o app cliente tenha uma dependência do SDK do mediador, dos SDKs dos mediadores e dos adaptadores de mediação, e que ele seja criado com eles.

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 de mediação cria uma visualização de anúncio, que envolve a visualização de anúncio do mediador vencedor. Também é possível definir listeners nessa visualização ou atualizar automaticamente o anúncio (usando o mesmo ou um mediador diferente).	O SDK do mediador solicita um anúncio em tela cheia do mediador, que inicia uma atividade.	O editor gerencia o processamento e o inflamento da visualização usando componentes retornados pelo SDK do mediador.

Fluxos de mediação no SDK Runtime

A forma como a mediação funciona no SDK Runtime é diferente dependendo se o mediado está ou não ativado pelo ambiente de execução. Com base nisso, podemos ter os seguintes cenários:

• O mediador e o mediado estão no SDK Runtime: RE mediado
• 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 com suporte e ativados pelo ambiente de execução (RE) do mediador, os adaptadores de mediação RE e os 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.

Figura 1. O mediador e o mediado são SDKs de RE.

Inicialização

Ao considerar a inicialização, descoberta e comunicação do mediador e do mediado habilitados para execução, o fluxo seguirá estas etapas:

1. O app (ou o SDK do 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 mediadores 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.

Figura 2. Fluxo para inicializar uma mediatee de RE.

Observação: use as classes *Compat Runtime Manager e Controller para garantir que o SDK ativado pelo ambiente de execução seja compatível com versões anteriores.

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 mediatee RE.

Anúncios de banner da RE Mediatee

Considerando uma solicitação do app para carregar um anúncio de banner, o fluxo para renderizar completamente é o seguinte:

1. O mediador seleciona o mediador vencedor para esse anúncio.
2. O mediador recebe um SandboxedUiAdapter do mediado.
3. O mediador encaminha o UiAdapter para o app.

Figura 3. Fluxo para renderizar um anúncio de banner de um RE mediatee.

Saiba mais sobre o uso de SandboxedUiAdapter e da 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 mediador vencedor para esse anúncio.
3. O mediador recebe um SandboxedUiAdapter do mediado.
4. O mediador define o UiAdapter do mediato 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 recebido de um RE Mediatee.

Anúncios de tela cheia do RE 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 de 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 mediador vencedor para esse anúncio.
3. O mediador solicita que o mediato carregue um anúncio, transmitindo o SdkActivityLauncher do app.
4. O Mediate registra um gerenciador de atividades e recebe um token de identificação para a atividade registrada.
5. O mediador usa o SdkActivityLauncher para solicitar a inicialização de uma atividade usando esse token.
6. Se o predicado do app cliente permitir, o SDK Runtime vai iniciar essa atividade no processo dedicado.

Figura 4. Diagrama de fluxo que ilustra como carregar um anúncio em tela cheia mediado de um RE Mediatee.

Observação: todos os eventos do ciclo de vida da atividade estão disponíveis para o mediador usando o ActivityHolder usado ao registrar o gerenciador de atividades.

Saiba mais sobre o suporte a atividades 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 ambiente de execução do SDK e dos SDKs dos mediadores vinculados estaticamente ao app (também sem conhecimento 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 mediadores estã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 ser acessível usando a API do mediador, mas os detalhes da implementação são deixados a critério de cada mediador. Chamamos essa API de MediationSandboxedSdk#registerInAppMediatee.

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

1. O app carrega e inicializa o SDK compatível com o tempo de execução do mediador.
2. O SDK de RA do mediador:
   1. Inicializa o SDK RE do mediador usando SdkSandboxManager#loadSdk.
   2. Inicializa todos os SDKs de mediação no app.
   3. Detecta e registra os SDKs mediatee no app usando a API fornecida pelo SDK 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.

Figura 6. 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 mediatee no app.

Anúncios de banner intermediários no app

Considerando uma solicitação do app para carregar um anúncio de banner, o fluxo para renderizar completamente é o seguinte:

1. O SDK ciente do 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 mediato relevante.
3. O SDK RE do mediador recupera a referência ao mediato e solicita o carregamento de um anúncio pelo SDK RA.
4. O SDK de RA recebe uma visualização do mediador no app.
5. O SDK do RA cria uma 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.

Cuidado: como essa SandboxedUiAdapter é recebida pelo processo do app, não recomendamos adicionar sobreposições a essa visualização, porque isso pode causar problemas de latência, desempenho e comportamento.

Figura 7. O mediador não deve sobrepor visualizações sobre a V1 ao recebê-las de um mediato no app.

Anúncios de tela cheia mediada no app

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

1. O app transmite uma SdkActivityLauncher ao SDK de RA do mediador com a solicitação de carregamento de 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. O SDK RE do mediador:
   1. Seleciona o mediato relevante.
   2. Recupera a referência ao mediador no app.
   3. Solicitações para carregar um anúncio pelo SDK de anúncios premiados.
4. O SDK do RA solicita que o mediador carregue um anúncio.
5. O mediador inicia a atividade diretamente. O predicado do app não será atendido.

Figura 8. O predicado será ignorado pelo mediador no app.

Observação: todos os eventos relacionados à atividade estão disponíveis para o mediador, como antes do SDK Runtime.

Engajamento e compartilhamento de feedback

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