---
title: "Кастомные элементы"
description: "Добавьте нативный элемент, например анимацию Lottie / Rive, интерактивный график или превью камеры, на экран флоу."
---

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

С помощью пользовательского элемента во Flow & Paywall Builder вы можете добавить нативный вид на экран флоу. Это может быть анимация Lottie / Rive, интерактивный график, карта, превью камеры — или любой другой вид, который может отображать ваше приложение. Пользователи видят нативный вид только в приложениях, использующих Adapty iOS SDK 4.4 или выше. Приложения, использующие Adapty Android SDK или SDK для кроссплатформенного фреймворка, например Flutter или React Native, показывают резервный вариант для каждого пользовательского элемента.

Чтобы отобразить нативный вью на экране флоу:

1. [Добавьте пользовательский элемент](#add-and-configure) на экран и укажите его **Type** и **ID**.
2. [Добавьте резервный контент](#set-fallback-content) внутри пользовательского элемента. Пользователи видят его, когда приложение не отображает представление.
3. [Настройте нативное представление в приложении](#set-up-your-app-code). Используйте Adapty SDK, чтобы присвоить ему те же Type и ID.
4. [Опубликуйте флоу](#publish-and-test) и протестируйте его на устройстве.
5. [Выпустите обновление приложения с нативным представлением](#what-changes-require-an-app-release). Пользователи версий приложения без нативного представления увидят резервный контент.

:::tip
Чтобы отобразить изображение или анимированное видео, используйте элемент [**Image**](custom-media#image) или [**Video**](custom-media#video) вместо пользовательского элемента. Ни для одного из них не нужен код в приложении, а файл можно заменить без выпуска обновления.
:::

## 1. Добавьте пользовательский элемент на экран \{#add-and-configure\}

1. Откройте панель **Add element**. В группе **Media** нажмите **Custom element**.

2. Если нативный вид реагирует на касания, не размещайте пользовательский элемент в контейнерах, которые тоже реагируют на касания, например в карусели. Так свайп по нативному виду не будет прокручивать карусель.
3. В поле **Type** укажите тип нативного вида, например `lottie_animation`:
   - **Правила именования**: используйте только строчные буквы, цифры и знаки подчёркивания.
   - **Точное совпадение**: тип должен совпадать с тем, что указан в вашем приложении, символ в символ. При любом другом написании пользователи увидят резервный вариант.
   - **Подсказки**: поле предлагает типы, уже используемые в этом флоу, а не те, что заданы в вашем приложении.
4. В поле **ID** замените предзаполненное значение, например `custom_1`, на идентификатор по своему выбору, например `welcome_wave`. Идентификатор позволяет различать пользовательские элементы одного типа.

5. Чтобы зарезервировать фиксированное пространство под нативный вид, оставьте высоту по умолчанию **Fixed**. Задайте значение, которое нужно этому виду.
   - **Shared area**: нативный вид и резервный контент занимают одну и ту же область.
   - **Alignment**: если нативный вид меньше этой области, по умолчанию он отображается в верхнем левом углу. Чтобы изменить положение, настройте выравнивание в разделе **Layout** настроек кастомного элемента.

   :::important
   При высоте **Hug** нативный вид без собственной высоты, например карта или список с прокруткой, сжимается почти до нулевой высоты.
   :::

6. (Опционально) Чтобы обрезать нативный вид по скруглённым **Corners** пользовательского элемента, в разделе **Layout** установите флажок **Clip content**.

### Использование нативных представлений в нескольких пользовательских элементах \{#use-native-views-in-several-custom-elements\}

Следующие правила применяются к типу и ID пользовательских элементов:

- **Type**: Укажите один Type для каждого вида нативного представления, например `lottie_animation` для Lottie-плеера и `map` для карты.
- **ID**: В рамках одного Type присвойте уникальный ID каждому элементу контента, например `streak_ring` и `welcome_wave` для двух Lottie-анимаций. Приложение читает ID, чтобы определить нужный контент. Если два кастомных элемента на одном экране имеют одинаковые Type и ID, в поле **ID** появится предупреждение: *Same type and ID as another element on this screen.* Опубликовать флоу при этом всё равно можно.
- **Копии элементов**: При дублировании или вставке элемента, а также при добавлении [вкладки](builder-tabs) билдер переименовывает каждый скопированный ID, который уже занят на данном экране или компоненте. Например, `custom_1` становится `custom_2`, а `hero` — `hero_2`. Убедитесь, что код вашего приложения ссылается на правильный ID.

## 2. Добавьте резервный контент \{#set-fallback-content\}

Пользователь увидит резервный контент вместо нативного представления в следующих случаях:

- Версия вашего приложения не включает код этого представления.
- Приложение использует Android SDK Adapty, SDK для кроссплатформенного фреймворка или iOS SDK Adapty версии ниже 4.4.
- Тип и ID кастомного элемента не совпадают ни с одним представлением в коде приложения.
- Код приложения находит совпадение по Типу и ID, но не возвращает представление. Например, для него нужен файл, которого нет на устройстве, или разрешение, в котором пользователь отказал.

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

Flow & Paywall Builder не может выполнять код вашего приложения, поэтому на его холсте показывается только резервный контент. [Превью в мобильном приложении Adapty](paywall-device-compatibility-preview#preview-on-devices) тоже отображает резервный контент. Чтобы увидеть нативный вид, [протестируйте флоу на устройстве](#publish-and-test) в сборке вашего приложения.

:::important
Размещайте кнопки навигации, кнопки покупки и другие важные элементы интерфейса за пределами кастомного элемента. Пользователь видит либо нативное представление, либо фолбэк — никогда оба сразу.
:::

Внутрь кастомного элемента нельзя добавить **Footer**, **Sliding sheet** или **Bottom Sheet**.

## 3. Настройте нативный вид в вашем приложении \{#set-up-your-app-code\}

Когда открывается экран с кастомным элементом, Adapty SDK передаёт Type и ID этого элемента в функцию-резолвер в коде вашего приложения. Резолвер возвращает одно из следующего:

- **Вид, соответствующий Type и ID**: пользователи видят нативный вид. В коде указывайте Type и ID точно так же, как в билдере.
- **Ничего**: пользователи видят резервный вариант. Например, возвращайте пустой результат, если нужный файл отсутствует на устройстве.

Для кода iOS следуйте инструкции [Отображение пользовательских элементов с помощью iOS SDK](ios-flow-custom-elements). В ней показано, как написать resolver и протестировать нативный вид на устройстве.

:::tip
Нативный вид может визуализировать данные пользователя, например ответы из более раннего флоу. См. [Показ интерактивного графика цели по весу в пейволе](custom-element-interactive-chart).
:::

## 4. Опубликуйте и протестируйте флоу \{#publish-and-test\}

Чтобы [опубликовать флоу](builder-save-publish), убедитесь, что у каждого пользовательского элемента задан Type, соответствующий [правилам именования](#add-and-configure). Вы можете опубликовать флоу до релиза приложения. До тех пор пока пользователи не обновят приложение, они будут видеть резервный пейвол.

Ошибка в нативном представлении может привести к краху приложения. Перед релизом протестируйте каждый экран с пользовательским элементом в сборке с нативным представлением. Чтобы протестировать флоу, который реальные пользователи ещё не видят, добавьте его в [плейсмент](create-placement), который запрашивает эта сборка, но не запрашивает опубликованное приложение. Чтобы видеть последний опубликованный флоу, а не закэшированный, зарегистрируйте устройство как [тестовое](test-devices). Подробную инструкцию читайте в разделе [Тестирование на устройстве](ios-flow-custom-elements#test-on-a-device).

## Какие изменения требуют выпуска обновления приложения \{#what-changes-require-an-app-release\}

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

| Изменённый контент | Что делать | Что видят пользователи, не обновившие приложение |
|---|---|---|
| Нативное представление существующего кастомного элемента, например новая анимация | Выпустить обновление приложения с новым нативным представлением | Предыдущее нативное представление, если оно есть в их версии приложения |
| Нативное представление для нового кастомного элемента | Выпустить обновление приложения с новым нативным представлением. Добавить кастомный элемент с новым Type и ID, опубликовать флоу | Резервный контент |
| Существующее нативное представление на другом экране, в другом флоу или в A/B-тесте | Добавить кастомный элемент с тем же Type и ID, опубликовать флоу. Обновление приложения не нужно, если ваш [общий резолвер](ios-flow-custom-elements#set-an-app-wide-resolver) возвращает нужное представление | Нативное представление, если оно есть в их версии приложения |
| Type или ID кастомного элемента | Выпустить обновление приложения с нативным представлением для нового Type и ID, опубликовать флоу | Резервный контент |
| Резервный контент, другие настройки кастомного элемента | Опубликовать флоу. Обновление приложения не нужно | Обновлённый контент |

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

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

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

## Устранение неполадок \{#troubleshooting\}

- **Пользователи видят резервный вариант вместо нативного отображения**: убедитесь, что Type и ID в точности совпадают с теми, что используются в вашем приложении. Пользователи версий приложения без этого отображения будут видеть резервный вариант до обновления. Чтобы найти причину в коде, воспользуйтесь разделом [Test on a device](ios-flow-custom-elements#test-on-a-device) в гайде для iOS.
- **Пользователи видят пустую область**: [добавьте резервный контент](#set-fallback-content) и опубликуйте флоу. Если пустая область по-прежнему отображается на [тестовом устройстве](test-devices), нативное отображение появляется без содержимого. Убедитесь, что resolver возвращает `nil` при отсутствии контента, как описано в разделе [Set conditions for fallback content](ios-flow-custom-elements#set-conditions-for-fallback-content).
- **Нативное отображение не вписывается в кастомный элемент**: убедитесь, что приложение подгоняет отображение под область кастомного элемента. Чтобы обрезать отображение по скруглённым **Corners**, в разделе **Layout** установите флажок **Clip content**.