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 報告功能。
常數值:「android.app.sdksandbox.extra.HOST_TOKEN」
EXTRA_SURFACE_套件
public static final String EXTRA_SURFACE_PACKAGE
套件中的鍵名稱會傳遞至 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_錯誤
public static final int LOAD_SDK_INTERNAL_ERROR
載入 SDK 時發生內部錯誤。
這表示在從用戶端應用程式套用呼叫時發生了一般內部錯誤。
常數值:500 (0x000001f4)
LOAD_SDK_未找到
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_錯誤
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 沙箱已停用。日後如果嘗試在這項啟動程序中載入 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_已停用
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 。回呼和事件監聽器會透過這個 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> |
如果無法在對應中找到呼叫 Info 或 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 :要傳遞至 SDK 的其他參數,格式為 Bundle (如用戶端與 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 :先前使用 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。
當用戶端應用程式收到 SDK 成功載入的信號,並將 SurfaceView
新增至檢視區塊階層後,則可能會以非同步方式要求 SurfacePackage
,以顯示來自 SDK 的檢視畫面。
SurfacePackage
準備就緒後,系統會叫用已傳遞 receiver
的 OutcomeReceiver#onResult
回呼。這個回呼會包含 Bundle
物件,其中包含與要求 SurfacePackage
相關聯的值 SdkSandboxManager#EXTRA_SURFACE_PACKAGE
。
傳遞的 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
,並傳遞至共用的 SDK,該 SDK 會識別來自該 SDK 的要求,藉此定義此 Activity
。sdkActivityToken
在下列情況下,Activity
不會啟動:
- 呼叫這個 API 的應用程式位於背景。
- 傳遞的
sdkActivityToken
不會對應至與呼叫端應用程式共用的 SDK 形式的Activity
要求表單。 - 共用傳遞
sdkActivityToken
的 SDK 移除了自身對這個Activity
的要求。 - 沙箱
Activity
已建立。
參數 | |
---|---|
fromActivity |
Activity :會向 Activity 呼叫 Activity#startActivity(Intent) ,藉此啟動新的沙箱 Activity 。此值不能為 null 。 |
sdkActivityToken |
IBinder :要求 Activity 的 SDK 共用的 ID。此值不能為 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 。 |
取消註冊 AppOwnedSdkSandboxInterface
public void unregisterAppOwnedSdkSandboxInterface (String name)
取消註冊應用程式程序的 ERROR(/AppOwnedSdkSandboxInterfaces)
。
參數 | |
---|---|
name |
String :用來註冊 AppOwnedSdkSandboxInterface 的名稱。此值不能為 null 。 |