Suporte de atividades para anúncios em tela cheia

O SDK Runtime impõe restrições sobre como os SDKs podem iniciar novas atividades. Isso representa um desafio para formatos de anúncios em tela cheia que normalmente dependem da inicialização de uma atividade separada para melhorar o controle e a experiência do usuário. Para resolver esse problema, o SDK Runtime apresenta um novo mecanismo para atividades em sandbox.

Os SDKs carregados no ambiente do SDK Runtime não podem definir tags <activity> diretamente no manifesto nem iniciar as próprias atividades. Em vez disso, uma nova ação de intent, START_SANDBOXED_ACTIVITY, foi introduzida.

Embora os SDKs também não possam iniciar intents com essa ação, eles podem solicitar que o app cliente inicie essa intent. Em seguida, o sistema cria uma atividade definida pela plataforma e a transmite ao SDK. Essa atividade será executada no mesmo processo do SDK.

O SDK pode usar essa atividade para implementar e gerenciar a experiência de anúncios em tela cheia.

A atividade fornecida pela plataforma é uma android.app.Activity padrão, iniciada como parte da tarefa do app cliente.

Criação de atividades no SDK Runtime

Você tem dois métodos principais para criar atividades: usando as bibliotecas de atividades simplificadas do Jetpack ou interagindo diretamente com as APIs da plataforma.

Recomendamos o uso de bibliotecas de atividades, porque elas simplificam a criação de atividades abstraindo a complexidade subjacente.

Bibliotecas de atividades

As bibliotecas de atividades oferecem várias vantagens:

  • Abstrair os detalhes internos de registro de manipuladores de atividades e compartilhamento dos identificadores com apps clientes.
  • Dá aos desenvolvedores de apps mais controle sobre como os SDKs criam atividades nos apps, permitindo que eles definam condições (predicados) a serem atendidas.
  • Criar uma maneira unificada para os SDKs definirem APIs que iniciam atividades.

Há três bibliotecas de atividade: principal, de cliente e de provedor.

  • A biblioteca principal fornece as interfaces usadas pelos apps cliente e bibliotecas de provedor.
  • A biblioteca provider fornece APIs para que os SDKs iniciem atividades.
  • A biblioteca cliente fornece APIs para apps clientes criarem um iniciador de atividades, que os SDKs podem usar para solicitar que os apps iniciem atividades.

Essas bibliotecas apresentam as seguintes APIs:

O fluxo de atividades de inicialização com bibliotecas de atividades é o seguinte:

  1. O SDK adiciona um parâmetro do tipo SdkActivityLauncher a todas as APIs que vão iniciar atividades.
  2. O app cliente chama createSdkActivityLauncher em uma das atividades para criar um iniciador que pode ser transmitido ao SDK em chamadas de API.
  3. O SDK chama SdkSandboxControllerCompat.registerSdkSandboxActivityHandler(SdkSandboxActivityHandlerCompat) e recupera o token de identificador.
  4. O SDK chama launchSdkActivity para iniciar a atividade.

O diagrama a seguir mostra o fluxo no caso de uso de bibliotecas de atividades.

Diagrama de sequência da biblioteca de atividades
Diagrama de sequência mostrando o fluxo de início de uma atividade usando bibliotecas de atividades.

APIs da plataforma

A plataforma apresenta as seguintes APIs para facilitar a criação e o gerenciamento de atividades em sandbox no SDK Runtime:

Para iniciar uma atividade usando as APIs da plataforma, os SDKs precisam seguir este fluxo:

  1. O SDK registra um manipulador de atividades usando as APIs fornecidas e recebe um identificador.
  2. O SDK compartilha esse identificador com o app cliente.
  3. O app cliente chama o método para iniciar uma atividade no SDK Runtime com a API da plataforma startSdkSandboxActivity(Activity, IBinder), transmitindo como parâmetros a atividade inicial escolhida para essa nova atividade e o identificador do gerenciador de atividades.
  4. A plataforma inicia uma atividade e notifica o SDK por um callback no gerenciador de atividades (SdkSandboxActivityHandler.onActivityCreated(Activity)).
  5. O SDK usa a atividade para preenchê-la com um anúncio.

O uso de APIs da plataforma faz com que o SDK seja responsável por compartilhar o identificador do SdkSandboxActivityHandler com o app cliente usando as APIs em um momento adequado e orientar os apps clientes sobre como usá-lo.

No diagrama de fluxo abaixo, o SDK de exemplo tem um método launchActivity(AppCallback) que espera um callback (definido como parte da API do SDK). Esse callback é usado pelo SDK para compartilhar o identificador do gerenciador de atividades (SdkSandboxActivityHandler) com o app cliente.

Diagrama de sequência das APIs da plataforma
Diagrama de sequência mostrando o fluxo de início de uma atividade usando APIs da plataforma.

Visibilidade

No SDK Runtime, os anúncios integrados à hierarquia de visualização do app cliente usam canais laterais para renderizar visualizações do SDK do processo do SDK para o processo do app cliente.

O SDK não pode usar as mesmas APIs View usadas fora do SDK Runtime para determinar se o anúncio fica visível para o usuário, já que a visualização do anúncio não está anexada à janela do aplicativo (visibilidade).

Por outro lado, a atividade fornecida pela plataforma é executada de forma nativa no processo do SDK Runtime, eliminando a necessidade de canais secundários e permitindo que os SDKs usem as APIs Activity e View padrão do Android.

Devido a essas diferentes implementações, os esforços em andamento visam unificar as interfaces para recuperar os indicadores de visibilidade, independentemente do contexto de carregamento do anúncio.

Ciclo de vida

O ActivityHolder transmitido ao SDK pelo SdkSandboxActivityHandlerCompat.onActivityCreated(ActivityHolder) implementa LifecycleOwner e pode ser usado para saber mais sobre o Lifecycle.Event.

Navegação de retorno

O método ActivityHolder.getOnBackPressedDispatcher() retorna OnBackPressedDispatcher, que pode ser usado para registrar instâncias de OnBackPressedCallback para processar a navegação de volta.