已在 API 级别 33 中引入
也已在广告服务扩展 3 中引入
摘要： 嵌套类 |常量 |方法 |继承的方法

SdkSandboxManager

public final class SdkSandboxManager
extends Object

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

提供用于将 SDKs 加载到 SDK 沙盒进程，然后与之交互。

SDK 沙盒是在单独的 UID 范围内运行的 Java 进程。每个应用都有自己的 SDK 测试区进程。

应用首先需要使用 <uses-sdk-library> 标记在其清单中声明其所依赖的 SDK。应用只能将自己所依赖的 SDK 加载到 SDK 沙盒中。

摘要

嵌套类

interface SdkSandboxManager.SdkSandboxProcessDeathCallback

用于跟踪 SDK 沙盒终止事件的回调。 

常量

String EXTRA_DISPLAY_ID

要在 requestSurfacePackage(java.lang.String, android.os.Bundle, java.util.concurrent.Executor, android.os.OutcomeReceiver) 的 Bundle 字段中使用的键的名称，其值应定义逻辑运算符的整数 ID 来显示 SurfacePackage。

String EXTRA_HEIGHT_IN_PIXELS

要在 requestSurfacePackage(java.lang.String, android.os.Bundle, java.util.concurrent.Executor, android.os.OutcomeReceiver) 的 Bundle 字段中使用的键的名称，其值应定义 SurfacePackage 的整数高度（以像素为单位）。

String EXTRA_HOST_TOKEN

要在 requestSurfacePackage(java.lang.String, android.os.Bundle, java.util.concurrent.Executor, android.os.OutcomeReceiver) 的 Bundle 字段中使用的键的名称，其值应呈现 SurfaceView 后由 SurfaceView.getHostToken() 返回的令牌 添加到视图层次结构中

String EXTRA_SURFACE_PACKAGE

Bundle 中的键的名称，会传递给 OutcomeReceiver 的 onResult 函数（requestSurfacePackage(java.lang.String, android.os.Bundle, java.util.concurrent.Executor, android.os.OutcomeReceiver) 的字段），其值会显示所请求的 SurfacePackage。

String EXTRA_WIDTH_IN_PIXELS

要在 requestSurfacePackage(java.lang.String, android.os.Bundle, java.util.concurrent.Executor, android.os.OutcomeReceiver) 的 Bundle 字段中使用的键的名称，其值应定义 SurfacePackage 的整数宽度（以像素为单位）。

int LOAD_SDK_ALREADY_LOADED

SDK 已加载。

int LOAD_SDK_INTERNAL_ERROR

加载 SDK 时发生内部错误。

int LOAD_SDK_NOT_FOUND

找不到 SDK。

int LOAD_SDK_SDK_DEFINED_ERROR

加载后发生 SDK 错误。

int LOAD_SDK_SDK_SANDBOX_DISABLED

SDK 沙盒已停用。

int REQUEST_SURFACE_PACKAGE_INTERNAL_ERROR

请求 SurfacePackage 时发生内部错误。

int REQUEST_SURFACE_PACKAGE_SDK_NOT_LOADED

请求 SurfacePackage 时未加载 SDK。

int SDK_SANDBOX_PROCESS_NOT_AVAILABLE

SDK 沙盒进程不可用。

String SDK_SANDBOX_SERVICE

与 Context#getSystemService(String) 配合使用以检索 SdkSandboxManager 与属于此客户端应用的 SDK 进行交互。

int SDK_SANDBOX_STATE_DISABLED

SDK 沙盒已停用。

int SDK_SANDBOX_STATE_ENABLED_PROCESS_ISOLATION

SDK 沙盒已启用。

公共方法

void addSdkSandboxProcessDeathCallback(Executor callbackExecutor, SdkSandboxManager.SdkSandboxProcessDeathCallback callback)

添加了一个针对 SDK 沙盒生命周期事件（例如 SDK 沙盒）进行注册的回调 死亡。

void addSyncedSharedPreferencesKeys(Set<String> keys)

将密钥添加到从应用的默认 SharedPreferences 同步到 SDK 的一组密钥 沙盒

List<AppOwnedSdkSandboxInterface> getAppOwnedSdkSandboxInterfaces()

获取为应用注册的 AppOwnedSdkSandboxInterface 列表

List<SandboxedSdk> getSandboxedSdks()

获取沙盒中加载的 SDK 的相关信息。

static int getSdkSandboxState()

返回 SDK 沙盒功能的当前状态。

Set<String> getSyncedSharedPreferencesKeys()

返回从应用的默认 SharedPreferences 同步到 SDK 沙盒

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

在 SDK 沙盒 Java 进程中加载 SDK。

void registerAppOwnedSdkSandboxInterface(AppOwnedSdkSandboxInterface appOwnedSdkSandboxInterface)

为应用进程注册 AppOwnedSdkSandboxInterface。

void removeSdkSandboxProcessDeathCallback(SdkSandboxManager.SdkSandboxProcessDeathCallback callback)

移除之前使用 addSdkSandboxProcessDeathCallback(java.util.concurrent.Executor, android.app.sdksandbox.SdkSandboxManager.SdkSandboxProcessDeathCallback) 添加的 SdkSandboxProcessDeathCallback

void removeSyncedSharedPreferencesKeys(Set<String> keys)

从使用 addSyncedSharedPreferencesKeys(java.util.Set) 添加的一组键中移除键

如果已移除的密钥已经同步，系统会将其从 SDK 沙盒中清除。

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

向 SDK 发送 Surface 包请求。

void startSdkSandboxActivity(Activity fromActivity, IBinder sdkActivityToken)

在 SDK 沙盒中启动 Activity。

void unloadSdk(String sdkName)

卸载调用方之前已加载的 SDK。

void unregisterAppOwnedSdkSandboxInterface(String name)

为应用进程取消注册 ERROR(/AppOwnedSdkSandboxInterfaces)。

继承的方法

常量

EXTRA_DISPLAY_ID

已在 API 级别 34 中引入
也已在广告服务扩展 4 中引入 
public static final String EXTRA_DISPLAY_ID

要在 requestSurfacePackage(java.lang.String, android.os.Bundle, java.util.concurrent.Executor, android.os.OutcomeReceiver) 的 Bundle 字段中使用的键的名称，其值应定义逻辑运算符的整数 ID 来显示 SurfacePackage。

常量值： “android.app.sdksandbox.extra.DISPLAY_ID”

EXTRA_HEIGHT_IN_PIXELS

已在 API 级别 34 中引入
也已在广告服务扩展 4 中引入 
public static final String EXTRA_HEIGHT_IN_PIXELS

要在 requestSurfacePackage(java.lang.String, android.os.Bundle, java.util.concurrent.Executor, android.os.OutcomeReceiver) 的 Bundle 字段中使用的键的名称，其值应定义 SurfacePackage 的整数高度（以像素为单位）。

常量值： “android.app.sdksandbox.extra.HEIGHT_IN_PIXELS”

EXTRA_HOST_TOKEN

已在 API 级别 34 中引入
也已在广告服务扩展 4 中引入 
public static final String EXTRA_HOST_TOKEN

要在 requestSurfacePackage(java.lang.String, android.os.Bundle, java.util.concurrent.Executor, android.os.OutcomeReceiver) 的 Bundle 字段中使用的键的名称，其值应呈现 SurfaceView 后由 SurfaceView.getHostToken() 返回的令牌 添加到视图层次结构中仅接受非 null 值来启用 ANR 报告。

常量值： “android.app.sdksandbox.extra.HOST_TOKEN”

EXTRA_SURFACE_PACKAGE

已在 API 级别 34 中引入
也已在广告服务扩展 4 中引入 
public static final String EXTRA_SURFACE_PACKAGE

Bundle 中的键的名称，会传递给 OutcomeReceiver 的 onResult 函数（requestSurfacePackage(java.lang.String, android.os.Bundle, java.util.concurrent.Executor, android.os.OutcomeReceiver) 的字段），其值会显示所请求的 SurfacePackage。

常量值： “android.app.sdksandbox.extra.SURFACE_PACKAGE”

EXTRA_WIDTH_IN_PIXELS

已在 API 级别 34 中引入
也已在广告服务扩展 4 中引入 
public static final String EXTRA_WIDTH_IN_PIXELS

要在 requestSurfacePackage(java.lang.String, android.os.Bundle, java.util.concurrent.Executor, android.os.OutcomeReceiver) 的 Bundle 字段中使用的键的名称，其值应定义 SurfacePackage 的整数宽度（以像素为单位）。

常量值： “android.app.sdksandbox.extra.WIDTH_IN_PIXELS”

LOAD_SDK_ALREADY_LOADED

已在 API 级别 34 中引入
也已在广告服务扩展 4 中引入 
public static final int LOAD_SDK_ALREADY_LOADED

SDK 已加载。

这表示客户端应用在被调用后尝试通过调用 loadSdk(java.lang.String, android.os.Bundle, java.util.concurrent.Executor, android.os.OutcomeReceiver) 重新加载同一 SDK 已成功加载。

常量值： 101 (0x00000065)

LOAD_SDK_INTERNAL_ERROR

已在 API 级别 34 中引入
也已在广告服务扩展 4 中引入 
public static final int LOAD_SDK_INTERNAL_ERROR

加载 SDK 时出现内部错误。

这表示从客户端应用调用时发生一般性内部错误 应用。

常量值： 500 名 (0x000001f4)

LOAD_SDK_NOT_FOUND

已在 API 级别 34 中引入
也已在广告服务扩展 4 中引入 
public static final int LOAD_SDK_NOT_FOUND

找不到 SDK。

这表示客户端应用试图通过调用 loadSdk(java.lang.String, android.os.Bundle, java.util.concurrent.Executor, android.os.OutcomeReceiver) 加载不存在的 SDK。

常量值： 100 个 (0x00000064)

LOAD_SDK_SDK_DEFINED_ERROR 类中的方法

已在 API 级别 34 中引入
也已在广告服务扩展 4 中引入 
public static final int LOAD_SDK_SDK_DEFINED_ERROR

加载后发生 SDK 错误。

这表示 SDK 在后加载初始化期间遇到了错误。通过 您可以通过以下方法从 LoadSdkException 中返回的 Bundle 中获取详细信息： 传入 SdkSandboxManager#loadSdk 的 OutcomeReceiver。

常量值： 102 (0x00000066)

LOAD_SDK_SDK_SANDBOX_DISABLED

已在 API 级别 34 中引入
也已在广告服务扩展 4 中引入 
public static final int LOAD_SDK_SDK_SANDBOX_DISABLED

SDK 沙盒已停用。

这表示 SDK 沙盒已停用。任何后续尝试 这次启动也将失败。

常量值： 103 (0x00000067)

REQUEST_SURFACE_PACKAGE_INTERNAL_ERROR

已在 API 级别 34 中引入
也已在广告服务扩展 4 中引入 
public static final int REQUEST_SURFACE_PACKAGE_INTERNAL_ERROR

请求 SurfacePackage 时出现内部错误。

这表示在请求 SurfacePackage 时发生了常规内部错误。

常量值： 700 个 （0x000002bc）

REQUEST_SURFACE_PACKAGE_SDK_NOT_LOADED

已在 API 级别 34 中引入
也已在广告服务扩展 5 中引入 
public static final int REQUEST_SURFACE_PACKAGE_SDK_NOT_LOADED

请求 SurfacePackage 时未加载 SDK。

这表示正在请求 SurfacePackage 的 SDK 不是 要么是因为沙盒终止了，要么是因为最初没有加载。

常量值： 701 (0x000002bd)

SDK_SANDBOX_PROCESS_NOT_AVAILABLE

已在 API 级别 34 中引入
也已在广告服务扩展 4 中引入 
public static final int SDK_SANDBOX_PROCESS_NOT_AVAILABLE

SDK 沙盒进程不可用。

这表示 SDK 沙盒进程不可用，可能是因为该进程已终止， 未关联或最初并未创建。

常量值： 503 (0x000001f7)

SDK_SANDBOX_SERVICE

已在 API 级别 34 中引入
也已在广告服务扩展 4 中引入 
public static final String SDK_SANDBOX_SERVICE

与 Context#getSystemService(String) 配合使用以检索 SdkSandboxManager 与属于此客户端应用的 SDK 进行交互。

常量值： “sdk_sandbox”

SDK_SANDBOX_STATE_DISABLED

已在 API 级别 33 中引入
也已在广告服务扩展 3 中引入 
public static final int SDK_SANDBOX_STATE_DISABLED

SDK 沙盒已停用。

SdkSandboxManager API 已隐藏。尝试调用这些函数会导致 UnsupportedOperationException。

常量值： 0 (0x00000000)

SDK_SANDBOX_STATE_ENABLED_PROCESS_ISOLATION

已在 API 级别 33 中引入
也已在广告服务扩展 3 中引入 
public static final int SDK_SANDBOX_STATE_ENABLED_PROCESS_ISOLATION

SDK 沙盒已启用。

应用可以使用 SdkSandboxManager API 将其所依赖的 SDKs 加载到 相应的 SDK 沙盒进程。

常量值： 2 次 (0x00000002)

公共方法

addSdkSandboxProcessDeathCallback

已在 API 级别 34 中引入
也已在广告服务扩展 4 中引入 
public void addSdkSandboxProcessDeathCallback (Executor callbackExecutor, 
                SdkSandboxManager.SdkSandboxProcessDeathCallback callback)

添加了一个针对 SDK 沙盒生命周期事件（例如 SDK 沙盒）进行注册的回调 死亡。如果在调用 时尚未创建沙盒，则请求将被 创建出沙盒，此时系统会针对沙盒激活沙盒。多个 回调可以添加来检测是否终止，并且在沙盒终止时不会将其移除。

参数
callbackExecutor Executor：要在其上调用回调的 Executor。此值不能为 null。 通过此 Executor 分派回调和监听器事件，从而让您能够轻松控制要使用的线程。如需通过应用的主线程分派事件，可以使用 Context.getMainExecutor()。 否则，请提供分派给相应线程的 Executor。
callback SdkSandboxManager.SdkSandboxProcessDeathCallback：将接收 SDK 沙盒的 SdkSandboxProcessDeathCallback 和生命周期事件 此值不能为 null。

addSyncedSharedPreferencesKeys

已在 API 级别 34 中引入
也已在广告服务扩展 5 中引入 
public void addSyncedSharedPreferencesKeys (Set<String> keys)

将密钥添加到从应用的默认 SharedPreferences 同步到 SDK 的一组密钥 沙盒

同步的数据将可供 SDK 使用 SdkSandboxController.getClientSharedPreferences() API 读取。

如需停止同步使用此 API 添加的任何密钥，请使用 removeSyncedSharedPreferencesKeys(java.util.Set)。

如果应用重启，同步会中断，用户必须再次调用此 API 才能重新构建池 多个用于同步的密钥。

注意： 此类不支持跨多个进程使用。

参数
keys Set：将同步到沙盒的一组密钥。 此值不能为 null。

getAppOwnedSdkSandboxInterfaces

public List<AppOwnedSdkSandboxInterface> getAppOwnedSdkSandboxInterfaces ()

获取为应用注册的 AppOwnedSdkSandboxInterface 列表

返回
List<AppOwnedSdkSandboxInterface> 如果在映射中找不到 callInfo，则列表为空；否则为 AppOwnedSdkSandboxInterface 列表 此值不能为 null。

getSandboxedSdks

已在 API 级别 34 中引入
也已在广告服务扩展 5 中引入 
public List<SandboxedSdk> getSandboxedSdks ()

提取沙盒中加载的 SDK 的相关信息。

返回
List<SandboxedSdk> SandboxedSdk 的列表，其中包含当前加载的所有 SDK。 此值不能为 null。

getSdkSandboxState

已在 API 级别 33 中引入
也已在广告服务扩展 3 中引入 
public static int getSdkSandboxState ()

返回 SDK 沙盒功能的当前状态。

返回
int 值为 SDK_SANDBOX_STATE_DISABLED 或 SDK_SANDBOX_STATE_ENABLED_PROCESS_ISOLATION

getSyncedSharedPreferencesKeys

已在 API 级别 34 中引入
也已在广告服务扩展 5 中引入 
public Set<String> getSyncedSharedPreferencesKeys ()

返回从应用的默认 SharedPreferences 同步到 SDK 沙盒

返回
Set<String> 此值不能为 null。

loadSdk

已在 API 级别 34 中引入
也已在广告服务扩展 4 中引入 
public void loadSdk (String sdkName, 
                Bundle params, 
                Executor executor, 
                OutcomeReceiver<SandboxedSdk, LoadSdkException> receiver)

在 SDK 沙盒 Java 进程中加载 SDK。

将包含 sdkName 的 SDK 库异步加载到 SDK 沙盒进程。通过 来电者将通过 receiver 收到通知。

调用方应该已经使用 <uses-sdk-library> 标记在其清单中声明其所依赖的 SDKs。调用方只能将自己所依赖的 SDKs 加载到 SDK 中 沙盒

当客户端应用加载第一个 SDK 时，将会启动一个新的 SDK 沙盒进程 创建。如果已为客户端应用创建了沙盒，还会添加其他 SDK， 都将加载到同一沙盒中

只有当调用方在前台运行时，才能调用此 API。来自 背景将导致在 receiver 中返回 LoadSdkException。

参数
sdkName String：要加载的 SDK 的名称。 此值不能为 null。
params Bundle：要以 Bundle 的形式传递给 SDK 的其他参数 与 SDK 之间达成一致。 此值不能为 null。
executor Executor：要在其上调用接收器的 Executor。 此值不能为 null。 通过此 Executor 分派回调和监听器事件，从而让您能够轻松控制要使用的线程。如需通过应用的主线程分派事件，可以使用 Context.getMainExecutor()。 否则，请提供分派给相应线程的 Executor。
receiver OutcomeReceiver：此方法会在运行成功时收到 SandboxedSdk，也可能会收到 LoadSdkException。 此值不能为 null。

registerAppOwnedSdkSandboxInterface

public void registerAppOwnedSdkSandboxInterface (AppOwnedSdkSandboxInterface appOwnedSdkSandboxInterface)

为应用进程注册 AppOwnedSdkSandboxInterface。

注册与之前同名的 AppOwnedSdkSandboxInterface 注册接口将导致 IllegalStateException。

AppOwnedSdkSandboxInterface#getName() 是指接口的名称。

参数
appOwnedSdkSandboxInterface AppOwnedSdkSandboxInterface：要注册的 AppOwnedSdkSandboxInterface 此值不能为 null。

removeSdkSandboxProcessDeathCallback

已在 API 级别 34 中引入
也已在广告服务扩展 4 中引入 
public void removeSdkSandboxProcessDeathCallback (SdkSandboxManager.SdkSandboxProcessDeathCallback callback)

移除之前使用 addSdkSandboxProcessDeathCallback(java.util.concurrent.Executor, android.app.sdksandbox.SdkSandboxManager.SdkSandboxProcessDeathCallback) 添加的 SdkSandboxProcessDeathCallback

参数
callback SdkSandboxManager.SdkSandboxProcessDeathCallback：之前使用SdkSandboxProcessDeathCallback SdkSandboxManager#addSdkSandboxProcessDeathCallback(Executor, SdkSandboxProcessDeathCallback) 此值不能为 null。

removeSyncedSharedPreferencesKeys

已在 API 级别 34 中引入
也已在广告服务扩展 5 中引入 
public void removeSyncedSharedPreferencesKeys (Set<String> keys)

从使用 addSyncedSharedPreferencesKeys(java.util.Set) 添加的一组键中移除键

如果已移除的密钥已经同步，系统会将其从 SDK 沙盒中清除。

参数
keys Set：不应再同步到沙盒的一组密钥名称。 此值不能为 null。

requestSurfacePackage

已在 API 级别 34 中引入
也已在广告服务扩展 4 中引入 
public void requestSurfacePackage (String sdkName, 
                Bundle params, 
                Executor callbackExecutor, 
                OutcomeReceiver<Bundle, RequestSurfacePackageException> receiver)

向 SDK 发送 Surface 包请求。

客户端应用收到 SDK 加载成功的信号并 向视图层次结构添加了 SurfaceView，则可能会异步请求 一个 SurfacePackage，用于从 SDK 渲染视图。

当 SurfacePackage 准备就绪后，系统将调用 OutcomeReceiver#onResult 回调 系统会调用传递的 receiver。此回调将包含一个 Bundle 对象，该对象将包含 SdkSandboxManager#EXTRA_SURFACE_PACKAGE 键，该键的 关联的值为所请求的 SurfacePackage。

传递的 params 必须包含以下键：EXTRA_WIDTH_IN_PIXELS、SdkSandboxManager#EXTRA_HEIGHT_IN_PIXELS、 SdkSandboxManager#EXTRA_DISPLAY_ID 和 SdkSandboxManager#EXTRA_HOST_TOKEN。如果 如果有任何键缺失或无效，系统会抛出 IllegalArgumentException。

只有当调用方在前台运行时，才能调用此 API。来自 背景将导致 receiver 中返回 RequestSurfacePackageException。

参数
sdkName String：加载到 SDK 沙盒中的 SDK 的名称。 此值不能为 null。
params Bundle：客户端应用传递给 SDK 的参数。 此值不能为 null。
callbackExecutor Executor：要在其上调用回调的 Executor。此值不能为 null。 通过此 Executor 分派回调和监听器事件，从而让您能够轻松控制要使用的线程。如需通过应用的主线程分派事件，可以使用 Context.getMainExecutor()。 否则，请提供分派给相应线程的 Executor。
receiver OutcomeReceiver：在成功时返回 Bundle，其中包含键 值为 SurfacePackage 的 SdkSandboxManager#EXTRA_SURFACE_PACKAGE，或 失败时为 RequestSurfacePackageException。 此值不能为 null。
抛出
IllegalArgumentException 如果 params 未包含所有必需键，则返回此值。

startSdkSandboxActivity

已在 API 级别 34 中引入
也已在广告服务扩展 7 中引入 
public void startSdkSandboxActivity (Activity fromActivity, 
                IBinder sdkActivityToken)

在 SDK 沙盒中启动 Activity。

此函数将在传递的 fromActivity 的同一任务中启动新的 Activity，并将其传递给共享所传递的 sdkActivityToken 的 SDK， 标识来自该 SDK 的请求，用于说明此 Activity。

Activity 在以下情况下不会启动：

  • 调用此 API 的应用在后台运行。
  • 传递的 sdkActivityToken 未映射到 Activity 的请求 构成与调用方应用共享的 SDK。
  • 共享传递的 sdkActivityToken 的 SDK 移除了对此操作的请求 Activity。
  • 已创建沙盒“Activity”。

参数
fromActivity Activity：Activity 将通过针对它调用 Activity#startActivity(Intent) 来启动新的沙盒 Activity。 此值不能为 null。
sdkActivityToken IBinder：请求 Activity 的 SDK 共享的标识符。 此值不能为 null。

unloadSdk

已在 API 级别 34 中引入
也已在广告服务扩展 4 中引入 
public void unloadSdk (String sdkName)

卸载调用方之前已加载的 SDK。

我们无法保证为此 SDK 分配的内存会立即释放。全部 对 requestSurfacePackage(java.lang.String, android.os.Bundle, java.util.concurrent.Executor, android.os.OutcomeReceiver) 的后续调用 的 sdkName 将失败。

只有当调用方在前台运行时，才能调用此 API。来自 会导致抛出 SecurityException。

参数
sdkName String：要卸载的 SDK 的名称。 此值不能为 null。

unregisterAppOwnedSdkSandboxInterface

public void unregisterAppOwnedSdkSandboxInterface (String name)

为应用进程取消注册 ERROR(/AppOwnedSdkSandboxInterfaces)。

参数
name String：AppOwnedSdkSandboxInterface 注册时使用的名称。 此值不能为 null。