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. |
Публичные методы | |
---|---|
void | addSdkSandboxProcessDeathCallback ( Executor callbackExecutor, SdkSandboxManager.SdkSandboxProcessDeathCallback callback) Добавляет обратный вызов, который регистрируется для событий жизненного цикла песочницы SDK, таких как прекращение существования песочницы SDK. |
void | addSyncedSharedPreferencesKeys ( Set < String > keys) Добавляет ключи в набор ключей, синхронизируемых из |
List < AppOwnedSdkSandboxInterface > | getAppOwnedSdkSandboxInterfaces () Получает список |
List < SandboxedSdk > | getSandboxedSdks () Получает информацию о SDK, загруженных в песочницу. |
static int | getSdkSandboxState () Возвращает текущее состояние доступности функции песочницы SDK. |
Set < String > | getSyncedSharedPreferencesKeys () Возвращает заданные ключи, которые синхронизируются из |
void | loadSdk ( String sdkName, Bundle params, Executor executor, OutcomeReceiver < SandboxedSdk , LoadSdkException > receiver) Загружает SDK в Java-процесс песочницы SDK. |
void | registerAppOwnedSdkSandboxInterface ( AppOwnedSdkSandboxInterface appOwnedSdkSandboxInterface) Регистрирует |
void | removeSdkSandboxProcessDeathCallback ( SdkSandboxManager.SdkSandboxProcessDeathCallback callback) Удаляет |
void | removeSyncedSharedPreferencesKeys ( Set < String > keys) Удаляет ключи из набора ключей, добавленных с помощью Удаленные ключи будут удалены из песочницы SDK, если они уже были синхронизированы. |
void | requestSurfacePackage ( String sdkName, Bundle params, Executor callbackExecutor, OutcomeReceiver < Bundle , RequestSurfacePackageException > receiver) Отправляет запрос на поверхностный пакет в SDK. |
void | startSdkSandboxActivity ( Activity fromActivity, IBinder sdkActivityToken) Запускает |
void | unloadSdk ( String sdkName) Выгружает SDK, ранее загруженный вызывающей стороной. |
void | unregisterAppOwnedSdkSandboxInterface ( String name) Отменяет регистрацию |
Унаследованные методы | |
---|---|
Константы
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<SandboxedSdk, LoadSdkException> 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<Bundle, RequestSurfacePackageException> 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 . |
Контент и образцы кода на этой странице предоставлены по лицензиям. Java и OpenJDK – это зарегистрированные товарные знаки корпорации Oracle и ее аффилированных лиц.
Последнее обновление: 2024-08-21 UTC.