SdkSandboxManager

public final class SdkSandboxManager
extends Object

java.lang.Object.
   ↳ android.app.sdksandbox.SdkSandboxManager


Proporciona las APIs para cargar SDKs en el proceso de la zona de pruebas del SDK y, luego, interactuar con ellas.

La zona de pruebas del SDK es un proceso de Java que se ejecuta en un rango de UID separado. Cada app puede tener su propio proceso de la zona de pruebas del SDK.

Primero, la app debe declarar los SDK de los que depende en su manifiesto con la etiqueta <uses-sdk-library>. Es posible que las apps solo carguen los SDKs de los que dependan en la zona de pruebas del SDK.

Resumen

Clases anidadas

interface SdkSandboxManager.SdkSandboxProcessDeathCallback

Una devolución de llamada para hacer un seguimiento del cierre de la zona de pruebas del SDK de eventos. 

Constantes

String EXTRA_DISPLAY_ID

Es el nombre de la clave que se usará en los campos de paquete de requestSurfacePackage(java.lang.String, android.os.Bundle, java.util.concurrent.Executor, android.os.OutcomeReceiver). Su valor debe definir el ID de número entero de la pantalla lógica para mostrar el SurfacePackage.

String EXTRA_HEIGHT_IN_PIXELS

Es el nombre de la clave que se usará en los campos Bundle de requestSurfacePackage(java.lang.String, android.os.Bundle, java.util.concurrent.Executor, android.os.OutcomeReceiver). Su valor debe definir la altura del número entero de SurfacePackage en píxeles.

String EXTRA_HOST_TOKEN

Es el nombre de la clave que se usará en los campos Bundle de requestSurfacePackage(java.lang.String, android.os.Bundle, java.util.concurrent.Executor, android.os.OutcomeReceiver). Su valor debe presentar el token que muestra SurfaceView.getHostToken() una vez que se agrega SurfaceView a la jerarquía de vistas.

String EXTRA_SURFACE_PACKAGE

El nombre de la clave en el Bundle que se pasa a la función onResult de OutcomeReceiver, que es el campo requestSurfacePackage(java.lang.String, android.os.Bundle, java.util.concurrent.Executor, android.os.OutcomeReceiver), presenta el SurfacePackage solicitado.

String EXTRA_WIDTH_IN_PIXELS

Es el nombre de la clave que se usará en los campos Bundle de requestSurfacePackage(java.lang.String, android.os.Bundle, java.util.concurrent.Executor, android.os.OutcomeReceiver). Su valor debe definir el ancho del número entero de SurfacePackage en píxeles.

int LOAD_SDK_ALREADY_LOADED

Ya se cargó el SDK.

int LOAD_SDK_INTERNAL_ERROR

Se produjo un error interno durante la carga del SDK.

int LOAD_SDK_NOT_FOUND

No se encontró el SDK.

int LOAD_SDK_SDK_DEFINED_ERROR

Se produjo un error de SDK después de la carga.

int LOAD_SDK_SDK_SANDBOX_DISABLED

La zona de pruebas del SDK está inhabilitada.

int REQUEST_SURFACE_PACKAGE_INTERNAL_ERROR

Se produjo un error interno cuando se solicitó SurfacePackage.

int REQUEST_SURFACE_PACKAGE_SDK_NOT_LOADED

No se carga el SDK mientras se solicita un SurfacePackage.

int SDK_SANDBOX_PROCESS_NOT_AVAILABLE

El proceso de la zona de pruebas del SDK no está disponible.

String SDK_SANDBOX_SERVICE

Se usa con Context#getSystemService(String) a fin de recuperar un SdkSandboxManager para interactuar con los SDK que pertenecen a esta aplicación cliente.

int SDK_SANDBOX_STATE_DISABLED

La zona de pruebas del SDK está inhabilitada.

int SDK_SANDBOX_STATE_ENABLED_PROCESS_ISOLATION

La zona de pruebas del SDK está habilitada.

Métodos públicos

void addSdkSandboxProcessDeathCallback(Executor callbackExecutor, SdkSandboxManager.SdkSandboxProcessDeathCallback callback)

Agrega una devolución de llamada que se registra para los eventos de ciclo de vida de la zona de pruebas del SDK, como la finalización de la zona de pruebas del SDK.

void addSyncedSharedPreferencesKeys(Set<String> keys)

Agrega claves al conjunto de claves que se sincronizan desde el SharedPreferences predeterminado de la app a la zona de pruebas del SDK.

List<AppOwnedSdkSandboxInterface> getAppOwnedSdkSandboxInterfaces()

Recupera una lista de AppOwnedSdkSandboxInterface registrados en una app

List<SandboxedSdk> getSandboxedSdks()

Recupera información sobre los SDK que se cargan en la zona de pruebas.

static int getSdkSandboxState()

Muestra el estado actual de disponibilidad de la función de zona de pruebas del SDK.

Set<String> getSyncedSharedPreferencesKeys()

Muestra las claves del conjunto que se sincronizan del SharedPreferences predeterminado de la app a la zona de pruebas del SDK.

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

Carga el SDK en un proceso de Java de la zona de pruebas del SDK.

void registerAppOwnedSdkSandboxInterface(AppOwnedSdkSandboxInterface appOwnedSdkSandboxInterface)

Registra AppOwnedSdkSandboxInterface para un proceso de app.

void removeSdkSandboxProcessDeathCallback(SdkSandboxManager.SdkSandboxProcessDeathCallback callback)

Quita un SdkSandboxProcessDeathCallback que se agregó antes con addSdkSandboxProcessDeathCallback(java.util.concurrent.Executor, android.app.sdksandbox.SdkSandboxManager.SdkSandboxProcessDeathCallback)

void removeSyncedSharedPreferencesKeys(Set<String> keys)

Quita las llaves del conjunto de llaves que se agregaron con addSyncedSharedPreferencesKeys(java.util.Set)

Las claves que quites se borrarán de la zona de pruebas del SDK si ya se sincronizaron.

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

Envía al SDK una solicitud de un paquete de superficie.

void startSdkSandboxActivity(Activity fromActivity, IBinder sdkActivityToken)

Inicia una Activity en la zona de pruebas del SDK.

void unloadSdk(String sdkName)

Descarga un SDK que el llamador cargó previamente.

void unregisterAppOwnedSdkSandboxInterface(String name)

Cancela el registro de ERROR(/AppOwnedSdkSandboxInterfaces) para un proceso de la app.

Métodos heredados

Constantes

EXTRA_DISPLAY_ID

public static final String EXTRA_DISPLAY_ID

Es el nombre de la clave que se usará en los campos de paquete de requestSurfacePackage(java.lang.String, android.os.Bundle, java.util.concurrent.Executor, android.os.OutcomeReceiver). Su valor debe definir el ID de número entero de la pantalla lógica para mostrar el SurfacePackage.

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

ALTURA_EXTRA_EN_PÍXELES

public static final String EXTRA_HEIGHT_IN_PIXELS

Es el nombre de la clave que se usará en los campos Bundle de requestSurfacePackage(java.lang.String, android.os.Bundle, java.util.concurrent.Executor, android.os.OutcomeReceiver). Su valor debe definir la altura del número entero de SurfacePackage en píxeles.

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

EXTRA_HOST_TOKEN

public static final String EXTRA_HOST_TOKEN

Es el nombre de la clave que se usará en los campos Bundle de requestSurfacePackage(java.lang.String, android.os.Bundle, java.util.concurrent.Executor, android.os.OutcomeReceiver). Su valor debe presentar el token que muestra SurfaceView.getHostToken() una vez que se agrega SurfaceView a la jerarquía de vistas. Solo se acepta un valor no nulo para habilitar los informes de ANR.

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

PAQUETE_SURFACE_EXTRA

public static final String EXTRA_SURFACE_PACKAGE

El nombre de la clave en el Bundle que se pasa a la función onResult de OutcomeReceiver, que es el campo requestSurfacePackage(java.lang.String, android.os.Bundle, java.util.concurrent.Executor, android.os.OutcomeReceiver), presenta el SurfacePackage solicitado.

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

EXTRA_WIDTH_EN_PIXELS

public static final String EXTRA_WIDTH_IN_PIXELS

Es el nombre de la clave que se usará en los campos Bundle de requestSurfacePackage(java.lang.String, android.os.Bundle, java.util.concurrent.Executor, android.os.OutcomeReceiver). Su valor debe definir el ancho del número entero de SurfacePackage en píxeles.

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

LOAD_SDK_ALREADY_LOADED

public static final int LOAD_SDK_ALREADY_LOADED

Ya se cargó el SDK.

Esto indica que la aplicación cliente intentó volver a cargar el mismo SDK llamando a loadSdk(java.lang.String, android.os.Bundle, java.util.concurrent.Executor, android.os.OutcomeReceiver) después de cargarse correctamente.

Valor constante: 101 (0x00000065)

LOAD_SDK_INTERNAL_ERROR

public static final int LOAD_SDK_INTERNAL_ERROR

Se produjo un error interno durante la carga del SDK.

Esto indica que se produjo un error interno genérico cuando se aplicaba la llamada desde la aplicación cliente.

Valor constante: 500 (0x000001f4)

LOAD_SDK_NOT_FOUND

public static final int LOAD_SDK_NOT_FOUND

No se encontró el SDK.

Esto indica que la aplicación cliente intentó cargar un SDK inexistente con una llamada a loadSdk(java.lang.String, android.os.Bundle, java.util.concurrent.Executor, android.os.OutcomeReceiver).

Valor constante: 100 (0x00000064)

LOAD_SDK_SDK_DEFINED_ERROR

public static final int LOAD_SDK_SDK_DEFINED_ERROR

Se produjo un error de SDK después de la carga.

Esto indica que el SDK detectó un error durante la inicialización posterior a la carga. Los detalles se pueden obtener del paquete que se muestra en LoadSdkException mediante el OutcomeReceiver que se pasa a SdkSandboxManager#loadSdk.

Valor constante: 102 (0x00000066)

LOAD_SDK_SDK_SANDBOX_DISABLED

public static final int LOAD_SDK_SDK_SANDBOX_DISABLED

La zona de pruebas del SDK está inhabilitada.

Esto indica que la zona de pruebas del SDK está inhabilitada. También fallarán todos los intentos posteriores de cargar los SDKs en este inicio.

Valor constante: 103 (0x00000067)

REQUEST_SURFACE_PACKAGE_INTERNAL_ERROR

public static final int REQUEST_SURFACE_PACKAGE_INTERNAL_ERROR

Se produjo un error interno cuando se solicitó SurfacePackage.

Esto indica que se produjo un error interno genérico cuando se solicitaba SurfacePackage.

Valor constante: 700 (0x000002bc)

REQUEST_SURFACE_PACKAGE_SDK_NOT_LOADED

public static final int REQUEST_SURFACE_PACKAGE_SDK_NOT_LOADED

No se carga el SDK mientras se solicita un SurfacePackage.

Esto indica que no se cargó el SDK para el que se solicita SurfacePackage, ya sea porque la zona de pruebas falló o porque no se cargó en primer lugar.

Valor constante: 701 (0x000002bd)

SDK_SANDBOX_PROCESS_NOT_AVAILABLE

public static final int SDK_SANDBOX_PROCESS_NOT_AVAILABLE

El proceso de la zona de pruebas del SDK no está disponible.

Esto indica que el proceso de la zona de pruebas del SDK no está disponible, ya sea porque finalizó, se desconectó o no se creó.

Valor constante: 503 (0x000001f7)

SDK_SANDBOX_SERVICE

public static final String SDK_SANDBOX_SERVICE

Se usa con Context#getSystemService(String) a fin de recuperar un SdkSandboxManager para interactuar con los SDK que pertenecen a esta aplicación cliente.

Valor constante: "sdk_sandbox"

SDK_SANDBOX_STATE_DISABLED

public static final int SDK_SANDBOX_STATE_DISABLED

La zona de pruebas del SDK está inhabilitada.

Se ocultaron las API de SdkSandboxManager. Los intentos de llamarlos generarán UnsupportedOperationException.

Valor constante: 0 (0x00000000)

SDK_SANDBOX_STATE_ENABLED_PROCESS_ISOLATION

public static final int SDK_SANDBOX_STATE_ENABLED_PROCESS_ISOLATION

La zona de pruebas del SDK está habilitada.

La app puede usar las APIs de SdkSandboxManager para cargar la SDKs de la que depende en el proceso de la zona de pruebas del SDK correspondiente.

Valor constante: 2 (0x00000002)

Métodos públicos

addSdkSandboxProcessDeathCallback

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

Agrega una devolución de llamada que se registra para los eventos de ciclo de vida de la zona de pruebas del SDK, como la finalización de la zona de pruebas del SDK. Si la zona de pruebas aún no se ha creado cuando se llama a esta función, la solicitud se almacenará hasta que se cree una zona de pruebas, momento en el cual se activará. Se pueden agregar varias devoluciones de llamada para detectar el cierre de la zona de pruebas y no se quitarán cuando se cierre la zona de pruebas.

Parámetros
callbackExecutor Executor: el Executor en el que se invoca la devolución de llamada. Este valor no puede ser null. Los eventos de devolución de llamada y de objetos de escucha se envían a través de este Executor, lo que proporciona una manera fácil de controlar el subproceso que se usa. Para enviar eventos a través del subproceso principal de tu aplicación, puedes usar Context.getMainExecutor(). De lo contrario, proporciona un Executor que se envíe al subproceso correspondiente.

callback SdkSandboxManager.SdkSandboxProcessDeathCallback: El SdkSandboxProcessDeathCallback que recibirá los eventos de ciclo de vida de la zona de pruebas del SDK. Este valor no puede ser null.

addSyncedSharedPreferencesKeys

public void addSyncedSharedPreferencesKeys (Set<String> keys)

Agrega claves al conjunto de claves que se sincronizan desde el SharedPreferences predeterminado de la app a la zona de pruebas del SDK.

Los datos sincronizados estarán disponibles para que los SDKs los lean mediante la API de SdkSandboxController.getClientSharedPreferences().

Para detener la sincronización de cualquier clave que se haya agregado con esta API, usa removeSyncedSharedPreferencesKeys(java.util.Set).

La sincronización se interrumpe si la app se reinicia y el usuario debe llamar de nuevo a esta API a fin de recompilar el grupo de claves para la sincronización.

Nota: Esta clase no admite el uso en varios procesos.

Parámetros
keys Set: Conjunto de claves que se sincronizarán con la zona de pruebas. Este valor no puede ser null.

getAppOwnedSdkSandboxInterfaces.

public List<AppOwnedSdkSandboxInterface> getAppOwnedSdkSandboxInterfaces ()

Recupera una lista de AppOwnedSdkSandboxInterface registrados en una app

Devuelve
List<AppOwnedSdkSandboxInterface> lista vacía si no se encuentra callsInfo en el mapa; de lo contrario, es una lista de AppOwnedSdkSandboxInterface. Este valor no puede ser null.

getSandboxedSdks.

public List<SandboxedSdk> getSandboxedSdks ()

Recupera información sobre los SDK que se cargan en la zona de pruebas.

Devuelve
List<SandboxedSdk> Lista de SandboxedSdk que contiene todos los SDKs cargados actualmente. Este valor no puede ser null.

getSdkSandboxState

public static int getSdkSandboxState ()

Muestra el estado actual de disponibilidad de la función de zona de pruebas del SDK.

Devuelve
int El valor es SDK_SANDBOX_STATE_DISABLED o SDK_SANDBOX_STATE_ENABLED_PROCESS_ISOLATION.

getSyncedSharedPreferencesKeys

public Set<String> getSyncedSharedPreferencesKeys ()

Muestra las claves del conjunto que se sincronizan del SharedPreferences predeterminado de la app a la zona de pruebas del SDK.

Devuelve
Set<String> Este valor no puede ser null.

loadSdk

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

Carga el SDK en un proceso de Java de la zona de pruebas del SDK.

Carga la biblioteca del SDK con sdkName en un proceso de zona de pruebas del SDK de forma asíncrona. El emisor recibirá una notificación a través de receiver.

El llamador ya debe declarar SDKs de la que depende en su manifiesto con la etiqueta <uses-sdk-library>. El llamador solo puede cargar SDKs de la que depende en la zona de pruebas del SDK.

Cuando la aplicación cliente cargue el primer SDK, se creará un nuevo proceso de zona de pruebas del SDK. Si ya se creó una zona de pruebas para la aplicación cliente, se cargarán SDKs adicionales en la misma zona de pruebas.

Solo se puede llamar a esta API mientras el emisor se ejecuta en primer plano. Las llamadas en segundo plano generarán LoadSdkException en el receiver.

Parámetros
sdkName String: Es el nombre del SDK que se cargará. Este valor no puede ser null.

params Bundle: Son parámetros adicionales que se pasarán al SDK en forma de Bundle, según lo acordado entre el cliente y el SDK. Este valor no puede ser null.

executor Executor: El Executor en el que se invoca el receptor. Este valor no puede ser null. Los eventos de devolución de llamada y de objetos de escucha se envían a través de este Executor, lo que proporciona una manera fácil de controlar el subproceso que se usa. Para enviar eventos a través del subproceso principal de tu aplicación, puedes usar Context.getMainExecutor(). De lo contrario, proporciona un Executor que se envíe al subproceso correspondiente.

receiver OutcomeReceiver: Recibe un SandboxedSdk si se ejecuta correctamente o un LoadSdkException. Este valor no puede ser null.

registrarAppOwnedSdkSandboxInterface

public void registerAppOwnedSdkSandboxInterface (AppOwnedSdkSandboxInterface appOwnedSdkSandboxInterface)

Registra AppOwnedSdkSandboxInterface para un proceso de app.

Registrar un AppOwnedSdkSandboxInterface con el mismo nombre que una interfaz registrada con anterioridad dará como resultado IllegalStateException.

AppOwnedSdkSandboxInterface#getName() hace referencia al nombre de la interfaz.

Parámetros
appOwnedSdkSandboxInterface AppOwnedSdkSandboxInterface: La AppOwnedSdkSandboxInterface que se registrará. Este valor no puede ser null.

removeSdkSandboxProcessDeathCallback

public void removeSdkSandboxProcessDeathCallback (SdkSandboxManager.SdkSandboxProcessDeathCallback callback)

Quita un SdkSandboxProcessDeathCallback que se agregó antes con addSdkSandboxProcessDeathCallback(java.util.concurrent.Executor, android.app.sdksandbox.SdkSandboxManager.SdkSandboxProcessDeathCallback)

Parámetros
callback SdkSandboxManager.SdkSandboxProcessDeathCallback: El SdkSandboxProcessDeathCallback que se agregó antes con SdkSandboxManager#addSdkSandboxProcessDeathCallback(Executor, SdkSandboxProcessDeathCallback). Este valor no puede ser null.

removeSyncedSharedPreferencesKeys

public void removeSyncedSharedPreferencesKeys (Set<String> keys)

Quita las llaves del conjunto de llaves que se agregaron con addSyncedSharedPreferencesKeys(java.util.Set)

Las claves que quites se borrarán de la zona de pruebas del SDK si ya se sincronizaron.

Parámetros
keys Set: Es un conjunto de nombres de claves que ya no se deben sincronizar con la zona de pruebas. Este valor no puede ser null.

requestSurfacePackage

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

Envía al SDK una solicitud de un paquete de superficie.

Después de que la aplicación cliente reciba un indicador sobre la carga correcta de un SDK y haya agregado un SurfaceView a la jerarquía de vistas, puede solicitar, de forma asíncrona, un SurfacePackage para renderizar una vista desde el SDK.

Cuando el SurfacePackage esté listo, se invocará la devolución de llamada OutcomeReceiver#onResult del receiver pasado. Esta devolución de llamada contendrá un objeto Bundle, que incluirá la clave SdkSandboxManager#EXTRA_SURFACE_PACKAGE, cuyo valor asociado es el SurfacePackage solicitado.

El params pasado debe contener las siguientes claves: EXTRA_WIDTH_IN_PIXELS, SdkSandboxManager#EXTRA_HEIGHT_IN_PIXELS, SdkSandboxManager#EXTRA_DISPLAY_ID y SdkSandboxManager#EXTRA_HOST_TOKEN. Si falta alguna de estas claves o no es válida, se arrojará una IllegalArgumentException.

Solo se puede llamar a esta API mientras el emisor se ejecuta en primer plano. Las llamadas en segundo plano harán que se muestre RequestSurfacePackageException en receiver.

Parámetros
sdkName String: Es el nombre del SDK que se cargó en la zona de pruebas del SDK. Este valor no puede ser null.

params Bundle: Son los parámetros que la aplicación cliente pasa al SDK. Este valor no puede ser null.

callbackExecutor Executor: el Executor en el que se invoca la devolución de llamada. Este valor no puede ser null. Los eventos de devolución de llamada y de objetos de escucha se envían a través de este Executor, lo que proporciona una manera fácil de controlar el subproceso que se usa. Para enviar eventos a través del subproceso principal de tu aplicación, puedes usar Context.getMainExecutor(). De lo contrario, proporciona un Executor que se envíe al subproceso correspondiente.

receiver OutcomeReceiver: Esto muestra una Bundle si se ejecuta correctamente, que contendrá la clave SdkSandboxManager#EXTRA_SURFACE_PACKAGE con un valor SurfacePackage, o RequestSurfacePackageException si se produce un error. Este valor no puede ser null.

Arroja
IllegalArgumentException si params no contiene todas las claves requeridas.

startSdkSandboxActivity.

public void startSdkSandboxActivity (Activity fromActivity, 
                IBinder sdkActivityToken)

Inicia una Activity en la zona de pruebas del SDK.

Esta función iniciará una nueva Activity en la misma tarea del fromActivity pasado y la pasará al SDK que compartió el sdkActivityToken pasado que identifica una solicitud de ese SDK para estadísticas de este Activity.

Activity no se iniciará en los siguientes casos:

  • La app que llama a esta API se encuentra en segundo plano.
  • El sdkActivityToken pasado no se asigna a una solicitud de un Activity del SDK que lo compartió con la app que realiza la llamada.
  • El SDK que compartió el sdkActivityToken pasado quitó su solicitud para este Activity.
  • Ya se creó la zona de pruebas Activity.

Parámetros
fromActivity Activity: Se usará Activity para iniciar la nueva zona de pruebas Activity mediante una llamada a Activity#startActivity(Intent) en ella. Este valor no puede ser null.

sdkActivityToken IBinder: Es el identificador que comparte el SDK que solicita el Activity. Este valor no puede ser null.

descargarSdk

public void unloadSdk (String sdkName)

Descarga un SDK que el llamador cargó anteriormente.

No se garantiza que la memoria asignada para este SDK se libere de inmediato. Todas las llamadas posteriores a requestSurfacePackage(java.lang.String, android.os.Bundle, java.util.concurrent.Executor, android.os.OutcomeReceiver) para la sdkName determinada fallarán.

Solo se puede llamar a esta API mientras el emisor se ejecuta en primer plano. Las llamadas en segundo plano generarán una SecurityException.

Parámetros
sdkName String: Es el nombre del SDK que se descargará. Este valor no puede ser null.

unregisterAppOwnedSdkSandboxInterface

public void unregisterAppOwnedSdkSandboxInterface (String name)

Cancela el registro de ERROR(/AppOwnedSdkSandboxInterfaces) para un proceso de la app.

Parámetros
name String: Es el nombre con el que se registró AppOwnedSdkSandboxInterface. Este valor no puede ser null.