SdkSandboxManager
class SdkSandboxManager
kotlin.Any | |
↳ | android.app.sdksandbox.SdkSandboxManager |
Provides APIs to load SDKs
into the SDK sandbox process, and then interact with them.
SDK sandbox is a java process running in a separate uid range. Each app may have its own SDK sandbox process.
The app first needs to declare SDKs it depends on in its manifest using the <uses-sdk-library>
tag. Apps may only load SDKs they depend on into the SDK sandbox.
Summary
Nested classes | |
---|---|
abstract |
A callback for tracking events SDK sandbox death. |
Constants | |
---|---|
static String |
The name of key to be used in the Bundle fields of |
static String |
The name of key to be used in the Bundle fields of |
static String |
The name of key to be used in the Bundle fields of |
static String |
The name of key in the Bundle which is passed to the |
static String |
The name of key to be used in the Bundle fields of |
static Int |
SDK is already loaded. |
static Int |
Internal error while loading SDK. |
static Int |
SDK not found. |
static Int |
SDK error after being loaded. |
static Int |
SDK sandbox is disabled. |
static Int |
Internal error while requesting a |
static Int |
SDK is not loaded while requesting a |
static Int |
SDK sandbox process is not available. |
static String |
Use with |
static Int |
SDK sandbox is disabled. |
static Int |
SDK sandbox is enabled. |
Public methods | |
---|---|
Unit |
addSdkSandboxProcessDeathCallback(callbackExecutor: Executor, callback: SdkSandboxManager.SdkSandboxProcessDeathCallback) Adds a callback which gets registered for SDK sandbox lifecycle events, such as SDK sandbox death. |
Unit |
Adds keys to set of keys being synced from app's default |
MutableList<AppOwnedSdkSandboxInterface!> |
Fetches a list of |
MutableList<SandboxedSdk!> |
Fetches information about SDKs that are loaded in the sandbox. |
static Int |
Returns the current state of the availability of the SDK sandbox feature. |
MutableSet<String!> |
Returns the set keys that are being synced from app's default |
Unit |
loadSdk(sdkName: String, params: Bundle, executor: Executor, receiver: OutcomeReceiver<SandboxedSdk!, LoadSdkException!>) Loads SDK in an SDK sandbox java process. |
Unit |
registerAppOwnedSdkSandboxInterface(appOwnedSdkSandboxInterface: AppOwnedSdkSandboxInterface) Registers |
Unit |
Removes an |
Unit |
Removes keys from set of keys that have been added using |
Unit |
requestSurfacePackage(sdkName: String, params: Bundle, callbackExecutor: Executor, receiver: OutcomeReceiver<Bundle!, RequestSurfacePackageException!>) Sends a request for a surface package to the SDK. |
Unit |
startSdkSandboxActivity(fromActivity: Activity, sdkActivityToken: IBinder) Starts an |
Unit |
Unloads an SDK that has been previously loaded by the caller. |
Unit |
Unregisters |
Constants
EXTRA_DISPLAY_ID
static valEXTRA_DISPLAY_ID: String
Deprecated: Parameter for requestSurfacePackage(java.lang.String,android.os.Bundle,java.util.concurrent.Executor,android.os.OutcomeReceiver)
which is getting deprecated.
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
.
Value: "android.app.sdksandbox.extra.DISPLAY_ID"
EXTRA_HEIGHT_IN_PIXELS
static valEXTRA_HEIGHT_IN_PIXELS: String
Deprecated: Parameter for requestSurfacePackage(java.lang.String,android.os.Bundle,java.util.concurrent.Executor,android.os.OutcomeReceiver)
which is getting deprecated.
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.
Value: "android.app.sdksandbox.extra.HEIGHT_IN_PIXELS"
EXTRA_HOST_TOKEN
static valEXTRA_HOST_TOKEN: String
Deprecated: Parameter for requestSurfacePackage(java.lang.String,android.os.Bundle,java.util.concurrent.Executor,android.os.OutcomeReceiver)
which is getting deprecated.
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 android.view.SurfaceView#getHostToken()
once the android.view.SurfaceView
has been added to the view hierarchy. Only a non-null value is accepted to enable ANR reporting.
Value: "android.app.sdksandbox.extra.HOST_TOKEN"
EXTRA_SURFACE_PACKAGE
static valEXTRA_SURFACE_PACKAGE: String
Deprecated: Parameter for requestSurfacePackage(java.lang.String,android.os.Bundle,java.util.concurrent.Executor,android.os.OutcomeReceiver)
which is getting deprecated.
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
.
Value: "android.app.sdksandbox.extra.SURFACE_PACKAGE"
EXTRA_WIDTH_IN_PIXELS
static valEXTRA_WIDTH_IN_PIXELS: String
Deprecated: Parameter for requestSurfacePackage(java.lang.String,android.os.Bundle,java.util.concurrent.Executor,android.os.OutcomeReceiver)
which is getting deprecated.
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.
Value: "android.app.sdksandbox.extra.WIDTH_IN_PIXELS"
LOAD_SDK_ALREADY_LOADED
static val LOAD_SDK_ALREADY_LOADED: Int
SDK is already loaded.
This indicates that client application tried to reload the same SDK by calling android.app.sdksandbox.SdkSandboxManager#loadSdk(java.lang.String,android.os.Bundle,java.util.concurrent.Executor,android.os.OutcomeReceiver)
after being successfully loaded.
Value: 101
LOAD_SDK_INTERNAL_ERROR
static val LOAD_SDK_INTERNAL_ERROR: Int
Internal error while loading SDK.
This indicates a generic internal error happened while applying the call from client application.
Value: 500
LOAD_SDK_NOT_FOUND
static val LOAD_SDK_NOT_FOUND: Int
SDK not found.
This indicates that client application tried to load a non-existing SDK by calling android.app.sdksandbox.SdkSandboxManager#loadSdk(java.lang.String,android.os.Bundle,java.util.concurrent.Executor,android.os.OutcomeReceiver)
.
Value: 100
LOAD_SDK_SDK_DEFINED_ERROR
static val LOAD_SDK_SDK_DEFINED_ERROR: Int
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
.
Value: 102
LOAD_SDK_SDK_SANDBOX_DISABLED
static val LOAD_SDK_SDK_SANDBOX_DISABLED: Int
SDK sandbox is disabled.
This indicates that the SDK sandbox is disabled. Any subsequent attempts to load SDKs in this boot will also fail.
Value: 103
REQUEST_SURFACE_PACKAGE_INTERNAL_ERROR
static val REQUEST_SURFACE_PACKAGE_INTERNAL_ERROR: Int
Internal error while requesting a SurfacePackage
.
This indicates a generic internal error happened while requesting a SurfacePackage
.
Value: 700
REQUEST_SURFACE_PACKAGE_SDK_NOT_LOADED
static val REQUEST_SURFACE_PACKAGE_SDK_NOT_LOADED: Int
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.
Value: 701
SDK_SANDBOX_PROCESS_NOT_AVAILABLE
static val SDK_SANDBOX_PROCESS_NOT_AVAILABLE: Int
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.
Value: 503
SDK_SANDBOX_SERVICE
static val SDK_SANDBOX_SERVICE: String
Use with Context#getSystemService(String)
to retrieve an SdkSandboxManager
for interacting with the SDKs belonging to this client application.
Value: "sdk_sandbox"
SDK_SANDBOX_STATE_DISABLED
static val SDK_SANDBOX_STATE_DISABLED: Int
SDK sandbox is disabled.
SdkSandboxManager
APIs are hidden. Attempts at calling them will result in UnsupportedOperationException
.
Value: 0
SDK_SANDBOX_STATE_ENABLED_PROCESS_ISOLATION
static val SDK_SANDBOX_STATE_ENABLED_PROCESS_ISOLATION: Int
SDK sandbox is enabled.
App can use SdkSandboxManager
APIs to load SDKs
it depends on into the corresponding SDK sandbox process.
Value: 2
Public methods
addSdkSandboxProcessDeathCallback
fun addSdkSandboxProcessDeathCallback(
callbackExecutor: Executor,
callback: SdkSandboxManager.SdkSandboxProcessDeathCallback
): Unit
Adds 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 and will not be removed when the sandbox dies.
Parameters | |
---|---|
callbackExecutor |
Executor: the Executor on which to invoke the callback This value cannot be null . Callback and listener events are dispatched through this Executor , providing an easy way to control which thread is used. To dispatch events through the main thread of your application, you can use Context.getMainExecutor() . Otherwise, provide an Executor that dispatches to an appropriate thread. |
callback |
SdkSandboxManager.SdkSandboxProcessDeathCallback: the SdkSandboxProcessDeathCallback which will receive SDK sandbox lifecycle events. This value cannot be null . |
addSyncedSharedPreferencesKeys
fun addSyncedSharedPreferencesKeys(: MutableSet<String!>): Unit
Adds keys to set of keys being synced from app's default SharedPreferences
to the SDK sandbox.
Synced data will be available for SDKs to read using the android.app.sdksandbox.sdkprovider.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 |
MutableSet<String!>: set of keys that will be synced to Sandbox. This value cannot be null . |
getAppOwnedSdkSandboxInterfaces
fun getAppOwnedSdkSandboxInterfaces(): MutableList<AppOwnedSdkSandboxInterface!>
Fetches a list of AppOwnedSdkSandboxInterface
registered for an app
Return | |
---|---|
MutableList<AppOwnedSdkSandboxInterface!> |
empty list if callingInfo not found in map otherwise a list of AppOwnedSdkSandboxInterface This value cannot be null . |
getSandboxedSdks
fun getSandboxedSdks(): MutableList<SandboxedSdk!>
Fetches information about SDKs that are loaded in the sandbox.
Return | |
---|---|
MutableList<SandboxedSdk!> |
List of SandboxedSdk containing all currently loaded SDKs. This value cannot be null . |
getSdkSandboxState
static fun getSdkSandboxState(): Int
Returns the current state of the availability of the SDK sandbox feature.
Return | |
---|---|
Int |
Value is android.app.sdksandbox.SdkSandboxManager#SDK_SANDBOX_STATE_DISABLED , or android.app.sdksandbox.SdkSandboxManager#SDK_SANDBOX_STATE_ENABLED_PROCESS_ISOLATION |
getSyncedSharedPreferencesKeys
fun getSyncedSharedPreferencesKeys(): MutableSet<String!>
Returns the set keys that are being synced from app's default SharedPreferences
to the SDK sandbox.
Return | |
---|---|
MutableSet<String!> |
This value cannot be null . |
loadSdk
fun loadSdk(
sdkName: String,
params: Bundle,
executor: Executor,
receiver: OutcomeReceiver<SandboxedSdk!, LoadSdkException!>
): Unit
Loads SDK in an SDK sandbox java process.
Loads SDK library with sdkName
to an SDK sandbox process asynchronously. The caller will be notified through the receiver
.
The caller should already declare SDKs
it depends on in its manifest using <uses-sdk-library>
tag. The caller may only load SDKs
it depends on into the SDK sandbox.
When the client application loads the first SDK, a new SDK sandbox process will be created. If a sandbox has already been created for the client application, additional SDKs will be loaded into the same sandbox.
This API may only be called while the caller is running in the foreground. Calls from the background will result in returning LoadSdkException
in the receiver
.
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 . Callback and listener events are dispatched through this Executor , providing an easy way to control which thread is used. To dispatch events through the main thread of your application, you can use Context.getMainExecutor() . Otherwise, provide an Executor that dispatches to an appropriate thread. |
receiver |
OutcomeReceiver<SandboxedSdk!, LoadSdkException!>: This either receives a SandboxedSdk on a successful run, or LoadSdkException . This value cannot be null . |
registerAppOwnedSdkSandboxInterface
fun registerAppOwnedSdkSandboxInterface(appOwnedSdkSandboxInterface: AppOwnedSdkSandboxInterface): Unit
Registers AppOwnedSdkSandboxInterface
for an app process.
Registering an AppOwnedSdkSandboxInterface
that has same name as a previously registered interface will result in IllegalStateException
.
AppOwnedSdkSandboxInterface#getName()
refers to the name of the interface.
Parameters | |
---|---|
appOwnedSdkSandboxInterface |
AppOwnedSdkSandboxInterface: the AppOwnedSdkSandboxInterface to be registered This value cannot be null . |
removeSdkSandboxProcessDeathCallback
fun removeSdkSandboxProcessDeathCallback(callback: SdkSandboxManager.SdkSandboxProcessDeathCallback): Unit
Removes an SdkSandboxProcessDeathCallback
that was previously added using android.app.sdksandbox.SdkSandboxManager#addSdkSandboxProcessDeathCallback(java.util.concurrent.Executor,android.app.sdksandbox.SdkSandboxManager.SdkSandboxProcessDeathCallback)
Parameters | |
---|---|
callback |
SdkSandboxManager.SdkSandboxProcessDeathCallback: the SdkSandboxProcessDeathCallback which was previously added using SdkSandboxManager#addSdkSandboxProcessDeathCallback(Executor, This value cannot be null . |
removeSyncedSharedPreferencesKeys
fun removeSyncedSharedPreferencesKeys(: MutableSet<String!>): Unit
Removes keys from set of keys that have been added using addSyncedSharedPreferencesKeys(java.util.Set)
Removed keys will be erased from the SDK sandbox if they have been synced already.
Parameters | |
---|---|
keys |
MutableSet<String!>: set of key names that should no longer be synced to Sandbox. This value cannot be null . |
requestSurfacePackage
funrequestSurfacePackage(
sdkName: String,
params: Bundle,
callbackExecutor: Executor,
receiver: OutcomeReceiver<Bundle!, RequestSurfacePackageException!>
): Unit
Deprecated: This method will no longer be supported through SdkSandboxManager
. Please consider using androidx.privacysandbox library as an alternative
Sends a request for a surface package to the SDK.
After the client application receives a signal about a successful SDK loading, and has added a android.view.SurfaceView
to the view hierarchy, it may asynchronously request a SurfacePackage
to render a view from the SDK.
When the SurfacePackage
is ready, the OutcomeReceiver#onResult
callback of the passed receiver
will be invoked. This callback will contain a Bundle
object, which will contain the key SdkSandboxManager#EXTRA_SURFACE_PACKAGE
whose associated value is the requested SurfacePackage
.
The passed params
must contain the following keys: android.app.sdksandbox.SdkSandboxManager#EXTRA_WIDTH_IN_PIXELS
, SdkSandboxManager#EXTRA_HEIGHT_IN_PIXELS
, SdkSandboxManager#EXTRA_DISPLAY_ID
and SdkSandboxManager#EXTRA_HOST_TOKEN
. If any of these keys are missing or invalid, an IllegalArgumentException
will be thrown.
This API may only be called while the caller is running in the foreground. Calls from the background will result in returning RequestSurfacePackageException in the receiver
.
Parameters | |
---|---|
sdkName |
String: name of the SDK loaded into the SDK sandbox. This value cannot be null . |
params |
Bundle: the parameters which the client application passes to the SDK. This value cannot be null . |
callbackExecutor |
Executor: the Executor on which to invoke the callback This value cannot be null . Callback and listener events are dispatched through this Executor , providing an easy way to control which thread is used. To dispatch events through the main thread of your application, you can use Context.getMainExecutor() . Otherwise, provide an Executor that dispatches to an appropriate thread. |
receiver |
OutcomeReceiver<Bundle!, RequestSurfacePackageException!>: This either returns a Bundle on success which will contain the key SdkSandboxManager#EXTRA_SURFACE_PACKAGE with a SurfacePackage value, or RequestSurfacePackageException on failure. This value cannot be null . |
Exceptions | |
---|---|
java.lang.IllegalArgumentException |
if params does not contain all required keys. |
startSdkSandboxActivity
fun startSdkSandboxActivity(
fromActivity: Activity,
sdkActivityToken: IBinder
): Unit
Starts an Activity
in the SDK sandbox.
This function will start a new Activity
in the same task of the passed fromActivity
and pass it to the SDK that shared the passed sdkActivityToken
that identifies a request from that SDK to stat this Activity
.
The Activity
will not start in the following cases:
- The App calling this API is in the background.
- The passed
sdkActivityToken
does not map to a request for anActivity
form the SDK that shared it with the caller app. - The SDK that shared the passed
sdkActivityToken
removed its request for thisActivity
. - The sandbox
Activity
is already created.
Parameters | |
---|---|
fromActivity |
Activity: the Activity will be used to start the new sandbox Activity by calling android.app.Activity#startActivity(android.content.Intent) against it. This value cannot be null . |
sdkActivityToken |
IBinder: the identifier that is shared by the SDK which requests the Activity . This value cannot be null . |
unloadSdk
fun unloadSdk(sdkName: String): Unit
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 . |
unregisterAppOwnedSdkSandboxInterface
fun unregisterAppOwnedSdkSandboxInterface(name: String): Unit
Unregisters AppOwnedSdkSandboxInterface
s for an app process.
Parameters | |
---|---|
name |
String: the name under which AppOwnedSdkSandboxInterface was registered. This value cannot be null . |