API-интерфейсы представления пользовательского интерфейса среды выполнения SDK

SDK Runtime позволяет рекламным SDK работать в изолированной среде, что исключает доступ к иерархии представлений издателя. Для отображения рекламы платформа предоставляет SDK API SandboxedSdkProvider.getView для получения представления рекламы и упаковывает его в SurfacePackage для отправки по межпроцессному взаимодействию (IPC) клиентскому приложению. Это имеет ряд недостатков, которые обсуждаются ниже. Далее в этом документе будет представлена ​​предлагаемая библиотека Jetpack, которая разрабатывается для решения этих проблем.

Обоснование расширения API платформы

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

1. Позволяет SDK управлять несколькими рекламными объявлениями на протяжении всего их жизненного цикла и понимать, что происходит с пользовательским интерфейсом объявления после его создания SDK.
2. Разделяет создание представления и привязку контента. Использование стороннего канала позволяет SDK возвращать объект, соответствующий запросу рекламы к приложению (контент), который может быть привязан к контейнеру рекламы, когда приложение сочтет это необходимым.
3. Абстрагирует базовые платформенные конструкции, используемые для отображения пользовательского интерфейса в разных процессах. (В настоящее время платформа использует SurfaceControlViewhost и генерирует из него SurfacePackage .)
4. Позволяет SDK для размещения рекламы в среде выполнения SDK автоматически получать уведомления при изменении пользовательского интерфейса контейнера рекламы. Если издатель изменяет макет контейнера рекламы, SDK остается в неведении об этих изменениях, если издатель явно не вызовет API для уведомления.
5. Обеспечивает синхронизацию изменений размеров пользовательского интерфейса рекламы и контейнера рекламы без каких-либо видимых пользователю задержек.
6. Автоматически обеспечивает обратную совместимость. SurfacePackage недоступен до уровня API 30. Кроме того, на устройствах, где отсутствует среда выполнения SDK, а SDK является локальным для издателя, нецелесообразно создавать SurfacePackage для рекламы, когда представление можно получить напрямую из SDK. Боковой канал абстрагирует эту сложность от SDK и кода разработчика приложения.
7. Позволяет беспрепятственно интегрировать рекламный интерфейс с Composables. Разработчики Jetpack Compose, не работающие с представлениями, также могут продолжать размещать пользовательский интерфейс, сгенерированный разработчиком SDK, который по-прежнему работает с представлениями.

Библиотеки пользовательского интерфейса

Библиотеки пользовательского интерфейса абстрагируют описанные выше сложности и предоставляют дополнительный канал, который издатель и SDK могут использовать для отображения пользовательского интерфейса в разных процессах и его обновления по мере взаимодействия пользователя с ним и устройством.

Существует три библиотеки пользовательского интерфейса: основная , клиентская и провайдерская . Основная библиотека предоставляет интерфейсы, используемые клиентской и провайдерской библиотеками. Провайдер пользовательского интерфейса (обычно SDK) зависит от провайдерской библиотеки, а потребитель пользовательского интерфейса (обычно издатель) зависит от клиентской библиотеки. Вместе клиентская и провайдерская библиотеки образуют побочный канал, необходимый для создания и поддержания сеанса пользовательского интерфейса.

API

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

SandboxedUiAdapter : Создается SDK и предоставляет способ получения контента для отображения в пользовательском интерфейсе издателя.

SandboxedSdkView : Созданный издателем, это контейнер, содержащий контент, полученный через SandboxedUiAdapter .

Session : Создается SDK в ответ на вызов метода SandboxedUiAdapter.openSession() . Представляет собой одну сессию пользовательского интерфейса. Это формирует канал связи между SDK и издателем и получает уведомления об изменениях в SandboxedSdkView , таких как отсоединение окон, изменение их размера или изменение конфигурации.

SessionClient : Созданный клиентской библиотекой, он образует канал связи между SDK и издателем на стороне издателя.

SandboxedSdkUiSessionStateChangedListener : Создается издателем. Слушатель изменений состояния пользовательского интерфейса, связанного с SandboxedSdkView .

Для получения более подробной информации об этих API ознакомьтесь с документацией по privacysandbox-ui .

Управление потоком

На следующих диаграммах показано взаимодействие между клиентской и провайдерской библиотеками пользовательского интерфейса в различных сценариях:

На предыдущей диаграмме показано, как издатель может создать SandboxedSdkView программно или через свой XML-файл и прикрепить его к SdkSandboxUiAdapter полученному из SDK через API, определенный в SDK. Чтобы отслеживать все изменения состояния пользовательского интерфейса, издатель должен добавить SandboxedSdkUiSessionStateChangedListener к SandboxedSdkView перед прикреплением SdkSandboxUiAdapter .

На этой диаграмме показано, как если активность издателя обрабатывает изменения конфигурации, клиентская библиотека позаботится о передаче этих изменений в SDK, чтобы тот мог соответствующим образом обновить свой пользовательский интерфейс. Например, этот процесс может быть запущен, когда пользователь поворачивает устройство, и издатель объявляет об обработке изменений конфигурации в своей активности, установив android:configChanges=["orientation"] .

Эта диаграмма иллюстрирует, как SDK может запрашивать изменение размера контейнера рекламы с помощью методов объекта SessionClient . Этот API срабатывает, когда SDK хочет изменить размер рекламы и требует от издателя изменить размер контейнера рекламы в соответствии с новыми размерами. Это может происходить в ответ на взаимодействие с пользователем, например, mraid.resize() .

На этой диаграмме показано, как закрывается сессия при отсоединении SandboxedSdkView от окна. Сессию также можно закрыть в любой момент (например, при потере пользователем сетевого соединения) с помощью SDK, вызвав SessionClient.onSessionError() .

Z-порядок

Библиотека пользовательского интерфейса клиента использует внутри себя объект SurfaceView для размещения пользовательского интерфейса SDK. SurfaceView может использовать Z-порядок для отображения своего интерфейса либо поверх окна издателя, либо под ним. Это контролируется методом SandboxedSdkView.orderProviderUiAboveClientUi() , который принимает логическое значение setOnTop .

Если setOnTop равно true , каждое android.view.MotionEvent в SandboxedSdkView отправляется в SDK. Если false , они отправляются издателю. По умолчанию события движения отправляются в SDK.

Как правило, издателям не нужно менять стандартный порядок отображения рекламы по оси Z. Однако при показе элементов пользовательского интерфейса, закрывающих рекламу, например, выпадающего меню, порядок отображения по оси Z следует временно изменить по сравнению со стандартным, а затем восстановить его при закрытии закрывающего элемента. Мы изучаем способы автоматизации этого процесса в библиотеке пользовательского интерфейса клиента.

Прокрутка

Когда рекламный интерфейс расположен по вертикали над окном издателя, MotionEvents из рекламного интерфейса отправляются в SDK. Жесты прокрутки и взмаха, инициированные в рекламном интерфейсе, обрабатываются особым образом:

1. Жесты вертикальной прокрутки и прокрутки передаются и обрабатываются контейнером издателя. Это обеспечивает удобство использования, когда контейнер издателя, в котором размещен рекламный интерфейс, допускает вертикальную прокрутку. Это не требует дополнительной работы со стороны SDK или издателя.
2. Жесты горизонтальной прокрутки и прокрутки передаются в SDK и обрабатываются им. Это обеспечивает удобство использования, когда сам рекламный интерфейс допускает горизонтальную прокрутку (например, в рекламной карусели).

Руководство по внедрению

SDK должен реализовывать следующее:

• SandboxedUiAdapter : Этот параметр возвращается издателю в ответ на API, определенный в SDK, например, loadAd . Метод openSession() этой реализации следует использовать для отправки запроса на показ рекламы на серверы SDK и подготовки рекламного представления для этого запроса.
• Session** : Этот параметр возвращается в ответ на вызов SandboxedUiAdapter.openSession . Он предоставляет клиентской библиотеке способ получить доступ к рекламному интерфейсу и уведомить SDK об изменениях в этом API. Все методы Session должны быть реализованы здесь.

Издатель должен сделать следующее:

1. Создайте объект SandboxedSdkView либо с помощью XML, либо программно.
2. Прикрепите обработчик событий SandboxedSdkUiSessionStateChangedListener к объекту SandboxedSdkView , чтобы отслеживать изменения в пользовательском интерфейсе.
3. Прикрепите предоставленный SDK адаптер SandboxedUiAdapter к элементу SandboxedSdkView .
4. Добавьте SandboxedSdkView в окно как обычно, и пусть клиентская библиотека позаботится о создании и поддержании сессии пользовательского интерфейса с SDK.
5. В подходящие моменты реагируйте на изменения состояния, о которых сообщает SandboxedSdkUiSessionChangedListener . Например, если SDK неожиданно закрывает сессию, издатель может заменить SandboxedSdkView статическим изображением или удалить его из иерархии представлений.
6. При создании переходов, которые могут перекрывать рекламный интерфейс, например, выпадающее меню, временно orderProviderUiAboveClientUi в значение false, чтобы расположить рекламный интерфейс под окном издателя. После закрытия выпадающего меню установите orderProviderUiAboveClientUi в true .

Будущее API платформы

После перехода библиотек пользовательского интерфейса в бета-версию мы планируем объявить устаревшими API платформы среды выполнения SDK, связанные с отображением пользовательского интерфейса, а именно SdkSandboxManager.requestSurfacePackage() и SandbxedSdkProvider.getView() .

Открытые вопросы

1. Существуют ли более распространённые сценарии использования рекламного интерфейса, которые библиотеки пользовательского интерфейса должны обрабатывать автоматически?
2. Какие UI-фреймворки вы используете для отображения рекламного интерфейса? Ожидаете ли вы проблем с интеграцией библиотек UI с этими фреймворками?
3. Является ли размещение прокручиваемого рекламного интерфейса в прокручиваемом контейнере издателя распространенным для вас сценарием? Каково направление прокрутки для рекламного интерфейса и контейнера в этом случае? Какое поведение вы ожидаете, когда пользователь инициирует прокрутку рекламного интерфейса?