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) 的軟體包欄位中使用的鍵名稱，其值必須定義邏輯的整數 ID 顯示 SurfacePackage。

String EXTRA_HEIGHT_IN_PIXELS

要在 requestSurfacePackage(java.lang.String, android.os.Bundle, java.util.concurrent.Executor, android.os.OutcomeReceiver) 套件欄位中使用的鍵名稱，其值應定義 SurfacePackage 的整數高度 (以像素為單位)。

String EXTRA_HOST_TOKEN

要在 requestSurfacePackage(java.lang.String, android.os.Bundle, java.util.concurrent.Executor, android.os.OutcomeReceiver) 的套件欄位中使用的鍵名稱，其值應會顯示 SurfaceView.getHostToken() 傳回的權杖 (在 SurfaceView 經過後傳回) 加入到檢視區塊階層中

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) 套件欄位中使用的鍵名稱，其值應定義 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) 的軟體包欄位中使用的鍵名稱，其值必須定義邏輯的整數 ID 顯示 SurfacePackage。

常數值： 「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) 套件欄位中使用的鍵名稱，其值應定義 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) 的套件欄位中使用的鍵名稱，其值應會顯示 SurfaceView.getHostToken() 傳回的權杖 (在 SurfaceView 經過後傳回) 加入到檢視區塊階層中如要啟用 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) 套件欄位中使用的鍵名稱，其值應定義 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)， 成功載入。

常數值： 指南 (0x00000065)

LOAD_SDK_INTERNAL_ERROR

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

載入 SDK 時發生內部錯誤。

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

常數值： 500 人 (0x000001f4)

LOAD_SDK_NOT_FOUND

已加至 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_ERROR

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

載入後 SDK 錯誤。

這表示 SDK 在載入後初始化期間遇到錯誤。 此詳細資料可透過 LoadSdkException 中傳回的套裝組合，取得 傳入 SdkSandboxManager#loadSdk 的 OutcomeReceiver。

常數值： 指南 (0x00000066)

LOAD_SDK_SDK_SANDBOX_DISABLED

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

SDK 沙箱已停用。

這表示 SDK 沙箱已停用。之後嘗試在 此開機程序也會失敗

常數值： 指南 (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_DISABLED

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

SDK 沙箱已停用。

已隱藏 SdkSandboxManager 個 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> 如果地圖中沒有 callInfo，則會空白清單，否則為 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：之前使用 SdkSandboxProcessDeathCallback 新增的 SdkSandboxManager#addSdkSandboxProcessDeathCallback(Executor, 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 至檢視區塊階層，但能以非同步方式要求 用於算繪來自 SDK 檢視畫面的 SurfacePackage。

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

已加至 API 級別 34
也已納入 Ad Services Extensions 7 
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 所共用的 ID。 此值不能為 null。

卸載 Sdk

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

取消註冊 AppOwnedSdkSandboxInterface

public void unregisterAppOwnedSdkSandboxInterface (String name)

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

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