Поддержка активности для полноэкранной рекламы

Примечание. Privacy Sandbox для Android — это текущий проект, и в этом документе отражен его текущий дизайн. Ваше мнение очень важно, поскольку мы продолжаем развивать и улучшать его функции.

Среда выполнения SDK накладывает ограничения на то, как SDK могут запускать новые действия. Это создает проблему для полноэкранных форматов рекламы, которые обычно требуют запуска отдельного действия для улучшения контроля и удобства пользователей. Чтобы решить эту проблему, в SDK Runtime представлен новый механизм изолированных действий.

Пакеты SDK, загруженные в среду выполнения SDK, не могут напрямую определять теги <activity> в своем манифесте или инициировать свои собственные действия. Вместо этого вводится новое действие намерения START_SANDBOXED_ACTIVITY .

Хотя SDK также не могут запускать намерения с помощью этого действия, SDK могут запросить клиентское приложение инициировать это намерение. Затем система создает определяемое платформой действие и передает его в SDK. Это действие будет выполняться в том же процессе, что и SDK.

Затем SDK может использовать это действие для реализации полноэкранной рекламы и управления ею.

Действие, предоставляемое платформой, представляет собой стандартную операцию android.app.Activity , запускаемую как часть задачи клиентского приложения.

Внимание: предоставленное действие ( android.app.Activity ) имеет ограниченную поддержку некоторых библиотек AndroidX на стороне SDK, в частности Compose.

Внимание: Context этого действия не должен использоваться SDK напрямую. Вместо этого SDK должны использовать SandboxedSdkProvider#getContext() для получения соответствующего контекста для своих операций.

Создание активности в среде выполнения 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 для запроса приложения на запуск действий.

Последовательность запуска действий с библиотеками действий выглядит следующим образом:

1. SDK добавляет параметр типа SdkActivityLauncher ко всем API, которые запускают действия.
2. Клиентское приложение вызывает createSdkActivityLauncher в одном из своих действий, чтобы создать средство запуска, которое можно передать в SDK при вызовах API.
3. SDK вызывает SdkSandboxControllerCompat.registerSdkSandboxActivityHandler(SdkSandboxActivityHandlerCompat) и получает токен идентификатора.
4. SDK вызывает launchSdkActivity для запуска действия.

Примечание. Если клиентское приложение хочет добавить условие для SDK для создания действий, оно может передать выражение предиката при создании средства запуска. Если приложение не хочет обусловливать создание действия, оно может сделать так, чтобы предикат return всегда был true .

На следующей диаграмме показан порядок действий в случае использования библиотек действий.

Диаграмма последовательности, показывающая процесс запуска действия с использованием библиотек действий.

API платформы

Платформа представляет следующие API-интерфейсы для облегчения создания и управления изолированными действиями в среде выполнения SDK:

• SdkSandboxActivityHandler : обработчик активности используется для уведомления SDK о создании действия и его регистрации в SDK.
• Чтобы помочь с регистрацией обработчиков активности, SDK может использовать следующие методы в SdkSandboxController :
  • .registerSdkSandboxActivityHandler(SdkSandboxActivityHandler) : регистрирует экземпляр SdkSandboxActivityHandler , который возвращает идентификатор IBinder .
  • .unregisterSdkSandboxActivityHandler(SdkSandboxActivityHandler) : отменяет регистрацию зарегистрированного экземпляра SdkSandboxActivityHandler используя его идентификатор.
• SdkSandboxManager.startSdkSandboxActivity(Activity, IBinder) : вызываемый из клиентского приложения, этот метод запускает создание действий для SDK. Клиентское приложение должно передать в качестве параметров выбранное им начальное действие и идентификатор обработчика активности SDK.

Чтобы начать действие с использованием API платформы, SDK должны следовать следующему алгоритму:

1. SDK регистрирует обработчик активности с помощью предоставленных API и получает идентификатор.
2. SDK разделяет этот идентификатор со своим клиентским приложением.
3. Клиентское приложение вызывает метод для запуска действия в среде выполнения SDK с помощью API платформы startSdkSandboxActivity(Activity, IBinder) , передавая в качестве параметров выбранное начальное действие для этого нового действия и идентификатор обработчика действия.
4. Платформа запускает действие и уведомляет SDK посредством обратного вызова в обработчике действия ( SdkSandboxActivityHandler.onActivityCreated(Activity) ).
5. SDK использует это действие для заполнения его рекламой.

Примечание. onActivityCreated(Activity) вызывается через Activity.onCreate(Bundle) , ожидается, что SDK заполнят представление контента на этом этапе.

Использование API-интерфейсов платформы возлагает на SDK ответственность за передачу идентификатора SdkSandboxActivityHandler клиентскому приложению через его API-интерфейсы в соответствующее время и предоставление клиентским приложениям инструкций по его использованию.

На следующей блок-схеме в примере SDK есть метод launchActivity(AppCallback) который ожидает обратного вызова (определенного как часть API SDK). Этот обратный вызов используется SDK для обмена идентификатором обработчика активности ( SdkSandboxActivityHandler ) с клиентским приложением.

Диаграмма последовательности, показывающая процесс запуска действия с использованием API платформы.

Видимость

В среде выполнения 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 для обработки обратной навигации.