Отображение кастомных элементов с помощью Android SDK
Когда открывается экран с пользовательским элементом, Adapty SDK передаёт тип и ID элемента в резолвер в коде вашего приложения. Резолвер возвращает одно из следующего:
- Вью, соответствующее типу и ID: пользователи видят нативное вью — например, анимацию Lottie, интерактивный график или превью камеры.
- Нет вью: пользователи видят фолбэк — содержимое внутри пользовательского элемента в Flow & Paywall Builder.
Пользователи версий приложения без резолвера также видят фолбэк. Поэтому вы можете опубликовать флоу до того, как выпустите обновление приложения.
Прежде чем начать
Вам понадобится:
- Adapty Android SDK 4.4 или выше: Более ранние версии показывают фолбэк для каждого кастомного элемента.
- Нативное Android-приложение: SDK Adapty для кроссплатформенных фреймворков, например Flutter, показывают фолбэк для каждого кастомного элемента.
- Схема именования кастомных элементов: Задайте каждому нативному представлению тип (Type), например
lottie_animation. Используйте в типах только строчные буквы, цифры и знаки подчёркивания. Чтобы различать кастомные элементы одного типа, задайте каждому идентификатор (ID), напримерwelcome_wave. Типы и идентификаторы в коде должны совпадать с теми, что указаны в Flow & Paywall Builder.
Если ваше iOS-приложение уже отображает кастомные элементы, переиспользуйте его Types и IDs. Если вы не настроили отдельную аудиторию для каждой платформы, iOS- и Android-пользователи видят одинаковые флоу.
Создание вью для кастомных элементов
Для каждого типа создайте или переиспользуйте composable/Android View. Следующие вью типа lottie_animation воспроизводят Lottie-анимацию из папки assets вашего приложения. Пример на Kotlin — это composable, использующий библиотеку com.airbnb.android:lottie-compose. Пример на Java создаёт Android View с помощью библиотеки com.airbnb.android:lottie:
Требования и лучшие практики
-
Размер:
- Отступы и выравнивание: убедитесь, что нативный вид вписывается в контейнер, выделенный для него во Flow & Paywall Builder, с учётом отступов. Если вид не занимает всю область, по умолчанию он отображается в верхнем начальном углу этой области. Чтобы изменить положение, измените выравнивание в разделе Layout кастомного элемента.
- Hug по высоте: если высота кастомного элемента задана как Hug, вид, растягивающийся на всё доступное пространство (например, lazy list), схлопнется или растянется до высоты экрана. Задайте кастомному элементу Fixed высоту.
-
Тема: чтобы composable отображался в цветах и шрифтах вашего приложения на экране, построенном на Views, оберните его в вашу Compose-тему.
-
Действия флоу: нативный вид не может инициировать действия флоу, такие как переход на следующий экран. Кнопки навигации, кнопки покупки и другие кнопки с действиями флоу размещайте за пределами кастомного элемента.
-
Выбираемые элементы: размещайте кастомный элемент за пределами карточек продуктов и других выбираемых элементов. При изменении выбора нативный вид может потерять своё состояние.
-
Обработка навигации: когда пользователь переходит на следующий экран, SDK удаляет нативный вид с экрана. Завершите всё, что вид запустил, — например, сессии камеры, плееры и обновления геолокации:
- Composable: используйте блок
onDisposeвнутриDisposableEffect. Для асинхронной работы используйтеLaunchedEffect: Compose отменит его, когда composable покинет композицию. - Android
View: переопределитеonDetachedFromWindowв подклассе вашегоViewили добавьтеView.OnAttachStateChangeListenerкView.
Когда пользователь возвращается или происходит изменение конфигурации (например, поворот экрана), SDK снова вызывает резолвер и создаёт новое нативное представление без состояния предыдущего.
- Composable: используйте блок
-
Карусели: В карусели нативные представления на всех слайдах остаются активными, пока открыт экран, а не только представление на видимом слайде. Не помещайте в карусели превью с камеры и плееры со звуком.
Напишите резолвер для сопоставления пользовательских элементов и представлений
Чтобы написать резолвер, реализуйте интерфейс AdaptyCustomElementsResolver. Его метод resolve принимает тип и идентификатор пользовательского элемента и возвращает соответствующее представление в одной из следующих форм:
- Composable: Верните
AdaptyCustomElementContent.compose, передав Composable внутрь лямбды. - Android
View: ВернитеAdaptyCustomElementContent.view, передав функцию, которая создаётView. В Kotlin укажите параметрfactoryявно:AdaptyCustomElementContent.view(factory = { context, _ -> ChartView(context) }). Без явного имени Kotlin передаст трейлинг-лямбду в необязательный параметрupdate, и код не скомпилируется.
Для типа lottie_animation следующий резолвер возвращает Lottie-представление. Идентификатор указывает на файл анимации в папке assets, например welcome_wave для welcome_wave.json:
Для любого другого типа верните null. Если вы добавите пользовательский элемент с новым типом после выпуска приложения, пользователи выпущенной версии увидят его фолбэк.
К резолверу предъявляются следующие требования:
-
Сетевые данные и плееры: Храните сетевые данные и плееры в состоянии нативного вью, а не в резолвере. SDK вызывает резолвер многократно, пока экран открыт. Код в резолвере выполняется заново при каждом вызове, поэтому сетевые запросы повторяются, а плееры начинают воспроизведение сначала. Между этими вызовами SDK не пересоздаёт нативное вью, поэтому данные загружаются один раз, а плееры продолжают работу. Создавайте плееры, сессии и сетевые запросы внутри нативного вью:
- Composable: Создавайте плееры и сессии в
remember, а сетевые запросы — вLaunchedEffect. - Android
View: Создавайте плееры, сессии и сетевые запросы вonAttachedToWindow.
- Composable: Создавайте плееры и сессии в
-
Одно нативное вью на каждый кастомный элемент: Некоторые нативные вью изменяются, пока экран открыт, — например, когда загружаются данные или когда пользователь нажимает на них. Реализуйте эту логику в самом нативном вью, а не в резолвере. Если резолвер возвращает другой composable для того же кастомного элемента, Compose сбрасывает состояние вью.
-
Новый
Viewпри каждом появлении: Создавайте новыйViewпри каждом вызовеfactory. SDK вызываетfactoryкаждый раз, когда кастомный элемент появляется: при открытии экрана, при возврате пользователя на экран или после поворота устройства. -
Данные приложения: Храните объект с данными, например
StateFlowилиLiveDataс ежедневной серией, в свойстве резолвера. Передайте объект в нативное вью и наблюдайте за ним там:- Composable: Собирайте
StateFlowс помощьюcollectAsStateили наблюдайте заLiveDataс помощьюobserveAsState. - Android
View: Подписывайтесь на объект вonAttachedToWindow, а отписывайтесь вonDetachedFromWindow.
Значение, которое вы копируете в резолвер, например номер серии, остаётся таким, каким оно было в момент создания резолвера.
- Composable: Собирайте
Задайте условия для резервного контента
Чтобы показать пользователям резервный контент вместо пустого пользовательского элемента, не возвращайте представление в следующих ситуациях:
- Нечего визуализировать — отсутствует нужный файл анимации или файл данных.
- Нечего обрабатывать — пользователь пропустил вопрос викторины, и данные неполны.
- Доступ запрещён — отклонённое разрешение не позволяет представлению получить доступ к ресурсу.
Например, резолвер не возвращает представление, если файл анимации отсутствует.
Возвращайте null для разрешения только в том случае, если пользователь отклонил его до открытия экрана. ContextCompat.checkSelfPermission возвращает одно и то же значение — PERMISSION_DENIED — в двух случаях: до того как приложение впервые запросило разрешение, и после того как пользователь его отклонил. Чтобы различить эти ситуации, сохраняйте результат запроса разрешения и считывайте его в резолвере. Если приложение ещё не запрашивало разрешение, возвращайте нативный вид вместо null и запрашивайте разрешение внутри этого вида. Например, запросите доступ к геолокации при появлении вида карты и отобразите карту сразу после того, как пользователь предоставит доступ. Если вы вернёте null, а пользователь затем предоставит разрешение, он по-прежнему увидит запасной вариант. Изменение разрешения не заставляет SDK повторно вызывать резолвер. Нативный вид появится только после того, как SDK снова вызовет резолвер — например, когда пользователь вернётся на этот экран.
Передайте resolver в SDK
Начните с резолвера уровня приложения. SDK вызывает его в каждом флоу без собственного резолвера. Пользователи увидят ваши нативные экраны в новых флоу и A/B-тестах без релиза приложения. Эти экраны по-прежнему отображают данные конкретного пользователя, например ежедневную серию, считывая их из вашего приложения.
Прикрепите resolver к одному флоу, если флоу требует данных, которые ваше приложение получает только в момент открытия этого флоу. Например, пейвол отображает вес, который пользователь ввёл в предыдущем флоу, или показывает предварительный просмотр документа, который пользователь хочет экспортировать. Также можно прикрепить resolver к одному флоу, чтобы отображать другой вид для Type в этом флоу.
Отображение представлений в каждом флоу
Чтобы использовать resolver в каждом флоу, вызовите AdaptyUI.setCustomElementsResolver один раз, например в методе onCreate вашего класса Application:
Чтобы отображать одно и то же представление для каждого пользовательского элемента определённого типа, передайте в AdaptyCustomElementsResolver.of карту типов и представлений. Карта требует меньше кода, чем класс-резолвер, но вы не сможете задать условия для резервного контента.
val appWideViews = mapOf(
"confetti" to AdaptyCustomElementContent.compose { LottieElement("confetti.json") },
)
AdaptyUI.setCustomElementsResolver(AdaptyCustomElementsResolver.of(appWideViews))Отображение данных для одного флоу, например документа для экспорта
Резолвер, который вы передаёте во view флоу, заменяет общий резолвер приложения в этом view флоу.
Чтобы сохранить общие view приложения в этом флоу, передайте общий резолвер в данный резолвер и вызывайте общий резолвер для остальных Types и IDs. Следующий резолвер предпросматривает документ, который пользователь хочет экспортировать, и вызывает общий резолвер для всех остальных пользовательских элементов:
Передайте резолвер в параметре customElementsResolver метода AdaptyUI.getFlowView:
Если вы создаёте AdaptyFlowView самостоятельно, передайте резолвер в метод showFlow. В Java showFlow принимает те же аргументы, что и getFlowView, кроме activity. В Jetpack Compose передайте резолвер в AdaptyFlowScreen. Примеры каждого вызова смотрите в разделе Отображение флоу и пейволов.
Если вы используете AdaptyCustomElementsResolver.of вместо классов-резолверов, объедините карту глобальных представлений с картой для этого флоу: AdaptyCustomElementsResolver.of(appWideViews + flowViews). Передайте результат во view флоу. Если один и тот же тип присутствует в обеих картах, будет использоваться view для этого флоу.
Протестируйте на устройстве
Paywall Builder не может выполнять код вашего приложения, поэтому на его холсте отображается только резервный вариант. Ошибка в нативном представлении может привести к сбою приложения. Перед релизом протестируйте каждый экран с кастомным элементом на реальном устройстве:
-
Чтобы видеть последнюю опубликованную версию каждого флоу, а не кэшированную, зарегистрируйте устройство как тестовое.
-
Чтобы видеть предупреждения Adapty SDK в Logcat, установите уровень логирования равным
AdaptyLogLevel.WARNили более подробным. При уровне по умолчаниюAdaptyLogLevel.NONESDK ничего не логирует. -
На устройстве запустите сборку с резолвером. Откройте каждый экран с кастомным элементом и убедитесь, что нативный вид отображается и вписывается в этот элемент. Если вид поддерживает прокрутку или реагирует на жесты перетаскивания, проверьте их.
-
Если вместо нативного вида отображается резервный, найдите в Logcat предупреждение:
custom element <type>:<id> is not served by a resolver. Затем убедитесь, что:- Тип и ID в предупреждении совпадают с указанными в вашем коде, символ за символом.
- Приложение имеет доступ к файлу, данным или разрешению, которые нужны виду.
- Приложение устанавливает общий резолвер.
- Резолвер для этого флоу, если он передаётся, возвращает вид для данного типа и ID.
If the warning doesn’t appear, verify that the app uses Adapty Android SDK 4.4 or later.
-
If the custom element stays empty, find one of these warnings in Logcat:
custom element <type>:<id> is not served by a resolver: The custom element has no fallback content, and no resolver returns a view for it. Verify each item in step 4.content does not report its size: The composable has no height of its own. Give the custom element a Fixed height.
- SDK записывает предупреждение о размере только для компонентов (composables). Если Android
Viewостаётся пустым без предупреждения, задайте элементу Fixed высоту тоже.
-
Чтобы просмотреть резервный пейвол, верните
nullдля Type и откройте экран снова.
Примеры
Каждый рецепт показывает настройку в билдере и код для вашего приложения:
- Показ прогресса пользователя с помощью анимации Lottie: Кольцо, которое заполняется по мере роста серии.
- Показ интерактивного графика цели по весу в пейволе: График цели по весу в пейволе, который следует за флоу онбординга.
- Показ ближайших мест на карте во флоу: Карта фитнес-центров рядом с каждым пользователем.