SdkSandboxManager

public final class SdkSandboxManager
extends Object

java.lang.Object
   ↳ 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

interface SdkSandboxManager.SdkSandboxProcessDeathCallback

A callback for tracking events SDK sandbox death. 

Constants

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.

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.

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.

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.

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.

int LOAD_SDK_ALREADY_LOADED

SDK is already loaded.

int LOAD_SDK_INTERNAL_ERROR

Internal error while loading SDK.

int LOAD_SDK_NOT_FOUND

SDK not found.

int LOAD_SDK_SDK_DEFINED_ERROR

SDK error after being loaded.

int LOAD_SDK_SDK_SANDBOX_DISABLED

SDK sandbox is disabled.

int REQUEST_SURFACE_PACKAGE_INTERNAL_ERROR

Internal error while requesting a SurfacePackage.

int REQUEST_SURFACE_PACKAGE_SDK_NOT_LOADED

SDK is not loaded while requesting a SurfacePackage.

int SDK_SANDBOX_PROCESS_NOT_AVAILABLE

SDK sandbox process is not available.

String SDK_SANDBOX_SERVICE

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

int SDK_SANDBOX_STATE_DISABLED

SDK sandbox is disabled.

int SDK_SANDBOX_STATE_ENABLED_PROCESS_ISOLATION

SDK sandbox is enabled.

Public methods

void addSdkSandboxProcessDeathCallback(Executor callbackExecutor, SdkSandboxManager.SdkSandboxProcessDeathCallback callback)

Adds 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 SharedPreferences to the SDK sandbox.

List<AppOwnedSdkSandboxInterface> getAppOwnedSdkSandboxInterfaces()

Fetches a list of AppOwnedSdkSandboxInterface registered for an app

List<SandboxedSdk> getSandboxedSdks()

Fetches information about SDKs that are loaded in the sandbox.

static int getSdkSandboxState()

Returns the current state of the availability of the SDK sandbox feature.

Set<String> getSyncedSharedPreferencesKeys()

Returns the set keys that are being synced from app's default SharedPreferences to the SDK sandbox.

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

Loads SDK in an SDK sandbox java process.

void registerAppOwnedSdkSandboxInterface(AppOwnedSdkSandboxInterface appOwnedSdkSandboxInterface)

Registers AppOwnedSdkSandboxInterface for an app process.

void removeSdkSandboxProcessDeathCallback(SdkSandboxManager.SdkSandboxProcessDeathCallback callback)

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

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 the SDK sandbox if they have been synced already.

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

Sends a request for a surface package to the SDK.

void startSdkSandboxActivity(Activity fromActivity, IBinder sdkActivityToken)

Starts an Activity in the SDK sandbox.

void unloadSdk(String sdkName)

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

void unregisterAppOwnedSdkSandboxInterface(String name)

Unregisters ERROR(/AppOwnedSdkSandboxInterfaces) for an app process.

Inherited methods

Constants

EXTRA_DISPLAY_ID

Added in Android UpsideDownCake Privacy Sandbox
Also in Ad Services Extensions 4 
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

Added in Android UpsideDownCake Privacy Sandbox
Also in Ad Services Extensions 4 
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

Added in Android UpsideDownCake Privacy Sandbox
Also in Ad Services Extensions 4 
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

Added in Android UpsideDownCake Privacy Sandbox
Also in Ad Services Extensions 4 
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

Added in Android UpsideDownCake Privacy Sandbox
Also in Ad Services Extensions 4 
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

Added in Android UpsideDownCake Privacy Sandbox
Also in Ad Services Extensions 4 
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

Added in Android UpsideDownCake Privacy Sandbox
Also in Ad Services Extensions 4 
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

Added in Android UpsideDownCake Privacy Sandbox
Also in Ad Services Extensions 4 
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

Added in Android UpsideDownCake Privacy Sandbox
Also in Ad Services Extensions 4 
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

Added in Android UpsideDownCake Privacy Sandbox
Also in Ad Services Extensions 4 
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

Added in Android UpsideDownCake Privacy Sandbox
Also in Ad Services Extensions 4 
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

Added in Android UpsideDownCake Privacy Sandbox
Also in Ad Services Extensions 5 
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

Added in Android UpsideDownCake Privacy Sandbox
Also in Ad Services Extensions 4 
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

Added in Android UpsideDownCake Privacy Sandbox
Also in Ad Services Extensions 4 
public static final String SDK_SANDBOX_SERVICE

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

Constant Value: "sdk_sandbox"

SDK_SANDBOX_STATE_DISABLED

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

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

Constant Value: 2 (0x00000002)

Public methods

addSdkSandboxProcessDeathCallback

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

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.

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 the SDK sandbox.

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.

getAppOwnedSdkSandboxInterfaces

public List<AppOwnedSdkSandboxInterface> getAppOwnedSdkSandboxInterfaces ()

Fetches a list of AppOwnedSdkSandboxInterface registered for an app

Returns
List<AppOwnedSdkSandboxInterface> empty list if callingInfo not found in map otherwise a list of AppOwnedSdkSandboxInterface 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 the current state of the availability of the SDK sandbox feature.

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 the SDK sandbox.

Returns
Set<String> This value cannot be null.

loadSdk

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

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.
receiver OutcomeReceiver: This either receives a SandboxedSdk on a successful run, or LoadSdkException. This value cannot be null.

registerAppOwnedSdkSandboxInterface

public void registerAppOwnedSdkSandboxInterface (AppOwnedSdkSandboxInterface appOwnedSdkSandboxInterface)

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

public void removeSdkSandboxProcessDeathCallback (SdkSandboxManager.SdkSandboxProcessDeathCallback callback)

Removes 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 the SDK sandbox 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)

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 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: 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.
receiver OutcomeReceiver: 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.
Throws
IllegalArgumentException if params does not contain all required keys.

startSdkSandboxActivity

public void startSdkSandboxActivity (Activity fromActivity, 
                IBinder sdkActivityToken)

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 Activity#startActivity(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

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.

unregisterAppOwnedSdkSandboxInterface

public void unregisterAppOwnedSdkSandboxInterface (String name)

Unregisters ERROR(/AppOwnedSdkSandboxInterfaces) for an app process.

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