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 沙箱死亡事件的回呼。 

常數

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 函式，也就是 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。

void startSdkSandboxActivity(Activity fromActivity, IBinder sdkActivityToken)

在 SDK 沙箱中啟動 Activity。
void unloadSdk(String sdkName)

卸載呼叫端先前載入的 SDK。
void unregisterAppOwnedSdkSandboxInterface(String name)

取消註冊應用程式程序的 ERROR(/AppOwnedSdkSandboxInterfaces)。

繼承方法

常數

EXTRA_DISPLAY_ID

已新增至 API 級別 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。

常數值：「android.app.sdksandbox.extra.DISPLAY_ID」

EXTRA_HEIGHT_IN_PIXELS

已新增至 API 級別 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 的整數高度 (以像素為單位)。

常數值：「android.app.sdksandbox.extra.HEIGHT_IN_PIXELS」

EXTRA_HOST_TOKEN

已新增至 API 級別 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() 傳回的權杖。系統僅接受非空值，才能啟用 ANR 報告功能。

常數值：「android.app.sdksandbox.extra.HOST_TOKEN」

EXTRA_SURFACE_套件

已新增至 API 級別 34
Ad Services Extensions 4 也已納入
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

已新增至 API 級別 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 的整數寬度 (以像素為單位)。

常數值：「android.app.sdksandbox.extra.WIDTH_IN_PIXELS」

LOAD_SDK_ALREADY_LOADED

已新增至 API 級別 34
Ad Services Extensions 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_錯誤

已新增至 API 級別 34
Ad Services Extensions 4 也已納入
public static final int LOAD_SDK_INTERNAL_ERROR

載入 SDK 時發生內部錯誤。

這表示在從用戶端應用程式套用呼叫時發生了一般內部錯誤。

常數值：500 (0x000001f4)

LOAD_SDK_未找到

已新增至 API 級別 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。

常數值：100 (0x00000064)

LOAD_SDK_SDK_DEFINED_錯誤

已新增至 API 級別 34
Ad Services Extensions 4 也已納入
public static final int LOAD_SDK_SDK_DEFINED_ERROR

載入後發生 SDK 錯誤。

這表示 SDK 在載入後初始化期間發生錯誤。您可以從 LoadSdkException 傳回的 Bundle 中，透過傳入 SdkSandboxManager#loadSdk 的 OutcomeReceiver 取得相關詳細資料。

常數值：102 (0x00000066)

LOAD_SDK_SDK_SANDBOX_DISABLED

已新增至 API 級別 34
Ad Services Extensions 4 也已納入
public static final int LOAD_SDK_SDK_SANDBOX_DISABLED

SDK 沙箱已停用。

這表示 SDK 沙箱已停用。日後如果嘗試在這項啟動程序中載入 SDK，系統也會失敗。

常數值：103 (0x00000067)

REQUEST_SURFACE_PACKAGE_INTERNAL_ERROR

已新增至 API 級別 34
Ad Services Extensions 4 也已納入
public static final int REQUEST_SURFACE_PACKAGE_INTERNAL_ERROR

要求 SurfacePackage 時發生內部錯誤。

這表示在要求 SurfacePackage 時發生了一般內部錯誤。

常數值：700 (0x000002bc)

REQUEST_SURFACE_PACKAGE_SDK_NOT_LOADED

已新增至 API 級別 34
Ad Services Extensions 5 也已納入
public static final int REQUEST_SURFACE_PACKAGE_SDK_NOT_LOADED

要求 SurfacePackage 時未載入 SDK。

這表示由於沙箱已經終止，或是並未一開始就載入，因此未載入要求 SurfacePackage 的 SDK。

常數值：701 (0x000002bd)

SDK_SANDBOX_PROCESS_NOT_AVAILABLE

已新增至 API 級別 34
Ad Services Extensions 4 也已納入
public static final int SDK_SANDBOX_PROCESS_NOT_AVAILABLE

無法使用 SDK 沙箱程序。

這表示 SDK 沙箱程序無法使用，原因可能是 SDK 沙箱程序已經關閉、中斷連線，或並未在一開始建立建立。

常數值：503 (0x000001f7)

SDK_SANDBOX_SERVICE

已新增至 API 級別 34
Ad Services Extensions 4 也已納入
public static final String SDK_SANDBOX_SERVICE

搭配 Context#getSystemService(String) 使用，可擷取 SdkSandboxManager，以與這個用戶端應用程式的 SDK 互動。

常數值："sdk_sandbox"

SDK_SANDBOX_STATE_已停用

已新增至 API 級別 33
Ad Services Extensions 3 也已納入
public static final int SDK_SANDBOX_STATE_DISABLED

SDK 沙箱已停用。

已隱藏 SdkSandboxManager 個 API。嘗試呼叫這些 API 會導致 UnsupportedOperationException。

常數值：0 (0x00000000)

SDK_SANDBOX_STATE_ENABLED_PROCESS_ISOLATION

已新增至 API 級別 33
Ad Services Extensions 3 也已納入
public static final int SDK_SANDBOX_STATE_ENABLED_PROCESS_ISOLATION

SDK 沙箱已啟用。

應用程式可以使用 SdkSandboxManager API 將其仰賴的 SDKs 載入相應的 SDK 沙箱程序。

常數值：2 (0x00000002)

公用方法

addSdkSandboxProcessDeathCallback

已新增至 API 級別 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 級別 34
Ad Services Extensions 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> 如果無法在對應中找到呼叫 Info 或 AppOwnedSdkSandboxInterface 清單，則傳回空白清單 此值不能為 null。

getSandboxedSdks

已新增至 API 級別 34
Ad Services Extensions 5 也已納入 
public List<SandboxedSdk> getSandboxedSdks ()

擷取在沙箱中載入的 SDK 相關資訊。

傳回
List<SandboxedSdk> SandboxedSdk 清單，其中包含目前載入的所有 SDK。此值不能為 null。

getSdkSandboxState

已新增至 API 級別 33
Ad Services Extensions 3 也已納入 
public static int getSdkSandboxState ()

傳回 SDK 沙箱功能的目前狀態。

傳回
int 這個值可以是 SDK_SANDBOX_STATE_DISABLED 或 SDK_SANDBOX_STATE_ENABLED_PROCESS_ISOLATION

getSyncedSharedPreferencesKeys

已新增至 API 級別 34
Ad Services Extensions 5 也已納入 
public Set<String> getSyncedSharedPreferencesKeys ()

傳回從應用程式的預設 SharedPreferences 同步處理至 SDK 沙箱的一組金鑰。

傳回
Set<String> 此值不能為 null。

loadSdk

已新增至 API 級別 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> 標記，在其資訊清單中宣告 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

已新增至 API 級別 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 級別 34
Ad Services Extensions 5 也已納入 
public void removeSyncedSharedPreferencesKeys (Set<String> keys)

從使用 addSyncedSharedPreferencesKeys(java.util.Set) 新增的鍵組中移除金鑰

如果已移除的金鑰已同步，則會從 SDK 沙箱中清除。

參數
keys Set：不應再同步到沙箱的鍵名組合。此值不能為 null。

requestSurfacePackage

已新增至 API 級別 34
Ad Services Extensions 4 也已納入 
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

已新增至 API 級別 34
Ad Services Extensions 7 也已納入 
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

已新增至 API 級別 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。

取消註冊 AppOwnedSdkSandboxInterface

public void unregisterAppOwnedSdkSandboxInterface (String name)

取消註冊應用程式程序的 ERROR(/AppOwnedSdkSandboxInterfaces)。

參數
name String：用來註冊 AppOwnedSdkSandboxInterface 的名稱。此值不能為 null。