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 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.
static String

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.
static String

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.
static String

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.
static String

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.
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 SurfacePackage.
static Int

SDK is not loaded while requesting a SurfacePackage.
static Int

SDK sandbox process is not available.
static String

Use with Context#getSystemService(String) to retrieve an SdkSandboxManager for interacting with the SDKs belonging to this client application.
static Int

SDK sandbox is disabled.
static Int

SDK sandbox is enabled.
Public methods
Unit

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 SharedPreferences to the SDK sandbox.
MutableList<AppOwnedSdkSandboxInterface!>

Fetches a list of AppOwnedSdkSandboxInterface registered for an app
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 SharedPreferences to the SDK sandbox.
Unit
loadSdk(sdkName: String, params: Bundle, executor: Executor, receiver: OutcomeReceiver<SandboxedSdk!, LoadSdkException!>)

Loads SDK in an SDK sandbox java process.
Unit

Registers AppOwnedSdkSandboxInterface for an app process.
Unit

Removes an SdkSandboxProcessDeathCallback that was previously added using android.app.sdksandbox.SdkSandboxManager#addSdkSandboxProcessDeathCallback(java.util.concurrent.Executor,android.app.sdksandbox.SdkSandboxManager.SdkSandboxProcessDeathCallback)
Unit

Removes keys from set of keys that have been added using addSyncedSharedPreferencesKeys(java.util.Set)

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 Activity in the SDK sandbox.
Unit
unloadSdk(sdkName: String)

Unloads an SDK that has been previously loaded by the caller.
Unit

Unregisters AppOwnedSdkSandboxInterfaces for an app process.

Constants

EXTRA_DISPLAY_ID

Added in API level 34
Also in Ad Services Extensions 4
Deprecated in API level 36
static val EXTRA_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

Added in API level 34
Also in Ad Services Extensions 4
Deprecated in API level 36
static val EXTRA_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

Added in API level 34
Also in Ad Services Extensions 4
Deprecated in API level 36
static val EXTRA_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

Added in API level 34
Also in Ad Services Extensions 4
Deprecated in API level 36
static val EXTRA_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

Added in API level 34
Also in Ad Services Extensions 4
Deprecated in API level 36
static val EXTRA_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

Added in API level 34
Also in Ad Services Extensions 4
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

Added in API level 34
Also in Ad Services Extensions 4
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

Added in API level 34
Also in Ad Services Extensions 4
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

Added in API level 34
Also in Ad Services Extensions 4
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

Added in API level 34
Also in Ad Services Extensions 4
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

Added in API level 34
Also in Ad Services Extensions 4
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

Added in API level 34
Also in Ad Services Extensions 5
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

Added in API level 34
Also in Ad Services Extensions 4
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

Added in API level 34
Also in Ad Services Extensions 4
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

Added in API level 33
Also in Ad Services Extensions 3
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

Added in API level 33
Also in Ad Services Extensions 3
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

Added in API level 34
Also in Ad Services Extensions 4
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

Added in API level 34
Also in Ad Services Extensions 5
fun addSyncedSharedPreferencesKeys(keys: 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

Added in API level 35
Also in Ad Services Extensions 8
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

Added in API level 34
Also in Ad Services Extensions 5
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

Added in API level 33
Also in Ad Services Extensions 3
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

Added in API level 34
Also in Ad Services Extensions 5
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

Added in API level 34
Also in Ad Services Extensions 4
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

Added in API level 35
Also in Ad Services Extensions 8
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

Added in API level 34
Also in Ad Services Extensions 4
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

Added in API level 34
Also in Ad Services Extensions 5
fun removeSyncedSharedPreferencesKeys(keys: 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

Added in API level 34
Also in Ad Services Extensions 4
Deprecated in API level 36
fun requestSurfacePackage(
    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

Added in API level 34
Also in Ad Services Extensions 7
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 an Activity form the SDK that shared it with the caller app.
  • The SDK that shared the passed sdkActivityToken removed its request for this Activity.
  • 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

Added in API level 34
Also in Ad Services Extensions 4
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

Added in API level 35
Also in Ad Services Extensions 8
fun unregisterAppOwnedSdkSandboxInterface(name: String): Unit

Unregisters AppOwnedSdkSandboxInterfaces for an app process.

Parameters
name String: the name under which AppOwnedSdkSandboxInterface was registered. This value cannot be null.