Среда выполнения SDK накладывает ограничения на то, как SDK могут запускать новые действия. Это создает проблему для полноэкранных форматов рекламы, которые обычно требуют запуска отдельного действия для улучшения контроля и удобства пользователей. Чтобы решить эту проблему, в SDK Runtime представлен новый механизм изолированных действий.
Пакеты SDK, загруженные в среду выполнения SDK, не могут напрямую определять теги <activity>
в своем манифесте или инициировать свои собственные действия. Вместо этого вводится новое действие намерения START_SANDBOXED_ACTIVITY
.
Хотя SDK также не могут запускать намерения с помощью этого действия, SDK могут запросить клиентское приложение инициировать это намерение. Затем система создает определяемое платформой действие и передает его в SDK. Это действие будет выполняться в том же процессе, что и SDK.
Затем SDK может использовать это действие для реализации полноэкранной рекламы и управления ею.
Активность, предоставляемая платформой, представляет собой стандартную android.app.Activity
, запускаемую как часть задачи клиентского приложения.
Создание активности в среде выполнения SDK
У вас есть два основных метода создания действий: использование оптимизированных библиотек действий Jetpack или прямое взаимодействие с API-интерфейсами платформы .
Мы рекомендуем использовать библиотеки действий, поскольку они упрощают создание действий, абстрагируя основную сложность.
Библиотеки действий
Библиотеки действий предоставляют несколько преимуществ:
- Абстрагируйте внутренние детали регистрации обработчиков действий и обмена их идентификаторами с клиентскими приложениями.
- Предоставляет разработчикам приложений больше контроля над тем, как пакеты SDK создают действия в своих приложениях, позволяя им устанавливать условия (предикаты), которые должны выполняться.
- Создайте унифицированный способ для SDK определять API, которые запускают действия.
Существует три библиотеки действий: ядро, клиент и поставщик.
- Основная библиотека предоставляет интерфейсы, используемые клиентскими приложениями и библиотеками поставщиков.
- Библиотека поставщика предоставляет API для SDK для запуска действий.
- Клиентская библиотека предоставляет API-интерфейсы для клиентских приложений для создания средства запуска действий, которое SDK может использовать для запроса приложений на запуск действий.
Эти библиотеки представляют следующие API:
-
SdkActivityLauncher
: средство запуска действий позволяет SDK обрабатывать запуск действий из клиентского приложения. Клиентские приложения должны создать средство запуска и передать его в качестве параметра API-интерфейсам SDK, которые запускают действия. -
<T : Activity & LifecycleOwner> T.createSdkActivityLauncher(() -> Boolean )
: функция расширения, которую клиентское приложение может вызывать из своих действий для создания средств запуска. -
SdkActivityLauncher.launchSdkActivity(IBinder)
: метод, используемый SDK для запроса приложения на запуск действий.
Последовательность запуска действий с библиотеками действий выглядит следующим образом:
- SDK добавляет параметр типа
SdkActivityLauncher
ко всем API, которые запускают действия. - Клиентское приложение вызывает
createSdkActivityLauncher
в одном из своих действий, чтобы создать средство запуска, которое можно передать в SDK при вызовах API. - SDK вызывает
SdkSandboxControllerCompat.registerSdkSandboxActivityHandler(SdkSandboxActivityHandlerCompat)
и получает токен идентификатора. - SDK вызывает
launchSdkActivity
для запуска действия.
На следующей диаграмме показан порядок действий в случае использования библиотек действий.
![Диаграмма последовательности действий библиотеки действий](https://developers.google.cn/static/privacy-sandbox/private-advertising/sdk-runtime/full-screen-ads/ActivityLibrarySequence.png?hl=ru)
API платформы
Платформа представляет следующие API-интерфейсы для облегчения создания и управления изолированными действиями в среде выполнения SDK:
-
SdkSandboxActivityHandler
: обработчик активности используется для уведомления SDK о создании действия и его регистрации в SDK. - Чтобы помочь с регистрацией обработчиков активности, SDK может использовать следующие методы в
SdkSandboxController
:-
.registerSdkSandboxActivityHandler(SdkSandboxActivityHandler)
: регистрирует экземплярSdkSandboxActivityHandler
, который возвращает идентификаторIBinder
. -
.unregisterSdkSandboxActivityHandler(SdkSandboxActivityHandler)
: отменяет регистрацию зарегистрированного экземпляраSdkSandboxActivityHandler
, используя его идентификатор.
-
-
SdkSandboxManager.startSdkSandboxActivity(Activity, IBinder)
: вызываемый из клиентского приложения, этот метод запускает создание действий для SDK. Клиентское приложение должно передать в качестве параметров выбранное им начальное действие и идентификатор обработчика активности SDK.
Чтобы начать действие с использованием API платформы, SDK должны следовать следующему алгоритму:
- SDK регистрирует обработчик активности с помощью предоставленных API и получает идентификатор.
- SDK разделяет этот идентификатор со своим клиентским приложением.
- Клиентское приложение вызывает метод для запуска действия в среде выполнения SDK с помощью API платформы
startSdkSandboxActivity(Activity, IBinder)
, передавая в качестве параметров выбранное начальное действие для этого нового действия и идентификатор обработчика действия. - Платформа запускает действие и уведомляет SDK посредством обратного вызова в обработчике действия (
SdkSandboxActivityHandler.onActivityCreated(Activity)
). - SDK использует это действие для заполнения его рекламой.
Использование API-интерфейсов платформы возлагает на SDK ответственность за передачу идентификатора SdkSandboxActivityHandler клиентскому приложению через его API-интерфейсы в соответствующее время и предоставление клиентским приложениям инструкций по его использованию.
На следующей блок-схеме в примере SDK есть метод launchActivity(AppCallback)
, который ожидает обратного вызова (определенного как часть API SDK). Этот обратный вызов используется SDK для обмена идентификатором обработчика активности ( SdkSandboxActivityHandler
) с клиентским приложением.
![Схема последовательности API платформы](https://developers.google.cn/static/privacy-sandbox/private-advertising/sdk-runtime/full-screen-ads/platformAPIssequence.png?hl=ru)
Видимость
В среде выполнения SDK объявления, интегрированные в иерархию представлений клиентского приложения, используют побочные каналы для рендеринга представлений SDK из процесса SDK в процесс клиентского приложения.
SDK не может использовать те же API-интерфейсы представления, которые они используют вне среды выполнения SDK, чтобы определить, видно ли объявление пользователю, поскольку представление объявления не привязано к окну приложения ( Viewability ).
Напротив, действия, предоставляемые платформой, выполняются изначально в процессе выполнения SDK, что устраняет необходимость в побочных каналах и позволяет SDK использовать стандартные API-интерфейсы Android Activity
и View
.
Из-за этих различных реализаций постоянные усилия направлены на унификацию интерфейсов для получения сигналов видимости независимо от контекста загрузки рекламы.
Жизненный цикл
ActivityHolder
, передаваемый в SDK через SdkSandboxActivityHandlerCompat.onActivityCreated(ActivityHolder)
реализует LifecycleOwner
и может использоваться для получения сведений о Lifecycle.Event
.
Обратная навигация
Метод ActivityHolder.getOnBackPressedDispatcher()
возвращает OnBackPressedDispatcher
, который можно использовать для регистрации экземпляров OnBackPressedCallback
для обработки обратной навигации.