SdkSandboxManager

public final class SdkSandboxManager
extends Object

java.lang.Object (link em inglês)
   ↳ android.app.sdksandbox.SdkSandboxManager


Fornece APIs para carregar SDKs no processo de sandbox do SDK e interagir com eles.

O sandbox do SDK é um processo Java executado em um intervalo de UID separado. Cada app pode ter o próprio processo de sandbox do SDK.

Primeiro, o app precisa declarar no manifesto os SDKs de que depende usando a tag <uses-sdk-library>. Os apps só podem carregar SDKs de que dependem no sandbox.

Resumo

Classes aninhadas

interface SdkSandboxManager.SdkSandboxProcessDeathCallback

Um callback para rastrear o encerramento do sandbox do SDK de eventos. 

Constantes

String EXTRA_DISPLAY_ID

O nome da chave a ser usada nos campos "Pacote" de requestSurfacePackage(java.lang.String, android.os.Bundle, java.util.concurrent.Executor, android.os.OutcomeReceiver). O valor dela precisa definir o ID de número inteiro da exibição lógica para mostrar o SurfacePackage.

String EXTRA_HEIGHT_IN_PIXELS

O nome da chave a ser usada nos campos "Pacote" do requestSurfacePackage(java.lang.String, android.os.Bundle, java.util.concurrent.Executor, android.os.OutcomeReceiver). O valor dela precisa definir a altura inteira de SurfacePackage em pixels.

String EXTRA_HOST_TOKEN

O nome da chave a ser usada nos campos Bundle de requestSurfacePackage(java.lang.String, android.os.Bundle, java.util.concurrent.Executor, android.os.OutcomeReceiver). O valor dela precisa apresentar o token retornado por SurfaceView.getHostToken() depois que o SurfaceView for adicionado à hierarquia de visualização.

String EXTRA_SURFACE_PACKAGE

O nome da chave no pacote que é transmitido para a função onResult do OutcomeReceiver, que é o campo de requestSurfacePackage(java.lang.String, android.os.Bundle, java.util.concurrent.Executor, android.os.OutcomeReceiver). O valor dela apresenta o SurfacePackage solicitado.

String EXTRA_WIDTH_IN_PIXELS

O nome da chave a ser usada nos campos "Pacote" do requestSurfacePackage(java.lang.String, android.os.Bundle, java.util.concurrent.Executor, android.os.OutcomeReceiver). O valor dela precisa definir a largura inteira de SurfacePackage em pixels.

int LOAD_SDK_ALREADY_LOADED

O SDK já está carregado.

int LOAD_SDK_INTERNAL_ERROR

Erro interno ao carregar o SDK.

int LOAD_SDK_NOT_FOUND

O SDK não foi encontrado.

int LOAD_SDK_SDK_DEFINED_ERROR

Erro do SDK após o carregamento.

int LOAD_SDK_SDK_SANDBOX_DISABLED

O sandbox do SDK está desativado.

int REQUEST_SURFACE_PACKAGE_INTERNAL_ERROR

Erro interno ao solicitar um SurfacePackage.

int REQUEST_SURFACE_PACKAGE_SDK_NOT_LOADED

O SDK não é carregado ao solicitar um SurfacePackage.

int SDK_SANDBOX_PROCESS_NOT_AVAILABLE

O processo de sandbox do SDK não está disponível.

String SDK_SANDBOX_SERVICE

Use com Context#getSystemService(String) para extrair um SdkSandboxManager e interagir com os SDKs pertencentes a esse aplicativo cliente.

int SDK_SANDBOX_STATE_DISABLED

O sandbox do SDK está desativado.

int SDK_SANDBOX_STATE_ENABLED_PROCESS_ISOLATION

O sandbox do SDK está ativado.

Métodos públicos

void addSdkSandboxProcessDeathCallback(Executor callbackExecutor, SdkSandboxManager.SdkSandboxProcessDeathCallback callback)

Adiciona um callback que é registrado para eventos de ciclo de vida do sandbox do SDK, como o encerramento do sandbox do SDK.

void addSyncedSharedPreferencesKeys(Set<String> keys)

Adiciona chaves ao conjunto de chaves que está sendo sincronizada do SharedPreferences padrão do app ao sandbox do SDK.

List<AppOwnedSdkSandboxInterface> getAppOwnedSdkSandboxInterfaces()

Busca uma lista de AppOwnedSdkSandboxInterface registrados para um app

List<SandboxedSdk> getSandboxedSdks()

Busca informações sobre SDKs que são carregados no sandbox.

static int getSdkSandboxState()

Retorna o estado atual da disponibilidade do recurso sandbox do SDK.

Set<String> getSyncedSharedPreferencesKeys()

Retorna as chaves definidas que estão sendo sincronizadas do SharedPreferences padrão do app para o sandbox do SDK.

void loadSdk(String sdkName, Bundle params, Executor executor, OutcomeReceiver<SandboxedSdkLoadSdkException> receiver)

Carrega o SDK em um processo Java do sandbox do SDK.

void registerAppOwnedSdkSandboxInterface(AppOwnedSdkSandboxInterface appOwnedSdkSandboxInterface)

Registra AppOwnedSdkSandboxInterface em um processo de app.

void removeSdkSandboxProcessDeathCallback(SdkSandboxManager.SdkSandboxProcessDeathCallback callback)

Remove um SdkSandboxProcessDeathCallback que foi adicionado anteriormente usando addSdkSandboxProcessDeathCallback(java.util.concurrent.Executor, android.app.sdksandbox.SdkSandboxManager.SdkSandboxProcessDeathCallback).

void removeSyncedSharedPreferencesKeys(Set<String> keys)

Remove chaves do conjunto de chaves que foram adicionadas usando addSyncedSharedPreferencesKeys(java.util.Set).

As chaves removidas vão ser apagadas do sandbox do SDK se já tiverem sido sincronizadas.

void requestSurfacePackage(String sdkName, Bundle params, Executor callbackExecutor, OutcomeReceiver<BundleRequestSurfacePackageException> receiver)

Envia uma solicitação de um pacote de superfície ao SDK.

void startSdkSandboxActivity(Activity fromActivity, IBinder sdkActivityToken)

Inicia um Activity no sandbox do SDK.

void unloadSdk(String sdkName)

Descarrega um SDK que foi carregado anteriormente pelo autor da chamada.

void unregisterAppOwnedSdkSandboxInterface(String name)

Cancela o registro de ERROR(/AppOwnedSdkSandboxInterfaces) em um processo de app.

Métodos herdados

Constantes

ID DE DISPLAY EXTRA

public static final String EXTRA_DISPLAY_ID

O nome da chave a ser usada nos campos "Pacote" de requestSurfacePackage(java.lang.String, android.os.Bundle, java.util.concurrent.Executor, android.os.OutcomeReceiver). O valor dela precisa definir o ID de número inteiro da exibição lógica para mostrar o SurfacePackage.

Valor da constante: "android.app.sdksandbox.extra.DISPLAY_ID"

EXTRA_HEIGHT_IN_PIXELS

public static final String EXTRA_HEIGHT_IN_PIXELS

O nome da chave a ser usada nos campos "Pacote" do requestSurfacePackage(java.lang.String, android.os.Bundle, java.util.concurrent.Executor, android.os.OutcomeReceiver). O valor dela precisa definir a altura inteira de SurfacePackage em pixels.

Valor da constante: "android.app.sdksandbox.extra.HEIGHT_IN_PIXELS"

EXTRA_HOST_TOKEN

public static final String EXTRA_HOST_TOKEN

O nome da chave a ser usada nos campos Bundle de requestSurfacePackage(java.lang.String, android.os.Bundle, java.util.concurrent.Executor, android.os.OutcomeReceiver). O valor dela precisa apresentar o token retornado por SurfaceView.getHostToken() depois que o SurfaceView for adicionado à hierarquia de visualização. Somente valores não nulos são aceitos para ativar os relatórios de ANR.

Valor da constante: "android.app.sdksandbox.extra.HOST_TOKEN"

Pacote extra

public static final String EXTRA_SURFACE_PACKAGE

O nome da chave no pacote que é transmitido para a função onResult do OutcomeReceiver, que é o campo de requestSurfacePackage(java.lang.String, android.os.Bundle, java.util.concurrent.Executor, android.os.OutcomeReceiver). O valor dela apresenta o SurfacePackage solicitado.

Valor da constante: "android.app.sdksandbox.extra.SURFACE_PACKAGE"

EXTRA_WIDTH_IN_PIXELS

public static final String EXTRA_WIDTH_IN_PIXELS

O nome da chave a ser usada nos campos "Pacote" do requestSurfacePackage(java.lang.String, android.os.Bundle, java.util.concurrent.Executor, android.os.OutcomeReceiver). O valor dela precisa definir a largura inteira de SurfacePackage em pixels.

Valor da constante: "android.app.sdksandbox.extra.WIDTH_IN_PIXELS"

LOAD_SDK_ALREADY_LOADED

public static final int LOAD_SDK_ALREADY_LOADED

O SDK já está carregado.

Isso indica que o aplicativo cliente tentou recarregar o mesmo SDK chamando loadSdk(java.lang.String, android.os.Bundle, java.util.concurrent.Executor, android.os.OutcomeReceiver) depois de ser carregado.

Valor da constante: 101 (0x00000065)

LOAD_SDK_INTERNAL_ERROR

public static final int LOAD_SDK_INTERNAL_ERROR

Erro interno ao carregar o SDK.

Isso indica que ocorreu um erro interno genérico ao aplicar a chamada do aplicativo cliente.

Valor da constante: 500 (0x000001f4)

LOAD_SDK_NOT_FOUND

public static final int LOAD_SDK_NOT_FOUND

O SDK não foi encontrado.

Isso indica que o aplicativo cliente tentou carregar um SDK que não existe chamando loadSdk(java.lang.String, android.os.Bundle, java.util.concurrent.Executor, android.os.OutcomeReceiver).

Valor da constante: 100 (0x00000064)

LOAD_SDK_SDK_DEFINED_ERROR

public static final int LOAD_SDK_SDK_DEFINED_ERROR

Erro do SDK após o carregamento.

Isso indica que o SDK encontrou um erro durante a inicialização pós-carregamento. Os detalhes podem ser conferidos no pacote retornado em LoadSdkException pelo OutcomeReceiver transmitido para SdkSandboxManager#loadSdk.

Valor da constante: 102 (0x00000066)

SDK LOAD_SDK_SANDBOX_DISABLED

public static final int LOAD_SDK_SDK_SANDBOX_DISABLED

O sandbox do SDK está desativado.

Isso indica que o sandbox do SDK está desativado. Qualquer tentativa subsequente de carregar SDKs nesta inicialização também vai falhar.

Valor da constante: 103 (0x00000067)

REQUEST_SURFACE_PACKAGE_INTERNAL_ERROR

public static final int REQUEST_SURFACE_PACKAGE_INTERNAL_ERROR

Erro interno ao solicitar um SurfacePackage.

Isso indica que ocorreu um erro interno genérico ao solicitar um SurfacePackage.

Valor da constante: 700 (0x000002bc)

REQUEST_SURFACE_PACKAGE_SDK_NOT_LOADED

public static final int REQUEST_SURFACE_PACKAGE_SDK_NOT_LOADED

O SDK não é carregado ao solicitar um SurfacePackage.

Isso indica que o SDK para o qual o SurfacePackage está sendo solicitado não foi carregado porque o sandbox expirou ou não foi carregado.

Valor da constante: 701 (0x000002bd)

SDK_SANDBOX_PROCESS_NÃO_DISPONÍVEL

public static final int SDK_SANDBOX_PROCESS_NOT_AVAILABLE

O processo de sandbox do SDK não está disponível.

Isso indica que o processo de sandbox do SDK não está disponível porque foi encerrado, desconectado ou não foi criado.

Valor da constante: 503 (0x000001f7)

SDK_SANDBOX_SERVICE

public static final String SDK_SANDBOX_SERVICE

Use com Context#getSystemService(String) para extrair um SdkSandboxManager e interagir com os SDKs pertencentes a esse aplicativo cliente.

Valor da constante: "sdk_sandbox"

SDK_SANDBOX_STATE_DISABLED

public static final int SDK_SANDBOX_STATE_DISABLED

O sandbox do SDK está desativado.

As APIs SdkSandboxManager estão ocultas. Qualquer tentativa de ligar vai resultar em UnsupportedOperationException.

Valor da constante: 0 (0x00000000)

SDK_SANDBOX_STATE_ENABLED_PROCESS_ISOLATION

public static final int SDK_SANDBOX_STATE_ENABLED_PROCESS_ISOLATION

O sandbox do SDK está ativado.

O app pode usar APIs SdkSandboxManager para carregar os SDKs de que depende no processo correspondente de sandbox do SDK.

Valor da constante: 2 (0x00000002)

Métodos públicos

addSdkSandboxProcessDeathCallback

public void addSdkSandboxProcessDeathCallback (Executor callbackExecutor, 
                SdkSandboxManager.SdkSandboxProcessDeathCallback callback)

Adiciona um callback que é registrado para eventos de ciclo de vida do sandbox do SDK, como o encerramento do sandbox do SDK. Se o sandbox ainda não tiver sido criado quando chamado, a solicitação será armazenada até que um sandbox seja criado. Nesse momento, ele será ativado para esse sandbox. Vários callbacks podem ser adicionados para detectar mortes e não serão removidos quando o sandbox terminar.

Parâmetros
callbackExecutor Executor: o Executor em que o callback é invocado Este valor não pode ser null. Eventos de callback e listener são enviados com esse Executor, fornecendo uma maneira fácil de controlar qual linha de execução vai ser usada. Para enviar eventos com a linha de execução principal do aplicativo, use Context.getMainExecutor(). Caso contrário, forneça um Executor que seja enviado para uma linha de execução adequada.

callback SdkSandboxManager.SdkSandboxProcessDeathCallback: o SdkSandboxProcessDeathCallback que vai receber os eventos de ciclo de vida do sandbox do SDK. Esse valor não pode ser null.

addSyncedSharedPreferencesKeys

public void addSyncedSharedPreferencesKeys (Set<String> keys)

Adiciona chaves ao conjunto de chaves que está sendo sincronizada do SharedPreferences padrão do app ao sandbox do SDK.

Os dados sincronizados vão ficar disponíveis para os SDKs lerem usando a API SdkSandboxController.getClientSharedPreferences().

Para interromper a sincronização de chaves adicionadas com essa API, use removeSyncedSharedPreferencesKeys(java.util.Set).

A sincronização é interrompida se o app é reiniciado e o usuário precisa chamar essa API novamente para recriar o conjunto de chaves para sincronização.

Observação: esta classe não oferece suporte ao uso em vários processos.

Parâmetros
keys Set: conjunto de chaves que vão ser sincronizadas com o sandbox. Esse valor não pode ser null.

getAppOwnedSdkSandboxInterfaces

public List<AppOwnedSdkSandboxInterface> getAppOwnedSdkSandboxInterfaces ()

Busca uma lista de AppOwnedSdkSandboxInterface registrados para um app

Returns
List<AppOwnedSdkSandboxInterface> lista vazia se callInfo não for encontrado no mapa. Caso contrário, uma lista de AppOwnedSdkSandboxInterface Esse valor não pode ser null.

getSandboxedSdks

public List<SandboxedSdk> getSandboxedSdks ()

Busca informações sobre SDKs que são carregados no sandbox.

Returns
List<SandboxedSdk> Lista de SandboxedSdk contendo todos os SDKs carregados no momento. Esse valor não pode ser null.

getSdkSandboxState

public static int getSdkSandboxState ()

Retorna o estado atual da disponibilidade do recurso sandbox do SDK.

Returns
int O valor é SDK_SANDBOX_STATE_DISABLED ou SDK_SANDBOX_STATE_ENABLED_PROCESS_ISOLATION

getSyncedSharedPreferencesKeys

public Set<String> getSyncedSharedPreferencesKeys ()

Retorna as chaves definidas que estão sendo sincronizadas do SharedPreferences padrão do app para o sandbox do SDK.

Returns
Set<String> Esse valor não pode ser null.

loadSdk

public void loadSdk (String sdkName, 
                Bundle params, 
                Executor executor, 
                OutcomeReceiver<SandboxedSdkLoadSdkException> receiver)

Carrega o SDK em um processo Java do sandbox do SDK.

Carrega a biblioteca do SDK com sdkName para um processo de sandbox do SDK de forma assíncrona. O autor da chamada vai ser notificado pelo receiver.

O autor da chamada já precisa declarar os SDKs de que depende no manifesto usando a tag <uses-sdk-library>. O autor da chamada só pode carregar os SDKs de que depende no sandbox do SDK.

Quando o aplicativo cliente carregar o primeiro SDK, um novo processo de sandbox do SDK será criado. Se um sandbox já tiver sido criado para o aplicativo cliente, outros SDKs serão carregados no mesmo sandbox.

Essa API só pode ser chamada enquanto o autor da chamada está em execução em primeiro plano. Chamadas em segundo plano resultarão no retorno de LoadSdkException no receiver.

Parâmetros
sdkName String: nome do SDK a ser carregado. Esse valor não pode ser null.

params Bundle: outros parâmetros a serem transmitidos ao SDK na forma de um Bundle, conforme combinado entre o cliente e o SDK. Esse valor não pode ser null.

executor Executor: o Executor em que o receptor será invocado. Esse valor não pode ser null. Eventos de callback e listener são enviados com esse Executor, fornecendo uma maneira fácil de controlar qual linha de execução vai ser usada. Para enviar eventos com a linha de execução principal do aplicativo, use Context.getMainExecutor(). Caso contrário, forneça um Executor que seja enviado para uma linha de execução adequada.

receiver OutcomeReceiver: recebe um SandboxedSdk em uma execução bem-sucedida ou LoadSdkException. Esse valor não pode ser null.

registerAppOwnedSdkSandboxInterface

public void registerAppOwnedSdkSandboxInterface (AppOwnedSdkSandboxInterface appOwnedSdkSandboxInterface)

Registra AppOwnedSdkSandboxInterface em um processo de app.

Registrar um AppOwnedSdkSandboxInterface que tem o mesmo nome de uma interface registrada anteriormente resultará em IllegalStateException.

AppOwnedSdkSandboxInterface#getName() se refere ao nome da interface.

Parâmetros
appOwnedSdkSandboxInterface AppOwnedSdkSandboxInterface: a AppOwnedSdkSandboxInterface a ser registrada Esse valor não pode ser null.

removeSdkProcessDeathCallback

public void removeSdkSandboxProcessDeathCallback (SdkSandboxManager.SdkSandboxProcessDeathCallback callback)

Remove um SdkSandboxProcessDeathCallback que foi adicionado anteriormente usando addSdkSandboxProcessDeathCallback(java.util.concurrent.Executor, android.app.sdksandbox.SdkSandboxManager.SdkSandboxProcessDeathCallback).

Parâmetros
callback SdkSandboxManager.SdkSandboxProcessDeathCallback: o SdkSandboxProcessDeathCallback que foi adicionado anteriormente usando SdkSandboxManager#addSdkSandboxProcessDeathCallback(Executor, SdkSandboxProcessDeathCallback) Esse valor não pode ser null.

removeSyncedSharedPreferencesKeys

public void removeSyncedSharedPreferencesKeys (Set<String> keys)

Remove chaves do conjunto de chaves que foram adicionadas usando addSyncedSharedPreferencesKeys(java.util.Set).

As chaves removidas vão ser apagadas do sandbox do SDK se já tiverem sido sincronizadas.

Parâmetros
keys Set: conjunto de nomes de chave que não vão mais ser sincronizados com o sandbox. Esse valor não pode ser null.

requestSurfacePackage

public void requestSurfacePackage (String sdkName, 
                Bundle params, 
                Executor callbackExecutor, 
                OutcomeReceiver<BundleRequestSurfacePackageException> receiver)

Envia uma solicitação de um pacote de superfície ao SDK.

Depois que o app cliente receber um indicador sobre um carregamento do SDK e adicionar um SurfaceView à hierarquia de visualização, ele poderá solicitar de forma assíncrona um SurfacePackage para renderizar uma visualização do SDK.

Quando o SurfacePackage estiver pronto, o callback OutcomeReceiver#onResult do receiver transmitido será invocado. Esse callback conterá um objeto Bundle, que terá a chave SdkSandboxManager#EXTRA_SURFACE_PACKAGE, cujo valor associado é o SurfacePackage solicitado.

O params transmitido precisa conter as seguintes chaves: EXTRA_WIDTH_IN_PIXELS, SdkSandboxManager#EXTRA_HEIGHT_IN_PIXELS, SdkSandboxManager#EXTRA_DISPLAY_ID e SdkSandboxManager#EXTRA_HOST_TOKEN. Se alguma dessas chaves estiver ausente ou for inválida, uma IllegalArgumentException será gerada.

Essa API só pode ser chamada enquanto o autor da chamada está em execução em primeiro plano. Chamadas em segundo plano resultarão no retorno de RequestSurfacePackageException no receiver.

Parâmetros
sdkName String: nome do SDK carregado no sandbox. Esse valor não pode ser null.

params Bundle: os parâmetros que o aplicativo cliente transmite ao SDK. Esse valor não pode ser null.

callbackExecutor Executor: o Executor em que o callback é invocado Este valor não pode ser null. Eventos de callback e listener são enviados com esse Executor, fornecendo uma maneira fácil de controlar qual linha de execução vai ser usada. Para enviar eventos com a linha de execução principal do aplicativo, use Context.getMainExecutor(). Caso contrário, forneça um Executor que seja enviado para uma linha de execução adequada.

receiver OutcomeReceiver: retorna um Bundle em caso de sucesso, que vai conter a chave SdkSandboxManager#EXTRA_SURFACE_PACKAGE com um valor SurfacePackage, ou RequestSurfacePackageException em caso de falha. Esse valor não pode ser null.

Gera
IllegalArgumentException se params não tiver todas as chaves necessárias.

startSdkSandboxActivity

public void startSdkSandboxActivity (Activity fromActivity, 
                IBinder sdkActivityToken)

Inicia um Activity no sandbox do SDK.

Essa função vai iniciar um novo Activity na mesma tarefa do fromActivity transmitido e transmiti-lo ao SDK que compartilhou o sdkActivityToken transmitido, que identifica uma solicitação desse SDK para ativar esse Activity.

O Activity não será iniciado nos seguintes casos:

  • O app que está chamando essa API está em segundo plano.
  • O sdkActivityToken transmitido não está associado a uma solicitação de um Activity do SDK que o compartilhou com o app autor da chamada.
  • O SDK que compartilhou o sdkActivityToken transmitido removeu a solicitação para esse Activity.
  • O sandbox Activity já foi criado.

Parâmetros
fromActivity Activity: o Activity vai ser usado para iniciar o novo Activity sandbox chamando Activity#startActivity(Intent). Esse valor não pode ser null.

sdkActivityToken IBinder: o identificador compartilhado pelo SDK que solicita o Activity. Esse valor não pode ser null.

DesloadSdk

public void unloadSdk (String sdkName)

Descarrega um SDK que foi carregado anteriormente pelo autor da chamada.

Não é possível garantir que a memória alocada para esse SDK seja liberada imediatamente. Todas as chamadas subsequentes para requestSurfacePackage(java.lang.String, android.os.Bundle, java.util.concurrent.Executor, android.os.OutcomeReceiver) para o sdkName especificado falharão.

Essa API só pode ser chamada enquanto o autor da chamada está em execução em primeiro plano. Chamadas em segundo plano resultam na geração de uma SecurityException.

Parâmetros
sdkName String: nome do SDK a ser descarregado. Esse valor não pode ser null.

CancelAppOwnedSdkSandboxInterface

public void unregisterAppOwnedSdkSandboxInterface (String name)

Cancela o registro de ERROR(/AppOwnedSdkSandboxInterfaces) em um processo de app.

Parâmetros
name String: o nome em que a AppOwnedSdkSandboxInterface foi registrada. Esse valor não pode ser null.