SdkSandboxManager
public
final
class
SdkSandboxManager
extends Object
| java.lang.Object | |
| ↳ | android.app.sdksandbox.SdkSandboxManager |
Provides APIs to load SDKs
into SDK sandbox process, and then interact with them.
SdkSandbox is a java process running in a separate uid range. Each app has its own
SDK sandbox process.
First app needs to declare SDKs it depends on in it's AndroidManifest.xml
using <uses-sdk-library> tag. App can only load SDKs it depends on into the
SdkSandbox.
Note: All APIs defined in this class are not stable and subject to change.
Summary
Nested classes | |
|---|---|
interface |
SdkSandboxManager.SdkSandboxProcessDeathCallback
A callback for tracking events SDK sandbox death. |
Public methods | |
|---|---|
void
|
addSdkSandboxProcessDeathCallback(Executor callbackExecutor, SdkSandboxManager.SdkSandboxProcessDeathCallback callback)
Add a callback which gets registered for sdk sandbox lifecycle events, such as sdk sandbox death. |
void
|
addSyncedSharedPreferencesKeys(Set<String> keys)
Adds keys to set of keys being synced from app's default |
List<SandboxedSdk>
|
getSandboxedSdks()
Fetches information about Sdks that are loaded in the sandbox. |
static
int
|
getSdkSandboxState()
Returns current state of the |
Set<String>
|
getSyncedSharedPreferencesKeys()
Returns the set keys that are being synced from app's default |
void
|
loadSdk(String sdkName, Bundle params, Executor executor, OutcomeReceiver<SandboxedSdk, LoadSdkException> receiver)
Load SDK in a SDK sandbox java process. |
void
|
removeSdkSandboxProcessDeathCallback(SdkSandboxManager.SdkSandboxProcessDeathCallback callback)
Remove an |
void
|
removeSyncedSharedPreferencesKeys(Set<String> keys)
Removes keys from set of keys that have been added using Removed keys will be erased from SdkSandbox if they have been synced already. |
void
|
requestSurfacePackage(String sdkName, Bundle params, Executor callbackExecutor, OutcomeReceiver<Bundle, RequestSurfacePackageException> receiver)
Send a request for a surface package to the sdk. |
void
|
unloadSdk(String sdkName)
Unloads an SDK that has been previously loaded by the caller. |
Inherited methods | |
|---|---|
Constants
EXTRA_DISPLAY_ID
public static final String EXTRA_DISPLAY_ID
The name of key to be used in the Bundle fields of requestSurfacePackage(java.lang.String, android.os.Bundle, java.util.concurrent.Executor, android.os.OutcomeReceiver), its value should define the integer ID of the logical
display to display the SurfacePackage.
Constant Value: "android.app.sdksandbox.extra.DISPLAY_ID"
EXTRA_HEIGHT_IN_PIXELS
public static final String EXTRA_HEIGHT_IN_PIXELS
The name of key to be used in the Bundle fields of requestSurfacePackage(java.lang.String, android.os.Bundle, java.util.concurrent.Executor, android.os.OutcomeReceiver), its value should define the integer height of the SurfacePackage in pixels.
Constant Value: "android.app.sdksandbox.extra.HEIGHT_IN_PIXELS"
EXTRA_HOST_TOKEN
public static final String EXTRA_HOST_TOKEN
The name of key to be used in the Bundle fields of requestSurfacePackage(java.lang.String, android.os.Bundle, java.util.concurrent.Executor, android.os.OutcomeReceiver), its value should present the token returned by SurfaceView.getHostToken() once the SurfaceView has been
added to the view hierarchy. Only a non-null value is accepted to enable ANR reporting.
Constant Value: "android.app.sdksandbox.extra.HOST_TOKEN"
EXTRA_SURFACE_PACKAGE
public static final String EXTRA_SURFACE_PACKAGE
The name of key in the Bundle which is passed to the onResult function of the OutcomeReceiver which is field of requestSurfacePackage(java.lang.String, android.os.Bundle, java.util.concurrent.Executor, android.os.OutcomeReceiver), its value presents the requested SurfacePackage.
Constant Value: "android.app.sdksandbox.extra.SURFACE_PACKAGE"
EXTRA_WIDTH_IN_PIXELS
public static final String EXTRA_WIDTH_IN_PIXELS
The name of key to be used in the Bundle fields of requestSurfacePackage(java.lang.String, android.os.Bundle, java.util.concurrent.Executor, android.os.OutcomeReceiver), its value should define the integer width of the SurfacePackage in pixels.
Constant Value: "android.app.sdksandbox.extra.WIDTH_IN_PIXELS"
LOAD_SDK_ALREADY_LOADED
public static final int LOAD_SDK_ALREADY_LOADED
SDK is already loaded.
This indicates that client application tried to reload the same SDk by calling loadSdk(java.lang.String, android.os.Bundle, java.util.concurrent.Executor, android.os.OutcomeReceiver) after being
successfully loaded.
Constant Value: 101 (0x00000065)
LOAD_SDK_INTERNAL_ERROR
public static final int LOAD_SDK_INTERNAL_ERROR
Internal error while loading SDK.
This indicates a generic internal error happened while applying the call from client application.
Constant Value: 500 (0x000001f4)
LOAD_SDK_NOT_FOUND
public static final int LOAD_SDK_NOT_FOUND
SDK not found.
This indicates that client application tried to load a non-existing SDK by calling loadSdk(java.lang.String, android.os.Bundle, java.util.concurrent.Executor, android.os.OutcomeReceiver).
Constant Value: 100 (0x00000064)
LOAD_SDK_SDK_DEFINED_ERROR
public static final int LOAD_SDK_SDK_DEFINED_ERROR
SDK error after being loaded.
This indicates that the SDK encountered an error during post-load initialization. The
details of this can be obtained from the Bundle returned in LoadSdkException through
the OutcomeReceiver passed in to SdkSandboxManager#loadSdk.
Constant Value: 102 (0x00000066)
LOAD_SDK_SDK_SANDBOX_DISABLED
public static final int LOAD_SDK_SDK_SANDBOX_DISABLED
SDK sandbox is disabled.
This indicates that the SDK sandbox is disabled. Any subsequent attempts to load SDKs in this boot will also fail.
Constant Value: 103 (0x00000067)
REQUEST_SURFACE_PACKAGE_INTERNAL_ERROR
public static final int REQUEST_SURFACE_PACKAGE_INTERNAL_ERROR
Internal error while requesting a SurfacePackage.
This indicates a generic internal error happened while requesting a
SurfacePackage.
Constant Value: 700 (0x000002bc)
REQUEST_SURFACE_PACKAGE_SDK_NOT_LOADED
public static final int REQUEST_SURFACE_PACKAGE_SDK_NOT_LOADED
SDK is not loaded while requesting a SurfacePackage.
This indicates that the SDK for which the SurfacePackage is being requested is not
loaded, either because the sandbox died or because it was not loaded in the first place.
Constant Value: 701 (0x000002bd)
SDK_SANDBOX_PROCESS_NOT_AVAILABLE
public static final int SDK_SANDBOX_PROCESS_NOT_AVAILABLE
Sdk sandbox process is not available.
This indicates that the sdk sandbox process is not available, either because it has died, disconnected or was not created in the first place.
Constant Value: 503 (0x000001f7)
SDK_SANDBOX_SERVICE
public static final String SDK_SANDBOX_SERVICE
Use with Context#getSystemService(String) to retrieve a SdkSandboxManager for
interacting with the SDKs belonging to this client application.
Constant Value: "sdk_sandbox"
SDK_SANDBOX_STATE_DISABLED
public static final int SDK_SANDBOX_STATE_DISABLED
SDK Sandbox is disabled.
SdkSandboxManager APIs are hidden. Attempts at calling them will result in
UnsupportedOperationException.
Constant Value: 0 (0x00000000)
SDK_SANDBOX_STATE_ENABLED_PROCESS_ISOLATION
public static final int SDK_SANDBOX_STATE_ENABLED_PROCESS_ISOLATION
SDK Sandbox is enabled.
App can use SdkSandboxManager APIs to load SDKs it depends on into the
corresponding SdkSandbox process.
Constant Value: 2 (0x00000002)
Public methods
addSdkSandboxProcessDeathCallback
public void addSdkSandboxProcessDeathCallback (Executor callbackExecutor, SdkSandboxManager.SdkSandboxProcessDeathCallback callback)
Add a callback which gets registered for sdk sandbox lifecycle events, such as sdk sandbox death. If the sandbox has not yet been created when this is called, the request will be stored until a sandbox is created, at which point it is activated for that sandbox. Multiple callbacks can be added to detect death.
| Parameters | |
|---|---|
callbackExecutor |
Executor: the Executor on which to invoke the callback
This value cannot be null.
|
callback |
SdkSandboxManager.SdkSandboxProcessDeathCallback: the SdkSandboxProcessDeathCallback which will receive sdk sandbox
lifecycle events.
This value cannot be null. |
addSyncedSharedPreferencesKeys
public void addSyncedSharedPreferencesKeys (Set<String> keys)
Adds keys to set of keys being synced from app's default SharedPreferences to
SdkSandbox.
Synced data will be available for sdks to read using the SdkSandboxController.getClientSharedPreferences() API.
To stop syncing any key that has been added using this API, use removeSyncedSharedPreferencesKeys(java.util.Set).
The sync breaks if the app restarts and user must call this API again to rebuild the pool of keys for syncing.
Note: This class does not support use across multiple processes.
| Parameters | |
|---|---|
keys |
Set: set of keys that will be synced to Sandbox.
This value cannot be null. |
getSandboxedSdks
public List<SandboxedSdk> getSandboxedSdks ()
Fetches information about Sdks that are loaded in the sandbox.
| Returns | |
|---|---|
List<SandboxedSdk> |
List of SandboxedSdk containing all currently loaded sdks
This value cannot be null. |
getSdkSandboxState
public static int getSdkSandboxState ()
Returns current state of the SdkSandbox.
| Returns | |
|---|---|
int |
Value is SDK_SANDBOX_STATE_DISABLED, or SDK_SANDBOX_STATE_ENABLED_PROCESS_ISOLATION |
getSyncedSharedPreferencesKeys
public Set<String> getSyncedSharedPreferencesKeys ()
Returns the set keys that are being synced from app's default SharedPreferences to
SdkSandbox.
| Returns | |
|---|---|
Set<String> |
This value cannot be null. |
loadSdk
public void loadSdk (String sdkName, Bundle params, Executor executor, OutcomeReceiver<SandboxedSdk, LoadSdkException> receiver)
Load SDK in a SDK sandbox java process.
It loads SDK library with sdkName to a sandbox process asynchronously, caller
should be notified through receiver.
App should already declare SDKs it depends on in its AndroidManifest using
<use-sdk-library> tag. App can only load SDKs it depends on into the SdkSandbox.
When client application loads the first SDK, a new SdkSandbox process will be
created, otherwise other SDKs will be loaded into the same sandbox which already created for
the client application.
This API may only be called while the caller is running in the foreground. Calls from the
background will result in a SecurityException being thrown.
| Parameters | |
|---|---|
sdkName |
String: name of the SDK to be loaded.
This value cannot be null. |
params |
Bundle: additional parameters to be passed to the SDK in the form of a Bundle
as agreed between the client and the SDK.
This value cannot be null. |
executor |
Executor: the Executor on which to invoke the receiver.
This value cannot be null.
|
receiver |
OutcomeReceiver: This either returns a SandboxedSdk on a successful run, or LoadSdkException.
This value cannot be null. |
removeSdkSandboxProcessDeathCallback
public void removeSdkSandboxProcessDeathCallback (SdkSandboxManager.SdkSandboxProcessDeathCallback callback)
Remove an SdkSandboxProcessDeathCallback that was previously added using addSdkSandboxProcessDeathCallback(java.util.concurrent.Executor, android.app.sdksandbox.SdkSandboxManager.SdkSandboxProcessDeathCallback)
| Parameters | |
|---|---|
callback |
SdkSandboxManager.SdkSandboxProcessDeathCallback: the SdkSandboxProcessDeathCallback which was previously added using
SdkSandboxManager#addSdkSandboxProcessDeathCallback(Executor,
SdkSandboxProcessDeathCallback)
This value cannot be null. |
removeSyncedSharedPreferencesKeys
public void removeSyncedSharedPreferencesKeys (Set<String> keys)
Removes keys from set of keys that have been added using addSyncedSharedPreferencesKeys(java.util.Set)
Removed keys will be erased from SdkSandbox if they have been synced already.
| Parameters | |
|---|---|
keys |
Set: set of key names that should no longer be synced to Sandbox.
This value cannot be null. |
requestSurfacePackage
public void requestSurfacePackage (String sdkName, Bundle params, Executor callbackExecutor, OutcomeReceiver<Bundle, RequestSurfacePackageException> receiver)
Send a request for a surface package to the sdk.
After client application receives a signal about a successful SDK loading, and has added a
SurfaceView to the view hierarchy, it may asynchronously request a
SurfacePackage to render a view from the SDK.
When the SurfacePackage is ready, onResult function of the receiver will be called with Bundle, that bundle will contain the key EXTRA_SURFACE_PACKAGE with value present the requested SurfacePackage.
This API may only be called while the caller is running in the foreground. Calls from the
background will result in a SecurityException being thrown.
| Parameters | |
|---|---|
sdkName |
String: name of the SDK loaded into sdk sandbox.
This value cannot be null. |
params |
Bundle: the parameters which the client application passes to the SDK, it should
contain the following params: (EXTRA_WIDTH_IN_PIXELS, EXTRA_HEIGHT_IN_PIXELS,
EXTRA_DISPLAY_ID, EXTRA_HOST_TOKEN). If any of these params is missing, an
IllegalArgumentException will be thrown. Any additional parameters may be passed as
agreed between the client and the SDK.
This value cannot be null. |
callbackExecutor |
Executor: the Executor on which to invoke the callback
This value cannot be null.
|
receiver |
OutcomeReceiver: This either returns a Bundle on success which should contain the key
EXTRA_SURFACE_PACKAGE with value of SurfacePackage response, or RequestSurfacePackageException on failure.
This value cannot be null. |
| Throws | |
|---|---|
IllegalArgumentException |
if any of the following params (EXTRA_WIDTH_IN_PIXELS, EXTRA_HEIGHT_IN_PIXELS, EXTRA_DISPLAY_ID, EXTRA_HOST_TOKEN) are missing from the Bundle or passed with the wrong value or type. |
unloadSdk
public void unloadSdk (String sdkName)
Unloads an SDK that has been previously loaded by the caller.
It is not guaranteed that the memory allocated for this SDK will be freed immediately. All
subsequent calls to requestSurfacePackage(java.lang.String, android.os.Bundle, java.util.concurrent.Executor, android.os.OutcomeReceiver)
for the given sdkName will fail.
This API may only be called while the caller is running in the foreground. Calls from the
background will result in a SecurityException being thrown.
| Parameters | |
|---|---|
sdkName |
String: name of the SDK to be unloaded.
This value cannot be null. |
| Throws | |
|---|---|
IllegalArgumentException |
if the SDK is not loaded. |
Content and code samples on this page are subject to the licenses described in the Content License. Java and OpenJDK are trademarks or registered trademarks of Oracle and/or its affiliates.
Last updated 2023-01-26 UTC.