在 API level 33 中添加
另请参阅 Ad Services Extensions 3
摘要：嵌套类 | 常量 | 方法 | 继承的方法

SdkSandboxManager

public final class SdkSandboxManager
extends Object

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

提供 API 以将 SDK 加载到 SDK 沙盒进程中，然后与其交互。

SDK 沙盒是一个运行在单独 uid 范围内的 Java 进程。每个应用可以有自己的 SDK 沙盒进程。

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

摘要

嵌套类

接口 SdkSandboxManager.SdkSandboxProcessDeathCallback

用于跟踪 SDK 沙盒死亡事件的回调。 

常量

String EXTRA_DISPLAY_ID

在 requestSurfacePackage(java.lang.String, android.os.Bundle, java.util.concurrent.Executor, android.os.OutcomeReceiver) 的 Bundle 字段中使用的键的名称，其值应定义用于显示 SurfacePackage 的逻辑显示屏的整数 ID。
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

传递给 OutcomeReceiver 的 onResult 函数的 Bundle 中的键的名称，该键是 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 package 的请求。
void startSdkSandboxActivity(Activity fromActivity, IBinder sdkActivityToken)

在 SDK 沙盒中启动一个 Activity。
void unloadSdk(String sdkName)

卸载调用方先前加载的 SDK。
void unregisterAppOwnedSdkSandboxInterface(String name)

注销应用的 AppOwnedSdkSandboxInterfaces 进程。

继承的方法

常量

EXTRA_DISPLAY_ID

在 API level 34 中添加
另请参阅 Ad Services Extensions 4
public static final String EXTRA_DISPLAY_ID

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

Constant Value: "android.app.sdksandbox.extra.DISPLAY_ID"

EXTRA_HEIGHT_IN_PIXELS

在 API level 34 中添加
另请参阅 Ad Services Extensions 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 的整数高度（以像素为单位）。

Constant Value: "android.app.sdksandbox.extra.HEIGHT_IN_PIXELS"

EXTRA_HOST_TOKEN

在 API level 34 中添加
另请参阅 Ad Services Extensions 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 报告。

Constant Value: "android.app.sdksandbox.extra.HOST_TOKEN"

EXTRA_SURFACE_PACKAGE

在 API level 34 中添加
另请参阅 Ad Services Extensions 4
public static final String EXTRA_SURFACE_PACKAGE

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

Constant Value: "android.app.sdksandbox.extra.SURFACE_PACKAGE"

EXTRA_WIDTH_IN_PIXELS

在 API level 34 中添加
另请参阅 Ad Services Extensions 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 的整数宽度（以像素为单位）。

Constant Value: "android.app.sdksandbox.extra.WIDTH_IN_PIXELS"

LOAD_SDK_ALREADY_LOADED

在 API level 34 中添加
另请参阅 Ad Services Extensions 4
public static final int LOAD_SDK_ALREADY_LOADED

SDK 已加载。

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

Constant Value: 101 (0x00000065)

LOAD_SDK_INTERNAL_ERROR

在 API level 34 中添加
另请参阅 Ad Services Extensions 4
public static final int LOAD_SDK_INTERNAL_ERROR

加载 SDK 时发生内部错误。

这表示在应用客户端应用的调用时发生了一个通用内部错误。

Constant Value: 500 (0x000001f4)

LOAD_SDK_NOT_FOUND

在 API level 34 中添加
另请参阅 Ad Services Extensions 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。

Constant Value: 100 (0x00000064)

LOAD_SDK_SDK_DEFINED_ERROR

在 API level 34 中添加
另请参阅 Ad Services Extensions 4
public static final int LOAD_SDK_SDK_DEFINED_ERROR

SDK 加载后出错。

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

Constant Value: 102 (0x00000066)

LOAD_SDK_SDK_SANDBOX_DISABLED

在 API level 34 中添加
另请参阅 Ad Services Extensions 4
public static final int LOAD_SDK_SDK_SANDBOX_DISABLED

SDK 沙盒已停用。

这表示 SDK 沙盒已停用。在此次启动中，后续任何加载 SDK 的尝试也将失败。

Constant Value: 103 (0x00000067)

REQUEST_SURFACE_PACKAGE_INTERNAL_ERROR

在 API level 34 中添加
另请参阅 Ad Services Extensions 4
public static final int REQUEST_SURFACE_PACKAGE_INTERNAL_ERROR

请求 SurfacePackage 时发生内部错误。

这表示在请求 SurfacePackage 时发生了一个通用内部错误。

Constant Value: 700 (0x000002bc)

REQUEST_SURFACE_PACKAGE_SDK_NOT_LOADED

在 API level 34 中添加
另请参阅 Ad Services Extensions 5
public static final int REQUEST_SURFACE_PACKAGE_SDK_NOT_LOADED

请求 SurfacePackage 时 SDK 未加载。

这表示正在请求 SurfacePackage 的 SDK 未加载，可能是因为沙盒已死亡，或者最初就没有加载。

Constant Value: 701 (0x000002bd)

SDK_SANDBOX_PROCESS_NOT_AVAILABLE

在 API level 34 中添加
另请参阅 Ad Services Extensions 4
public static final int SDK_SANDBOX_PROCESS_NOT_AVAILABLE

SDK 沙盒进程不可用。

这表示 SDK 沙盒进程不可用，可能是因为它已死亡、断开连接，或者最初就没有创建。

Constant Value: 503 (0x000001f7)

SDK_SANDBOX_SERVICE

在 API level 34 中添加
另请参阅 Ad Services Extensions 4
public static final String SDK_SANDBOX_SERVICE

与 Context#getSystemService(String) 一起使用，以检索一个 SdkSandboxManager，用于与此客户端应用所属的 SDK 进行交互。

Constant Value: "sdk_sandbox"

SDK_SANDBOX_STATE_DISABLED

在 API level 33 中添加
另请参阅 Ad Services Extensions 3
public static final int SDK_SANDBOX_STATE_DISABLED

SDK 沙盒已停用。

SdkSandboxManager API 是隐藏的。尝试调用它们将导致抛出 UnsupportedOperationException。

Constant Value: 0 (0x00000000)

SDK_SANDBOX_STATE_ENABLED_PROCESS_ISOLATION

在 API level 33 中添加
另请参阅 Ad Services Extensions 3
public static final int SDK_SANDBOX_STATE_ENABLED_PROCESS_ISOLATION

SDK 沙盒已启用。

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

Constant Value: 2 (0x00000002)

公共方法

addSdkSandboxProcessDeathCallback

在 API level 34 中添加
另请参阅 Ad Services Extensions 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 level 34 中添加
另请参阅 Ad Services Extensions 5
public void addSyncedSharedPreferencesKeys (Set<String> keys)

将键添加到从应用默认 SharedPreferences 同步到 SDK 沙盒的键集合中。

同步的数据可通过 SdkSandboxController.getClientSharedPreferences() API 供 SDK 读取。

要停止同步使用此 API 添加的任何键，请使用 removeSyncedSharedPreferencesKeys(java.util.Set)。

如果应用重启，同步将中断，用户必须再次调用此 API 以重建用于同步的键池。

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

参数
keys Set: 将同步到沙盒的键集合。此值不能为 null。

getAppOwnedSdkSandboxInterfaces

public List<AppOwnedSdkSandboxInterface> getAppOwnedSdkSandboxInterfaces ()

获取为应用注册的 AppOwnedSdkSandboxInterface 列表

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

getSandboxedSdks

在 API level 34 中添加
另请参阅 Ad Services Extensions 5
public List<SandboxedSdk> getSandboxedSdks ()

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

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

getSdkSandboxState

在 API level 33 中添加
另请参阅 Ad Services Extensions 3
public static int getSdkSandboxState ()

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

返回
int 值为 SDK_SANDBOX_STATE_DISABLED 或 SDK_SANDBOX_STATE_ENABLED_PROCESS_ISOLATION

getSyncedSharedPreferencesKeys

在 API level 34 中添加
另请参阅 Ad Services Extensions 5
public Set<String> getSyncedSharedPreferencesKeys ()

返回从应用默认 SharedPreferences 同步到 SDK 沙盒的键集合。

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

loadSdk

在 API level 34 中添加
另请参阅 Ad Services Extensions 4
public void loadSdk (String sdkName, 
                Bundle params, 
                Executor executor, 
                OutcomeReceiver<SandboxedSdk, LoadSdkException> receiver)

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

将具有 sdkName 的 SDK 库异步加载到 SDK 沙盒进程中。调用方将通过 receiver 得到通知。

调用方应已在其清单中使用 <uses-sdk-library> 标签声明其依赖的 SDK。调用方只能将其依赖的 SDK 加载到 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 level 34 中添加
另请参阅 Ad Services Extensions 4
public void removeSdkSandboxProcessDeathCallback (SdkSandboxManager.SdkSandboxProcessDeathCallback callback)

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

参数
callback SdkSandboxManager.SdkSandboxProcessDeathCallback: 先前使用 SdkSandboxManager#addSdkSandboxProcessDeathCallback(Executor, SdkSandboxProcessDeathCallback) 添加的 SdkSandboxProcessDeathCallback。此值不能为 null。

removeSyncedSharedPreferencesKeys

在 API level 34 中添加
另请参阅 Ad Services Extensions 5
public void removeSyncedSharedPreferencesKeys (Set<String> keys)

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

如果已同步，则移除的键将从 SDK 沙盒中擦除。

参数
keys Set: 应不再同步到沙盒的键名称集合。此值不能为 null。

requestSurfacePackage

在 API level 34 中添加
另请参阅 Ad Services Extensions 4
public void requestSurfacePackage (String sdkName, 
                Bundle params, 
                Executor callbackExecutor, 
                OutcomeReceiver<Bundle, RequestSurfacePackageException> receiver)

向 SDK 发送 surface package 的请求。

客户端应用收到 SDK 加载成功的信号后，并将 SurfaceView 添加到视图层次结构中，它可以异步请求一个 SurfacePackage 以渲染来自 SDK 的视图。

当 SurfacePackage 准备就绪时，将调用传入的 receiver 的 OutcomeReceiver#onResult 回调。此回调将包含一个 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，其中包含键 SdkSandboxManager#EXTRA_SURFACE_PACKAGE 及其值 SurfacePackage；失败时返回 RequestSurfacePackageException。此值不能为 null。
抛出
IllegalArgumentException 如果 params 不包含所有必需的键。

startSdkSandboxActivity

在 API level 34 中添加
另请参阅 Ad Services Extensions 7
public void startSdkSandboxActivity (Activity fromActivity, 
                IBinder sdkActivityToken)

在 SDK 沙盒中启动一个 Activity。

此函数将在传入的 fromActivity 的同一任务中启动一个新的 Activity，并将其传递给共享了传入的 sdkActivityToken 的 SDK，该令牌标识了该 SDK 启动此 Activity 的请求。

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

  • 调用此 API 的应用处于后台。
  • 传入的 sdkActivityToken 未映射到共享此令牌的 SDK 向调用方应用发出的 Activity 请求。
  • 共享了传入的 sdkActivityToken 的 SDK 已移除其对此 Activity 的请求。
  • 沙盒 Activity 已创建。

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

unloadSdk

在 API level 34 中添加
另请参阅 Ad Services Extensions 4
public void unloadSdk (String sdkName)

卸载调用方先前加载的 SDK。

不保证为此 SDK 分配的内存会立即释放。此后所有针对给定 sdkName 的 requestSurfacePackage(java.lang.String, android.os.Bundle, java.util.concurrent.Executor, android.os.OutcomeReceiver) 调用都将失败。

只能在调用方在前台运行时调用此 API。从后台进行的调用将导致抛出 SecurityException。

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

unregisterAppOwnedSdkSandboxInterface

public void unregisterAppOwnedSdkSandboxInterface (String name)

注销应用的 AppOwnedSdkSandboxInterfaces 进程。

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