SdkSandboxManager

public final class SdkSandboxManager
extends Object

java.lang.Object
   ↳ android.app.sdksandbox.SdkSandboxManager

SDKs を SDK サンドボックス プロセスに読み込んで操作するための API を提供します。

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

requestSurfacePackage(java.lang.String, android.os.Bundle, java.util.concurrent.Executor, android.os.OutcomeReceiver) のフィールドである OutcomeReceiver の onResult 関数に渡される Bundle 内のキーの名前。その値はリクエストされた 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) とともに使用して、このクライアント アプリケーションに属する SDK とやり取りするための SdkSandboxManager を取得します。

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 レポートを有効にするには、null 以外の値のみを使用できます。

定数値: "android.app.sdksandbox.extra.HOST_TOKEN"

EXTRA_SURFACE_PACKAGE

API レベル 34 で追加
Ad Services Extensions 4 にも追加 
public static final String EXTRA_SURFACE_PACKAGE

requestSurfacePackage(java.lang.String, android.os.Bundle, java.util.concurrent.Executor, android.os.OutcomeReceiver) のフィールドである OutcomeReceiver の onResult 関数に渡される Bundle 内のキーの名前で、値はリクエストされた 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_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 でエラーが発生したことを示します。詳細については、SdkSandboxManager#loadSdk に渡される OutcomeReceiver を通じて LoadSdkException で返される Bundle から取得できます。

定数値: 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 サンドボックス プロセスが終了しているか、切断されているか、そもそも作成されていないことを示します。

定数値: 503 (0x000001f7)

SDK_SANDBOX_SERVICE

API レベル 34 で追加
Ad Services Extensions 4 にも追加 
public static final String SDK_SANDBOX_SERVICE

Context#getSystemService(String) とともに使用して、このクライアント アプリケーションに属する SDK とやり取りするための SdkSandboxManager を取得します。

定数値: "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

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> 現在読み込まれているすべての SDK を含む SandboxedSdk のリスト。 この値が 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 を起動し、渡された sdkActivityToken を共有している SDK に渡します。この SDK は、この SDK からの Activity を記録するリクエストを識別します。

次の場合、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 になることはありません。