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. |
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 |
List<AppOwnedSdkSandboxInterface>
|
getAppOwnedSdkSandboxInterfaces()
Busca uma lista de |
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 |
void
|
loadSdk(String sdkName, Bundle params, Executor executor, OutcomeReceiver<SandboxedSdk, LoadSdkException> receiver)
Carrega o SDK em um processo Java do sandbox do SDK. |
void
|
registerAppOwnedSdkSandboxInterface(AppOwnedSdkSandboxInterface appOwnedSdkSandboxInterface)
Registra |
void
|
removeSdkSandboxProcessDeathCallback(SdkSandboxManager.SdkSandboxProcessDeathCallback callback)
Remove um |
void
|
removeSyncedSharedPreferencesKeys(Set<String> keys)
Remove chaves do conjunto de chaves que foram adicionadas usando 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<Bundle, RequestSurfacePackageException> receiver)
Envia uma solicitação de um pacote de superfície ao SDK. |
void
|
startSdkSandboxActivity(Activity fromActivity, IBinder sdkActivityToken)
Inicia um |
void
|
unloadSdk(String sdkName)
Descarrega um SDK que foi carregado anteriormente pelo autor da chamada. |
void
|
unregisterAppOwnedSdkSandboxInterface(String name)
Cancela o registro de |
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<SandboxedSdk, LoadSdkException> 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<Bundle, RequestSurfacePackageException> 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 umActivity
do SDK que o compartilhou com o app autor da chamada. - O SDK que compartilhou o
sdkActivityToken
transmitido removeu a solicitação para esseActivity
. - 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 . |