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

Среда выполнения SDK позволяет запускать рекламные 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 могут использовать для отображения пользовательского интерфейса в различных процессах и поддержания его обновления по мере взаимодействия пользователя с ним и с устройством.

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

API

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

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

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

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

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

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

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

Прочтите справочную документацию по Privacysandbox-ui для получения более подробной информации об этих API.

Поток управления

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

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

Иллюстрация, показывающая процесс открытого сеанса.
Получите пользовательский интерфейс из SDK.

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

Изменение пользовательского интерфейса по инициативе издателя.

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

Изменение пользовательского интерфейса, инициированное SDK.

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

Закрытие сеанса пользовательского интерфейса.

Z-порядок

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

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

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

Прокрутка

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

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

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

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. Какие платформы пользовательского интерфейса вы используете для показа пользовательского интерфейса рекламы? Ожидаете ли вы проблем при интеграции библиотек пользовательского интерфейса с этими платформами?
  3. Является ли пользовательский интерфейс прокручиваемой рекламы, помещенный в прокручиваемый контейнер издателя, распространенным вариантом использования для вас? Какова направленность прокрутки пользовательского интерфейса объявления и контейнера в этом случае? Какого поведения вы ожидаете, когда пользователь прокручивает рекламный интерфейс?