Отображение пользовательских элементов с помощью 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)
Tip

Более простая и ограниченная альтернатива подходу с резолвером — передать словарь [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 не может выполнять код приложения, поэтому на его холсте отображается только резервный вариант. Ошибка в нативном представлении может привести к краше приложения. Перед релизом протестируйте каждый экран с кастомным элементом на реальном устройстве:

  1. Чтобы видеть актуальную опубликованную версию каждого флоу вместо кэшированной, зарегистрируйте устройство как тестовое устройство.

  2. На устройстве запустите сборку с резолвером. Откройте каждый экран с пользовательским элементом и проверьте, что нативный вид отображается и вписывается в пользовательский элемент. Если вид прокручивается или реагирует на жесты перетаскивания, протестируйте эти жесты.

  3. Если вместо нативного вида появляется резервный, найдите в консоли Xcode предупреждение: custom element <type>:<id> is not served by a resolver. Затем проверьте:

    • Тип и ID в предупреждении совпадают с указанными в вашем коде, символ в символ.
    • Приложение имеет доступ к файлу, данным или разрешению, необходимым для отображения вида.
    • Приложение устанавливает общий резолвер до открытия экрана с пользовательским элементом.
    • Резолвер для этого флоу, если он задан, возвращает вид для данного типа и ID.

    Если предупреждение не появляется, убедитесь, что приложение использует Adapty iOS SDK 4.4 или новее, и что Adapty.logLevel не установлен в .error.

  4. Чтобы просмотреть резервный пейвол, верните nil для Type и откройте экран снова.

Примеры

Каждый пример показывает настройку в билдере и код для вашего приложения: