---
title: "Отображение пользовательских элементов с помощью iOS SDK"
description: "Отображение нативного SwiftUI-представления в каждом пользовательском элементе флоу и тестирование флоу на устройстве."
---

> **AI agents**: to search Adapty docs faster and with fewer tokens, install the Adapty skills: `npx adapty skills install --yes`

Когда открывается экран с [пользовательским элементом](flow-custom-elements), Adapty SDK передаёт тип и ID элемента в резолвер в коде вашего приложения. Резолвер возвращает одно из следующего:

- **Вид, соответствующий Type и ID**: пользователи видят нативный SwiftUI-вид — например, Lottie-анимацию, интерактивный график или превью камеры.
- **Нет вида**: пользователи видят резервный вариант — содержимое внутри кастомного элемента в Flow & Paywall Builder.

Если у пользователя устаревшая версия приложения — в которой резолвер ещё отсутствует — он всё равно увидит резервный контент. Поэтому флоу можно опубликовать ещё до выпуска обновления приложения.

## Прежде чем начать \{#before-you-start\}

Вам понадобится:

- **Adapty iOS SDK 4.4 или новее**: Более ранние версии отображают фолбэк для каждого кастомного элемента.
- **Нативное iOS-приложение**: SDK Adapty для кроссплатформенных фреймворков, таких как Flutter, показывают фолбэк для каждого кастомного элемента.
- **Схема именования кастомных элементов**: Задайте каждому нативному виду тип (Type), например `lottie_animation`. Используйте в типах только строчные буквы, цифры и знаки подчёркивания. Чтобы различать кастомные элементы одного типа, присвойте каждому идентификатор (ID), например `welcome_wave`. Типы и идентификаторы в коде должны совпадать с теми, что указаны в [Flow & Paywall Builder](flow-custom-elements#add-and-configure).

## Создайте представления для пользовательских элементов \{#create-views-for-custom-elements\}

Для каждого типа создайте нативное представление SwiftUI или используйте уже существующее из вашего приложения. Следующее представление типа `lottie_animation` воспроизводит Lottie-анимацию:

```swift showLineNumbers title="Swift"

struct LottieElementView: View {
    let animation: LottieAnimation?

    var body: some View {
        LottieView(animation: animation)
            .resizable()
            .looping()
    }
}
```

### Просмотр требований и рекомендаций \{#view-requirements-and-best-practices\}

- **Размер**:
  - **Отступы и выравнивание**: Убедитесь, что нативный вид вписывается в контейнер, выделенный для него во Flow & Paywall Builder, с учётом отступов. Если вид не занимает всю область, по умолчанию он отображается в левом верхнем углу этой области. Чтобы изменить его положение, измените выравнивание в разделе **Layout** кастомного элемента.
  - **Высота Hug**: Если для высоты кастомного элемента задано значение **Hug**, вид, растягивающийся на всё доступное пространство (например, карта), схлопнется. Задайте кастомному элементу [**фиксированную** высоту](flow-custom-elements#add-and-configure).
- **Действия флоу**: Нативный вид не может запускать действия флоу, например переход к следующему экрану. Кнопки навигации, кнопки покупки и другие кнопки с действиями флоу размещайте за пределами кастомного элемента.
- **Выбираемые элементы**: Размещайте кастомный элемент за пределами карточек продуктов и других [выбираемых элементов](flow-selectable-elements). При изменении выбора нативный вид может потерять своё состояние.
- **Обработка навигации**: Когда пользователь переходит на следующий экран, SwiftUI запускает действие `onDisappear` нативного вида. В этом действии останавливайте всё, что запустил вид: сессии камеры, плееры, обновления геолокации. Для асинхронных задач используйте `.task`: SwiftUI отменяет их при исчезновении вида. Когда пользователь возвращается, SDK снова вызывает резолвер, и SwiftUI сбрасывает состояние вида.
- **UIKit-виды**: Оборачивайте их в `UIViewRepresentable`.

## Напишите резолвер для сопоставления пользовательских элементов и представлений \{#write-a-resolver-to-match-custom-elements-and-views\}

Чтобы написать резолвер, сделайте тип соответствующим протоколу `AdaptyUICustomElementsResolver` и реализуйте метод `view(forType:id:context:)`.

Для типа `lottie_animation` следующий резолвер возвращает `LottieElementView`. ID указывает на файл анимации в бандле приложения, например `welcome_wave`:

```swift showLineNumbers title="Swift"

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`. Если после релиза приложения вы [добавите кастомный элемент с новым типом](flow-custom-elements#what-changes-require-an-app-release), пользователи выпущенной версии увидят его резервный вариант.

К резолверу предъявляются следующие требования:

- **Сетевые данные и плееры**: Храните сетевые данные и плееры в состоянии [нативного вью](#create-views-for-custom-elements), а не в резолвере. SDK вызывает резолвер много раз, пока экран открыт — например, когда загружаются продукты или начинается покупка. Код в резолвере выполняется заново при каждом вызове, поэтому сетевые запросы повторяются, а плееры начинают сначала. SwiftUI сохраняет состояние нативного вью между вызовами, поэтому данные загружаются один раз, а плееры продолжают воспроизведение. Создавайте плееры, сессии и сетевые запросы в `.task` или в `@StateObject`, а не в начальном значении свойства `@State`. Swift вычисляет это начальное значение заново каждый раз, когда резолвер создаёт вью.
- **Одно нативное вью на каждый кастомный элемент**: Некоторые нативные вью меняются, пока экран открыт — например, когда загружаются данные или пользователь нажимает на них. Реализуйте эту логику в самом `body` вью, а не в резолвере. Если резолвер возвращает другое вью для того же кастомного элемента, SwiftUI сбрасывает его состояние.
- **Данные приложения**: Храните объект приложения с нужными данными — например, `ObservableObject` с [ежедневной серией](custom-element-lottie-animation) — в свойстве резолвера. Передайте объект в нативное вью и наблюдайте за ним там с помощью `@ObservedObject`. Значение, скопированное в резолвер (например, счётчик серии), остаётся таким, каким было на момент создания резолвера. Не используйте environment objects для этих данных: при использовании UIKit [флоу контроллера](ios-present-paywalls#present-flows-and-paywalls-in-uikit) нативное вью не получает SwiftUI-окружение вашего приложения.

### Задайте условия для резервного контента \{#set-conditions-for-fallback-content\}

Чтобы показывать пользователям [резервный контент](flow-custom-elements#set-fallback-content) вместо пустого кастомного элемента, возвращайте `nil` в следующих ситуациях:

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

Например, оператор `guard` в [резолвере](#write-a-resolver-to-match-custom-elements-and-views) возвращает `nil`, если файл анимации отсутствует.

Для разрешения возвращайте `nil` только в том случае, если пользователь уже отказал в нём до открытия экрана. Если пользователь ещё не ответил на запрос разрешения, верните нативный вид вместо `nil` и запросите разрешение внутри него. Например, в [Показ ближайших мест на карте во флоу](custom-element-map#3-match-the-map-to-the-custom-element) iOS показывает запрос доступа к геолокации, когда появляется карта. Нативный вид может отобразить карту сразу после того, как пользователь предоставит доступ. Если вернуть `nil` до того, как пользователь ответит, резервный элемент останется даже после предоставления доступа — до следующего вызова resolver'а со стороны SDK.

## Передайте резолвер в SDK \{#pass-the-resolver-to-the-sdk\}

Начните с резолвера на уровне всего приложения. SDK вызывает его в каждом флоу, у которого нет собственного резолвера. Пользователи видят ваши нативные экраны в новых флоу и A/B-тестах без обновления приложения. Эти экраны по-прежнему показывают каждому пользователю его собственные данные — например, [ежедневную серию](custom-element-lottie-animation), — поскольку получают их из вашего приложения.

Прикрепите резолвер к одному флоу, когда флоу требует данные, которые ваше приложение получает только при его открытии. Например, пейвол отображает [вес, введённый пользователем в предыдущем флоу](custom-element-interactive-chart), или предпросмотр документа, который пользователь хочет экспортировать. Вы также можете прикрепить резолвер к одному флоу, чтобы показать другой вид для Type в этом флоу.

### Установите глобальный резолвер \{#set-an-app-wide-resolver\}

Чтобы использовать резолвер во всех флоу, вызовите `AdaptyUI.setCustomElementsResolver(_:)` один раз — например, при запуске приложения:

```swift showLineNumbers title="Swift"

// keep this instance: a resolver for one flow can reuse it
@MainActor let customElementsResolver = CustomElementsResolver()

AdaptyUI.setCustomElementsResolver(customElementsResolver)
```

:::tip
Более простая и ограниченная альтернатива подходу с резолвером — передать словарь `[String: AdaptyUICustomElementBuilder]` с ключами типа. Это требует меньше кода, но вы не сможете [задать условия для резервного контента](#set-conditions-for-fallback-content).

```swift showLineNumbers title="Swift"
AdaptyUI.setCustomElementsResolver([
    "lottie_animation": .init { _, id, _ in LottieElementView(animation: .named(id)) },
])
```
:::

### Привяжите резолвер к одному флоу \{#attach-a-resolver-to-one-flow\}

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

Чтобы сохранить общие представления приложения в этом флоу, передайте общий резолвер в этот резолвер и вызывайте его для всех остальных типов и ID. Следующий резолвер отображает предпросмотр документа, который пользователь хочет экспортировать, и вызывает общий резолвер для всех остальных пользовательских элементов:

```swift showLineNumbers title="Swift"

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 к флоу при получении его конфигурации:

```swift showLineNumbers title="Swift"
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 }`. Если один и тот же тип встречается в обоих словарях, этот код оставит вариант из текущего флоу.

## Тестирование на устройстве \{#test-on-a-device\}

Paywall Builder не может выполнять код приложения, поэтому на его холсте отображается только резервный вариант. Ошибка в нативном представлении может привести к краше приложения. Перед релизом протестируйте каждый экран с кастомным элементом на реальном устройстве:

1. Чтобы видеть актуальную опубликованную версию каждого флоу вместо кэшированной, зарегистрируйте устройство как [тестовое устройство](test-devices).
2. На устройстве запустите сборку с резолвером. Откройте каждый экран с пользовательским элементом и проверьте, что нативный вид отображается и вписывается в пользовательский элемент. Если вид прокручивается или реагирует на жесты перетаскивания, протестируйте эти жесты.
3. Если вместо нативного вида появляется резервный, найдите в консоли Xcode предупреждение: `custom element <type>:<id> is not served by a resolver`. Затем проверьте:
   - Тип и ID в предупреждении совпадают с указанными в вашем коде, символ в символ.
   - Приложение имеет доступ к файлу, данным или разрешению, необходимым для отображения вида.
   - Приложение устанавливает общий резолвер до открытия экрана с пользовательским элементом.
   - [Резолвер для этого флоу](#attach-a-resolver-to-one-flow), если он задан, возвращает вид для данного типа и ID.

   Если предупреждение не появляется, убедитесь, что приложение использует Adapty iOS SDK 4.4 или новее, и что [`Adapty.logLevel`](sdk-installation-ios#logging) не установлен в `.error`.
4. Чтобы просмотреть резервный пейвол, верните `nil` для Type и откройте экран снова.

## Примеры \{#examples\}

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

- [Отображение прогресса пользователя с помощью Lottie-анимации](custom-element-lottie-animation): Кольцо, которое заполняется по мере роста серии.
- [Отображение интерактивного графика целевого веса на пейволе](custom-element-interactive-chart): График целевого веса на пейволе, который следует за онбординг-флоу.
- [Отображение ближайших мест на карте во флоу](custom-element-map): Карта фитнес-центров рядом с каждым пользователем.