Отображение пользовательских элементов с помощью iOS SDK
Когда открывается экран с пользовательским элементом, Adapty SDK передаёт тип и ID элемента в резолвер в коде вашего приложения. Резолвер возвращает одно из следующего:
- Вид, соответствующий Type и ID: пользователи видят нативный SwiftUI-вид — например, Lottie-анимацию, интерактивный график или превью камеры.
- Нет вида: пользователи видят резервный вариант — содержимое внутри кастомного элемента в Flow & Paywall Builder.
Если у пользователя устаревшая версия приложения — в которой резолвер ещё отсутствует — он всё равно увидит резервный контент. Поэтому флоу можно опубликовать ещё до выпуска обновления приложения.
Прежде чем начать
Вам понадобится:
- Adapty iOS SDK 4.4 или новее: Более ранние версии отображают фолбэк для каждого кастомного элемента.
- Нативное iOS-приложение: SDK Adapty для кроссплатформенных фреймворков, таких как Flutter, показывают фолбэк для каждого кастомного элемента.
- Схема именования кастомных элементов: Задайте каждому нативному виду тип (Type), например
lottie_animation. Используйте в типах только строчные буквы, цифры и знаки подчёркивания. Чтобы различать кастомные элементы одного типа, присвойте каждому идентификатор (ID), напримерwelcome_wave. Типы и идентификаторы в коде должны совпадать с теми, что указаны в Flow & Paywall Builder.
Создайте представления для пользовательских элементов
Для каждого типа создайте нативное представление SwiftUI или используйте уже существующее из вашего приложения. Следующее представление типа lottie_animation воспроизводит Lottie-анимацию:
struct LottieElementView: View {
let animation: LottieAnimation?
var body: some View {
LottieView(animation: animation)
.resizable()
.looping()
}
}
Просмотр требований и рекомендаций
- Размер:
- Отступы и выравнивание: Убедитесь, что нативный вид вписывается в контейнер, выделенный для него во Flow & Paywall Builder, с учётом отступов. Если вид не занимает всю область, по умолчанию он отображается в левом верхнем углу этой области. Чтобы изменить его положение, измените выравнивание в разделе Layout кастомного элемента.
- Высота Hug: Если для высоты кастомного элемента задано значение Hug, вид, растягивающийся на всё доступное пространство (например, карта), схлопнется. Задайте кастомному элементу фиксированную высоту.
- Действия флоу: Нативный вид не может запускать действия флоу, например переход к следующему экрану. Кнопки навигации, кнопки покупки и другие кнопки с действиями флоу размещайте за пределами кастомного элемента.
- Выбираемые элементы: Размещайте кастомный элемент за пределами карточек продуктов и других выбираемых элементов. При изменении выбора нативный вид может потерять своё состояние.
- Обработка навигации: Когда пользователь переходит на следующий экран, SwiftUI запускает действие
onDisappearнативного вида. В этом действии останавливайте всё, что запустил вид: сессии камеры, плееры, обновления геолокации. Для асинхронных задач используйте.task: SwiftUI отменяет их при исчезновении вида. Когда пользователь возвращается, SDK снова вызывает резолвер, и SwiftUI сбрасывает состояние вида. - UIKit-виды: Оборачивайте их в
UIViewRepresentable.
Напишите резолвер для сопоставления пользовательских элементов и представлений
Чтобы написать резолвер, сделайте тип соответствующим протоколу AdaptyUICustomElementsResolver и реализуйте метод view(forType:id:context:).
Для типа lottie_animation следующий резолвер возвращает LottieElementView. ID указывает на файл анимации в бандле приложения, например welcome_wave:
struct CustomElementsResolver: AdaptyUICustomElementsResolver {
func view(
forType type: String,
id: String,
context: AdaptyUICustomElementContext
) -> AnyView? {
switch type {
case "lottie_animation":
// the ID names the animation file, such as welcome_wave.json
guard let animation = LottieAnimation.named(id) else {
return nil // no file for this ID: show the fallback
}
return AnyView(LottieElementView(animation: animation))
default:
return nil
}
}
}
В случае default возвращайте nil. Если после релиза приложения вы добавите кастомный элемент с новым типом, пользователи выпущенной версии увидят его резервный вариант.
К резолверу предъявляются следующие требования:
- Сетевые данные и плееры: Храните сетевые данные и плееры в состоянии нативного вью, а не в резолвере. SDK вызывает резолвер много раз, пока экран открыт — например, когда загружаются продукты или начинается покупка. Код в резолвере выполняется заново при каждом вызове, поэтому сетевые запросы повторяются, а плееры начинают сначала. SwiftUI сохраняет состояние нативного вью между вызовами, поэтому данные загружаются один раз, а плееры продолжают воспроизведение. Создавайте плееры, сессии и сетевые запросы в
.taskили в@StateObject, а не в начальном значении свойства@State. Swift вычисляет это начальное значение заново каждый раз, когда резолвер создаёт вью. - Одно нативное вью на каждый кастомный элемент: Некоторые нативные вью меняются, пока экран открыт — например, когда загружаются данные или пользователь нажимает на них. Реализуйте эту логику в самом
bodyвью, а не в резолвере. Если резолвер возвращает другое вью для того же кастомного элемента, SwiftUI сбрасывает его состояние. - Данные приложения: Храните объект приложения с нужными данными — например,
ObservableObjectс ежедневной серией — в свойстве резолвера. Передайте объект в нативное вью и наблюдайте за ним там с помощью@ObservedObject. Значение, скопированное в резолвер (например, счётчик серии), остаётся таким, каким было на момент создания резолвера. Не используйте environment objects для этих данных: при использовании UIKit флоу контроллера нативное вью не получает SwiftUI-окружение вашего приложения.
Задайте условия для резервного контента
Чтобы показывать пользователям резервный контент вместо пустого кастомного элемента, возвращайте nil в следующих ситуациях:
- Нечего отображать — необходимый файл анимации или файл данных отсутствует.
- Нечего обрабатывать — пользователь пропустил вопрос квиза, и данные неполные.
- Доступ запрещён — отклонённое разрешение не даёт представлению обратиться к ресурсу.
Например, оператор guard в резолвере возвращает nil, если файл анимации отсутствует.
Для разрешения возвращайте nil только в том случае, если пользователь уже отказал в нём до открытия экрана. Если пользователь ещё не ответил на запрос разрешения, верните нативный вид вместо nil и запросите разрешение внутри него. Например, в Показ ближайших мест на карте во флоу iOS показывает запрос доступа к геолокации, когда появляется карта. Нативный вид может отобразить карту сразу после того, как пользователь предоставит доступ. Если вернуть nil до того, как пользователь ответит, резервный элемент останется даже после предоставления доступа — до следующего вызова resolver’а со стороны SDK.
Передайте резолвер в SDK
Начните с резолвера на уровне всего приложения. SDK вызывает его в каждом флоу, у которого нет собственного резолвера. Пользователи видят ваши нативные экраны в новых флоу и A/B-тестах без обновления приложения. Эти экраны по-прежнему показывают каждому пользователю его собственные данные — например, ежедневную серию, — поскольку получают их из вашего приложения.
Прикрепите резолвер к одному флоу, когда флоу требует данные, которые ваше приложение получает только при его открытии. Например, пейвол отображает вес, введённый пользователем в предыдущем флоу, или предпросмотр документа, который пользователь хочет экспортировать. Вы также можете прикрепить резолвер к одному флоу, чтобы показать другой вид для Type в этом флоу.
Установите глобальный резолвер
Чтобы использовать резолвер во всех флоу, вызовите AdaptyUI.setCustomElementsResolver(_:) один раз — например, при запуске приложения:
// keep this instance: a resolver for one flow can reuse it
@MainActor let customElementsResolver = CustomElementsResolver()
AdaptyUI.setCustomElementsResolver(customElementsResolver)
Более простая и ограниченная альтернатива подходу с резолвером — передать словарь [String: AdaptyUICustomElementBuilder] с ключами типа. Это требует меньше кода, но вы не сможете задать условия для резервного контента.
AdaptyUI.setCustomElementsResolver([
"lottie_animation": .init { _, id, _ in LottieElementView(animation: .named(id)) },
])Привяжите резолвер к одному флоу
Резолвер, привязанный к флоу, заменяет общий резолвер приложения в этом флоу. Значения, переданные этому резолверу, остаются такими же, какими они были при получении конфигурации флоу. Чтобы отобразить новые значения, получите конфигурацию повторно.
Чтобы сохранить общие представления приложения в этом флоу, передайте общий резолвер в этот резолвер и вызывайте его для всех остальных типов и ID. Следующий резолвер отображает предпросмотр документа, который пользователь хочет экспортировать, и вызывает общий резолвер для всех остальных пользовательских элементов:
struct ExportPaywallResolver: AdaptyUICustomElementsResolver {
let document: Document // the document that the user wants to export
let appWideResolver: any AdaptyUICustomElementsResolver
func view(
forType type: String,
id: String,
context: AdaptyUICustomElementContext
) -> AnyView? {
if type == "document_preview" {
return AnyView(DocumentPreview(document: document))
}
// other Types: the views of the app-wide resolver
return appWideResolver.view(forType: type, id: id, context: context)
}
}
Прикрепите resolver к флоу при получении его конфигурации:
func showExportPaywall(flow: AdaptyFlow, document: Document) async {
do {
let flowConfiguration = try await AdaptyUI.getFlowConfiguration(
forFlow: flow,
customElementsResolver: ExportPaywallResolver(
document: document,
appWideResolver: customElementsResolver // the instance that you set app-wide
)
)
// present the flow
} catch {
// handle the error
}
}
Если вы используете словари вместо резолверов, объедините их и передайте результат во флоу: appWideViews.merging(flowViews) { _, flowView in flowView }. Если один и тот же тип встречается в обоих словарях, этот код оставит вариант из текущего флоу.
Тестирование на устройстве
Paywall Builder не может выполнять код приложения, поэтому на его холсте отображается только резервный вариант. Ошибка в нативном представлении может привести к краше приложения. Перед релизом протестируйте каждый экран с кастомным элементом на реальном устройстве:
-
Чтобы видеть актуальную опубликованную версию каждого флоу вместо кэшированной, зарегистрируйте устройство как тестовое устройство.
-
На устройстве запустите сборку с резолвером. Откройте каждый экран с пользовательским элементом и проверьте, что нативный вид отображается и вписывается в пользовательский элемент. Если вид прокручивается или реагирует на жесты перетаскивания, протестируйте эти жесты.
-
Если вместо нативного вида появляется резервный, найдите в консоли Xcode предупреждение:
custom element <type>:<id> is not served by a resolver. Затем проверьте:- Тип и ID в предупреждении совпадают с указанными в вашем коде, символ в символ.
- Приложение имеет доступ к файлу, данным или разрешению, необходимым для отображения вида.
- Приложение устанавливает общий резолвер до открытия экрана с пользовательским элементом.
- Резолвер для этого флоу, если он задан, возвращает вид для данного типа и ID.
Если предупреждение не появляется, убедитесь, что приложение использует Adapty iOS SDK 4.4 или новее, и что
Adapty.logLevelне установлен в.error. -
Чтобы просмотреть резервный пейвол, верните
nilдля Type и откройте экран снова.
Примеры
Каждый пример показывает настройку в билдере и код для вашего приложения:
- Отображение прогресса пользователя с помощью Lottie-анимации: Кольцо, которое заполняется по мере роста серии.
- Отображение интерактивного графика целевого веса на пейволе: График целевого веса на пейволе, который следует за онбординг-флоу.
- Отображение ближайших мест на карте во флоу: Карта фитнес-центров рядом с каждым пользователем.