SdkSandboxManager
public
final
class
SdkSandboxManager
extends Object
| java.lang.Object | |
| ↳ | android.app.sdksandbox.SdkSandboxManager |
提供相应 API，用于将 SDKs 加载到 SDK 沙盒进程中，然后与之进行交互。
SDK 沙盒是在单独的 uid 范围内运行的 Java 进程。每个应用都有自己的 SDK 沙盒进程。
应用首先需要使用 <uses-sdk-library> 标记在其清单中声明其所依赖的 SDK。应用只能将自身所依赖的 SDK 加载到 SDK 沙盒中。
总结
嵌套类 | |
|---|---|
interface |
SdkSandboxManager.SdkSandboxProcessDeathCallback
用于跟踪 SDK 沙盒终止事件的回调。 |
继承的方法 | |
|---|---|
常量
EXTRA_DISPLAY_ID
public static final String EXTRA_DISPLAY_ID
要在 requestSurfacePackage(java.lang.String, android.os.Bundle, java.util.concurrent.Executor, android.os.OutcomeReceiver) 的 Bundle 字段中使用的键的名称，其值应定义用于显示 SurfacePackage 的逻辑屏幕的整数 ID。
常量值："android.app.sdksandbox.extra.DISPLAY_ID"
EXTRA_HEIGHT_IN_PIXELS
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
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() 返回的令牌。要启用 ANR 报告，请仅接受非 null 值。
常量值： "android.app.sdksandbox.extra.HOST_TOKEN"
EXTRA_SURFACE_PACKAGE
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
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
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
public static final int LOAD_SDK_INTERNAL_ERROR
加载 SDK 时出现内部错误。
这表示从客户端应用进行调用时发生常规内部错误。
常量值： 500 (0x000001f4)
LOAD_SDK_NOT_FOUND
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
public static final int LOAD_SDK_SDK_DEFINED_ERROR
加载后出现 SDK 错误。
这表示 SDK 在加载后初始化期间遇到了错误。您可以通过传递到 SdkSandboxManager#loadSdk 的 OutcomeReceiver 从 LoadSdkException 中返回的 Bundle 中获取详细信息。
常量值： 102 (0x00000066)
LOAD_SDK_SDK_SANDBOX_DISABLED
public static final int LOAD_SDK_SDK_SANDBOX_DISABLED
SDK 沙盒已停用。
这表示 SDK 沙盒已停用。在此启动过程中尝试加载 SDK 的任何后续操作也将失败。
常量值： 103 (0x00000067)
REQUEST_SURFACE_PACKAGE_INTERNAL_ERROR
public static final int REQUEST_SURFACE_PACKAGE_INTERNAL_ERROR
请求 SurfacePackage 时出现内部错误。
这表示在请求 SurfacePackage 时发生了常规内部错误。
常量值： 700 (0x000002bc)
REQUEST_SURFACE_PACKAGE_SDK_NOT_LOADED 请求
public static final int REQUEST_SURFACE_PACKAGE_SDK_NOT_LOADED
请求 SurfacePackage 时未加载 SDK。
这表示系统未加载请求 SurfacePackage 的 SDK，这可能是因为沙盒已终止，或是一开始未加载。
常量值： 701 (0x000002bd)
SDK_SANDBOX_PROCESS_NOT_AVAILABLE
public static final int SDK_SANDBOX_PROCESS_NOT_AVAILABLE
SDK 沙盒进程不可用。
这表示 SDK 沙盒进程不可用，可能是因为 SDK 进程已终止、已断开连接或最初并未创建。
常量值： 503 (0x000001f7)
SDK_SANDBOX_SERVICE
public static final String SDK_SANDBOX_SERVICE
与 Context#getSystemService(String) 配合使用以检索 SdkSandboxManager，以便与属于此客户端应用的 SDK 进行交互。
常量值： "sdk_sandbox"
SDK_SANDBOX_STATE_DISABLED
public static final int SDK_SANDBOX_STATE_DISABLED
SDK 沙盒已停用。
SdkSandboxManager API 已隐藏。尝试调用这些 API 将导致 UnsupportedOperationException。
常量值： 0 (0x00000000)
SDK_SANDBOX_STATE_ENABLED_PROCESS_ISOLATION
public static final int SDK_SANDBOX_STATE_ENABLED_PROCESS_ISOLATION
SDK 沙盒已启用。
应用可以使用 SdkSandboxManager API 将所依赖的 SDKs 加载到相应的 SDK 沙盒进程中。
常量值： 2 (0x00000002)
公共方法
addSdkSandboxProcessDeathCallback
public void addSdkSandboxProcessDeathCallback (Executor callbackExecutor, SdkSandboxManager.SdkSandboxProcessDeathCallback callback)
添加了针对 SDK 沙盒生命周期事件（如 SDK 沙盒终止）注册的回调。如果在调用此方法时尚未创建沙盒，则系统将存储请求，直到创建沙盒为止，此时即会为该沙盒激活请求。可以添加多个回调来检测死亡。
| 参数 | |
|---|---|
callbackExecutor |
Executor：要在其上调用回调的 Executor。此值不能为 null。
|
callback |
SdkSandboxManager.SdkSandboxProcessDeathCallback：将接收 SDK 沙盒生命周期事件的 SdkSandboxProcessDeathCallback。
此值不能为 null。 |
addSyncedSharedPreferencesKeys
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。 |
getSandboxedSdk
public List<SandboxedSdk> getSandboxedSdks ()
获取沙盒中加载的 SDK 的相关信息。
| 开球回攻次数 | |
|---|---|
List<SandboxedSdk> |
SandboxedSdk 的列表，其中包含当前已加载的所有 SDK。
此值不能为 null。 |
getSdkSandboxState
public static int getSdkSandboxState ()
返回 SDK 沙盒功能的可用性的当前状态。
| 开球回攻次数 | |
|---|---|
int |
值为 SDK_SANDBOX_STATE_DISABLED 或 SDK_SANDBOX_STATE_ENABLED_PROCESS_ISOLATION |
getSyncedSharedPreferencesKeys
public Set<String> getSyncedSharedPreferencesKeys ()
返回从应用的默认 SharedPreferences 同步到 SDK 沙盒的已设置密钥。
| 开球回攻次数 | |
|---|---|
Set<String> |
此值不能为 null。 |
loadSdk
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：要以客户端和 SDK 商定的 Bundle 形式传递给 SDK 的附加参数。
此值不能为 null。 |
executor |
Executor：要在其上调用接收器的 Executor。此值不能为 null。
|
receiver |
OutcomeReceiver：此方法会在运行成功时收到 SandboxedSdk，或收到 LoadSdkException。
此值不能为 null。 |
注册 AppOwnedSdkSandboxInterface
public void registerAppOwnedSdkSandboxInterface (AppOwnedSdkSandboxInterface appOwnedSdkSandboxInterface)
为应用进程注册 AppOwnedSdkSandboxInterface。
如果注册与先前注册的接口同名的 AppOwnedSdkSandboxInterface，则会导致 IllegalStateException。
AppOwnedSdkSandboxInterface#getName() 是指接口的名称。
| 参数 | |
|---|---|
appOwnedSdkSandboxInterface |
AppOwnedSdkSandboxInterface：要注册的 AppOwnedSdkSandboxInterface。此值不能为 null。 |
removeSdkSandboxProcessDeathCallback
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
public void removeSyncedSharedPreferencesKeys (Set<String> keys)
从使用 addSyncedSharedPreferencesKeys(java.util.Set) 添加的一组键中移除键
已移除的密钥将从 SDK 沙盒中清除（如果已同步）。
| 参数 | |
|---|---|
keys |
Set：不应再同步到沙盒的按键名称集。
此值不能为 null。 |
requestSurfacePackage
public void requestSurfacePackage (String sdkName, Bundle params, Executor callbackExecutor, OutcomeReceiver<Bundle, RequestSurfacePackageException> receiver)
向 SDK 发送 Surface 包请求。
客户端应用收到 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。
|
receiver |
OutcomeReceiver：此方法会在成功时返回 Bundle（其中包含值为 SurfacePackage 的 SdkSandboxManager#EXTRA_SURFACE_PACKAGE 键），或者在失败时返回 RequestSurfacePackageException。
此值不能为 null。 |
| 抛出 | |
|---|---|
IllegalArgumentException |
如果 params 未包含所有必需的键，则会发生该错误。 |
startSdkSandboxActivity
public void startSdkSandboxActivity (Activity fromActivity, IBinder sdkActivityToken)
在 SDK 沙盒中启动 Activity。
此函数将在传递的 fromActivity 的同一任务中启动一个新的 Activity，并将其传递给共享所传递的 sdkActivityToken（用于标识来自该 SDK 以统计此 Activity 的请求）的 SDK。
在以下情况下，Activity 不会启动：
- 调用此 API 的应用在后台运行。
- 所传递的
sdkActivityToken未映射到与调用方应用共享该 SDK 的Activity请求。 - 共享所传递的
sdkActivityToken的 SDK 移除了其针对此Activity的请求。 - 已创建沙盒
Activity。
| 参数 | |
|---|---|
fromActivity |
Activity：Activity 将通过针对它调用 Activity#startActivity(Intent) 来启动新沙盒 Activity。此值不能为 null。 |
sdkActivityToken |
IBinder：请求 Activity 的 SDK 共享的标识符。
此值不能为 null。 |
unloadSdk
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)
为应用进程取消注册 ERROR(/AppOwnedSdkSandboxInterfaces)。
| 参数 | |
|---|---|
name |
String：注册 AppOwnedSdkSandboxInterface 时使用的名称。
此值不能为 null。 |