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 沙盒终止事件的回调。 |
继承的方法 | |
---|---|
常量
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 字段中使用的键的名称,其值应定义逻辑运算符的整数 ID
来显示 SurfacePackage
。
常量值: “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()
返回的令牌
添加到视图层次结构中仅接受非 null 值来启用 ANR 报告。
常量值: “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 在后加载初始化期间遇到了错误。通过
您可以通过以下方法从 LoadSdkException
中返回的 Bundle 中获取详细信息:
传入 SdkSandboxManager#loadSdk
的 OutcomeReceiver
。
常量值: 102 (0x00000066)
LOAD_SDK_SDK_SANDBOX_DISABLED
public static final int LOAD_SDK_SDK_SANDBOX_DISABLED
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 沙盒进程不可用,可能是因为该进程已终止, 未关联或最初并未创建。
常量值: 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 已隐藏。尝试调用这些函数会导致 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 。
通过此 Executor 分派回调和监听器事件,从而让您能够轻松控制要使用的线程。如需通过应用的主线程分派事件,可以使用 Context.getMainExecutor() 。
否则,请提供分派给相应线程的 Executor 。 |
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 。 |
getSandboxedSdks
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 :要以 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
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
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
准备就绪后,系统将调用 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
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
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 。 |