SdkSandboxManager

public final class SdkSandboxManager
extends Object

java.lang.Объект
android.app.sdksandbox.SdkSandboxManager


Предоставляет API для загрузки SDKs в изолированную среду SDK и последующего взаимодействия с ними.

Песочница SDK — это Java-процесс, работающий в отдельном диапазоне uid. Каждое приложение может иметь собственный процесс песочницы SDK.

Сначала приложению необходимо объявить SDK, от которых оно зависит, в своем манифесте с помощью тега <uses-sdk-library> . Приложения могут загружать в песочницу SDK только те SDK, от которых они зависят.

Краткое содержание

Вложенные классы

interface SdkSandboxManager.SdkSandboxProcessDeathCallback

Обратный вызов для отслеживания событий смерти песочницы SDK.

Константы

String EXTRA_DISPLAY_ID

Имя ключа, который будет использоваться в полях Bundle requestSurfacePackage(java.lang.String, android.os.Bundle, java.util.concurrent.Executor, android.os.OutcomeReceiver) , его значение должно определять целочисленный идентификатор логический дисплей для отображения SurfacePackage .

String EXTRA_HEIGHT_IN_PIXELS

Имя ключа, который будет использоваться в полях Bundle requestSurfacePackage(java.lang.String, android.os.Bundle, java.util.concurrent.Executor, android.os.OutcomeReceiver) , его значение должно определять целочисленную высоту SurfacePackage в пикселях.

String EXTRA_HOST_TOKEN

Имя ключа, который будет использоваться в полях Bundle requestSurfacePackage(java.lang.String, android.os.Bundle, java.util.concurrent.Executor, android.os.OutcomeReceiver) , его значение должно представлять токен, возвращаемый SurfaceView.getHostToken() после добавления SurfaceView в иерархию представлений.

String EXTRA_SURFACE_PACKAGE

Имя ключа в Bundle, которое передается функции onResult OutcomeReceiver , которое является полем requestSurfacePackage(java.lang.String, android.os.Bundle, java.util.concurrent.Executor, android.os.OutcomeReceiver) , его значение представляет запрошенный SurfacePackage .

String EXTRA_WIDTH_IN_PIXELS

Имя ключа, который будет использоваться в полях Bundle 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

SDK не загружается при запросе SurfacePackage .

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)

Удаляет SdkSandboxProcessDeathCallback , который был ранее добавлен с помощью addSdkSandboxProcessDeathCallback(java.util.concurrent.Executor, android.app.sdksandbox.SdkSandboxManager.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)

Запускает Activity в песочнице SDK.

void unloadSdk ( String sdkName)

Выгружает SDK, ранее загруженный вызывающей стороной.

void unregisterAppOwnedSdkSandboxInterface ( String name)

Отменяет регистрацию ERROR(/AppOwnedSdkSandboxInterfaces) для процесса приложения.

Унаследованные методы

Константы

EXTRA_DISPLAY_ID

public static final String EXTRA_DISPLAY_ID

Имя ключа, который будет использоваться в полях Bundle requestSurfacePackage(java.lang.String, android.os.Bundle, java.util.concurrent.Executor, android.os.OutcomeReceiver) , его значение должно определять целочисленный идентификатор логический дисплей для отображения SurfacePackage .

Постоянное значение: «android.app.sdksandbox.extra.DISPLAY_ID»

EXTRA_HEIGHT_IN_PIXELS

public static final String EXTRA_HEIGHT_IN_PIXELS

Имя ключа, который будет использоваться в полях Bundle 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

public static final String EXTRA_HOST_TOKEN

Имя ключа, который будет использоваться в полях Bundle 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_PACKAGE

public static final String EXTRA_SURFACE_PACKAGE

Имя ключа в Bundle, которое передается функции onResult OutcomeReceiver , которое является полем 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

Имя ключа, который будет использоваться в полях Bundle 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

public static final int LOAD_SDK_ALREADY_LOADED

SDK уже загружен.

Это указывает на то, что клиентское приложение попыталось перезагрузить тот же SDK, вызвав loadSdk(java.lang.String, android.os.Bundle, java.util.concurrent.Executor, android.os.OutcomeReceiver) после успешной загрузки.

Постоянное значение: 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 не найден.

Это указывает на то, что клиентское приложение попыталось загрузить несуществующий SDK, вызвав loadSdk(java.lang.String, android.os.Bundle, java.util.concurrent.Executor, android.os.OutcomeReceiver) .

Постоянное значение: 100 (0x00000064)

LOAD_SDK_SDK_DEFINED_ERROR

public static final int LOAD_SDK_SDK_DEFINED_ERROR

Ошибка SDK после загрузки.

Это указывает на то, что SDK обнаружил ошибку во время инициализации после загрузки. Подробности об этом можно получить из Bundle, возвращенного в LoadSdkException через OutcomeReceiver , переданный в SdkSandboxManager#loadSdk .

Постоянное значение: 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

SDK не загружается при запросе SurfacePackage .

Это указывает на то, что пакет SDK, для которого запрашивается SurfacePackage , не загружен либо потому, что песочница прекратила работу, либо потому, что она не была загружена изначально.

Постоянное значение: 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 отключена.

API-интерфейсы SdkSandboxManager скрыты. Попытки их вызова приведут к UnsupportedOperationException .

Постоянное значение: 0 (0x00000000)

SDK_SANDBOX_STATE_ENABLED_PROCESS_ISOLATION

public static final int SDK_SANDBOX_STATE_ENABLED_PROCESS_ISOLATION

Песочница SDK включена.

Приложение может использовать API-интерфейсы SdkSandboxManager для загрузки 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 : SdkSandboxProcessDeathCallback , который будет получать события жизненного цикла песочницы SDK. Это значение не может быть null .

адсинкедшаредпреференцскейс

public void addSyncedSharedPreferencesKeys (Set<String> keys)

Добавляет ключи в набор ключей, синхронизируемых из SharedPreferences приложения по умолчанию в песочницу SDK.

Синхронизированные данные будут доступны для чтения SDK с помощью API SdkSandboxController.getClientSharedPreferences() .

Чтобы остановить синхронизацию любого ключа, добавленного с помощью этого API, используйте removeSyncedSharedPreferencesKeys(java.util.Set) .

Синхронизация прерывается, если приложение перезапускается, и пользователю приходится снова вызывать этот API, чтобы перестроить пул ключей для синхронизации.

Примечание. Этот класс не поддерживает использование в нескольких процессах.

Параметры
keys Set : набор ключей, которые будут синхронизированы с Sandbox. Это значение не может быть 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<SandboxedSdkLoadSdkException> receiver)

Загружает SDK в Java-процесс песочницы SDK.

Асинхронно загружает библиотеку SDK с sdkName в процесс песочницы SDK. Вызывающий абонент будет уведомлен через receiver .

Вызывающий объект уже должен объявить SDKs от которых он зависит, в своем манифесте, используя тег <uses-sdk-library> . Вызывающий может загружать в изолированную программную среду SDK только SDKs , от которых он зависит.

Когда клиентское приложение загружает первый SDK, будет создан новый процесс песочницы SDK. Если для клиентского приложения уже создана песочница, в ту же песочницу будут загружены дополнительные SDK.

Этот API можно вызывать только тогда, когда вызывающая сторона работает на переднем плане. Вызовы из фонового режима приведут к возврату LoadSdkException в receiver .

Параметры
sdkName String : имя загружаемого SDK. Это значение не может быть null .

params Bundle : дополнительные параметры, которые будут переданы в SDK в форме Bundle по соглашению между клиентом и SDK. Это значение не может быть null .

executor Executor : Executor , к которому вызывается получатель. Это значение не может быть null . События обратного вызова и прослушивателя отправляются через этот Executor , предоставляя простой способ контролировать, какой поток используется. Чтобы отправлять события через основной поток вашего приложения, вы можете использовать Context.getMainExecutor() . В противном случае предоставьте Executor , который отправляет данные в соответствующий поток.

receiver OutcomeReceiver : он либо получает SandboxedSdk при успешном запуске, либо LoadSdkException . Это значение не может быть null .

РегистрацияAppOwnedSdkSandboxInterface

public void registerAppOwnedSdkSandboxInterface (AppOwnedSdkSandboxInterface appOwnedSdkSandboxInterface)

Регистрирует AppOwnedSdkSandboxInterface для процесса приложения.

Регистрация AppOwnedSdkSandboxInterface с тем же именем, что и у ранее зарегистрированного интерфейса, приведет к IllegalStateException .

AppOwnedSdkSandboxInterface#getName() относится к имени интерфейса.

Параметры
appOwnedSdkSandboxInterface AppOwnedSdkSandboxInterface : регистрируемый AppOwnedSdkSandboxInterface. Это значение не может быть null .

удалитьSdkSandboxProcessDeathCallback

public void removeSdkSandboxProcessDeathCallback (SdkSandboxManager.SdkSandboxProcessDeathCallback callback)

Удаляет SdkSandboxProcessDeathCallback , который был ранее добавлен с помощью addSdkSandboxProcessDeathCallback(java.util.concurrent.Executor, android.app.sdksandbox.SdkSandboxManager.SdkSandboxProcessDeathCallback)

Параметры
callback SdkSandboxManager.SdkSandboxProcessDeathCallback : SdkSandboxProcessDeathCallback , который был ранее добавлен с помощью SdkSandboxManager#addSdkSandboxProcessDeathCallback(Executor, SdkSandboxProcessDeathCallback) Это значение не может быть null .

удалитьSyncedSharedPreferencesKeys

public void removeSyncedSharedPreferencesKeys (Set<String> keys)

Удаляет ключи из набора ключей, добавленных с помощью addSyncedSharedPreferencesKeys(java.util.Set)

Удаленные ключи будут удалены из песочницы SDK, если они уже были синхронизированы.

Параметры
keys Set : набор имен ключей, которые больше не следует синхронизировать с песочницей. Это значение не может быть null .

запросПоверхностьПакет

public void requestSurfacePackage (String sdkName, 
                Bundle params, 
                Executor callbackExecutor, 
                OutcomeReceiver<BundleRequestSurfacePackageException> receiver)

Отправляет запрос на поверхностный пакет в SDK.

После того как клиентское приложение получит сигнал об успешной загрузке 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 можно вызывать только тогда, когда вызывающая сторона работает на переднем плане. Вызовы из фонового режима приведут к возврату RequestSurfacePackageException в receiver .

Параметры
sdkName String : имя SDK, загруженного в песочницу SDK. Это значение не может быть null .

params Bundle : параметры, которые клиентское приложение передает в SDK. Это значение не может быть null .

callbackExecutor Executor : Executor , для которого вызывается обратный вызов. Это значение не может быть null . События обратного вызова и прослушивателя отправляются через этот Executor , предоставляя простой способ контролировать, какой поток используется. Чтобы отправлять события через основной поток вашего приложения, вы можете использовать Context.getMainExecutor() . В противном случае предоставьте Executor , который отправляет данные в соответствующий поток.

receiver OutcomeReceiver : в случае успеха возвращается либо Bundle , который будет содержать ключ SdkSandboxManager#EXTRA_SURFACE_PACKAGE со значением SurfacePackage , либо RequestSurfacePackageException в случае сбоя. Это значение не может быть null .

Броски
IllegalArgumentException если params не содержат все необходимые ключи.

startSdkSandboxActivity

public void startSdkSandboxActivity (Activity fromActivity, 
                IBinder sdkActivityToken)

Запускает Activity в песочнице SDK.

Эта функция запустит новое Activity в той же задаче, что и переданная fromActivity и передаст его в SDK, который поделился переданным sdkActivityToken , который идентифицирует запрос от этого SDK для статистики этого Activity .

Activity не запустится в следующих случаях:

  • Приложение, вызывающее этот API, находится в фоновом режиме.
  • Переданный sdkActivityToken не сопоставляется с запросом Activity из SDK, который поделился им с вызывающим приложением.
  • SDK, который поделился переданным sdkActivityToken удалил свой запрос для этого Activity .
  • Activity песочницы уже создана.

Параметры
fromActivity Activity : Activity будет использоваться для запуска нового Activity в песочнице путем вызова Activity#startActivity(Intent) против него. Это значение не может быть null .

sdkActivityToken IBinder : идентификатор, общий для SDK, который запрашивает Activity . Это значение не может быть null .

выгрузитьSdk

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 .