已在 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 中的键的名称,会传递给 OutcomeReceiveronResult 函数(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<SandboxedSdkLoadSdkException> 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<BundleRequestSurfacePackageException> 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 中的键的名称,会传递给 OutcomeReceiveronResult 函数(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#loadSdkOutcomeReceiver

常量值: 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_DISABLEDSDK_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<SandboxedSdkLoadSdkException> 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<BundleRequestSurfacePackageException> receiver)

向 SDK 发送 Surface 包请求。

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

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

传递的 params 必须包含以下键:EXTRA_WIDTH_IN_PIXELSSdkSandboxManager#EXTRA_HEIGHT_IN_PIXELSSdkSandboxManager#EXTRA_DISPLAY_IDSdkSandboxManager#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,其中包含键 值为 SurfacePackageSdkSandboxManager#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 ActivityActivity 将通过针对它调用 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