Suporte de atividades para anúncios em tela cheia

Observação: o Sandbox de privacidade no Android é um projeto em andamento, e este documento mostra o design atual. Seu feedback é essencial no desenvolvimento e aprimoramento de recursos.

Enviar feedback

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

Os SDKs carregados no ambiente do SDK Runtime não podem definir diretamente as tags <activity> no manifesto nem iniciar as próprias atividades. Em vez disso, uma nova ação da intent, START_SANDBOXED_ACTIVITY, é 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 para o SDK. Esta atividade será executada em o mesmo processo do SDK.

O SDK pode usar essa atividade para implementar e gerenciar o anúncio de tela cheia do usuário.

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

Cuidado: a atividade fornecida (android.app.Activity) tem suporte limitado a algumas bibliotecas do AndroidX no SDK, principalmente o Compose.

Atenção: o Context dessa atividade não pode ser usado diretamente pelo SDK do Vertex AI Pipelines. Em vez disso, os SDKs precisam usar SandboxedSdkProvider#getContext() para receber o contexto apropriado para as operações.

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 APIs da plataforma.

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

Bibliotecas de atividades

Atividade bibliotecas oferecem várias vantagens:

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

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

• A biblioteca core fornece as interfaces usadas pelos apps clientes e bibliotecas de provedores.
• A biblioteca de provedor fornece APIs para que os SDKs iniciem atividades.
• A biblioteca cliente fornece APIs para que os apps clientes criem um inicializador de atividades, que os SDKs podem usar para solicitar que os apps iniciem atividades.

Essas bibliotecas introduzem as seguintes APIs:

• SdkActivityLauncher: o acesso rápido de atividades permite que os SDKs processem a inicialização de atividades no app cliente. Os apps clientes precisam criar uma tela de início e transmiti-la como um parâmetro para as APIs do SDK que iniciam atividades.
• <T : Activity & LifecycleOwner> T.createSdkActivityLauncher(() -> Boolean ): Uma função de extensão que o app cliente pode chamar nas atividades dele para criar telas de início.
• SdkActivityLauncher.launchSdkActivity(IBinder): um método usado pelo SDK para solicitar que o app inicie atividades.

O fluxo para iniciar atividades com bibliotecas de atividades é o seguinte:

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

.

Observação :se o app cliente quiser adicionar uma condição para que os SDKs criem atividades, ele poderá transmitir uma expressão de predicado ao criar a tela de início. Se o app não quiser condicionar a criação de atividades, ele poderá fazer com que o predicado retorne sempre true.

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

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

APIs de plataforma

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

• SdkSandboxActivityHandler: O gerenciador de atividades é usado para notificar o SDK quando uma atividade é criada e é registrada pelo SDK.
• Para ajudar no registro de gerenciadores de atividades, o SDK pode usar os seguintes métodos em SdkSandboxController:
  • .registerSdkSandboxActivityHandler(SdkSandboxActivityHandler): Registra uma instância de SdkSandboxActivityHandler, que retorna um identificador IBinder.
  • .unregisterSdkSandboxActivityHandler(SdkSandboxActivityHandler): Cancela o registro de uma instância registrada de SdkSandboxActivityHandler usando seu identificador.
• SdkSandboxManager.startSdkSandboxActivity(Activity, IBinder): Invocado pelo app cliente, esse método aciona a criação de atividades para o SDK. O app cliente precisa transmitir como parâmetros a atividade inicial escolhida e o identificador do gerenciador de atividades do SDK.

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

1. O SDK registra um gerenciador 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 usando um callback no gerenciador de atividades (SdkSandboxActivityHandler.onActivityCreated(Activity)).
5. O SDK usa a atividade para preenchê-la com um anúncio.

.

Observação: onActivityCreated(Activity) é chamado por meio de Activity.onCreate(Bundle), Espera-se que os SDKs preencham a visualização de conteúdo nessa fase.

O uso de APIs de plataforma torna o SDK responsável por compartilhar o SdkSandboxActivityHandler identificador com o aplicativo cliente por meio de suas APIs em um momento apropriado e guiar apps clientes sobre como usá-lo.

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

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 lado canais para renderizar visualizações do SDK no 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 está visível para o usuário, porque a visualização do anúncio não é 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 padrão Activity e View do Android.

Devido a essas diferentes implementações, esforços contínuos visam unificar o para recuperar os sinais de visibilidade, independentemente do contexto de carregamento do anúncio.

Ciclo de vida

A ActivityHolder passados para o SDK por meio de SdkSandboxActivityHandlerCompat.onActivityCreated(ActivityHolder) implements LifecycleOwner e pode ser usado para conhecer Lifecycle.Event

Navegação de retorno

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