Получение флоу и пейволов — Flutter
getFlow После того как вы разработали свой флоу, его можно отобразить в мобильном приложении. Первый шаг — получить флоу или пейвол, связанный с плейсментом, и конфигурацию его отображения, как описано ниже.
Обратите внимание, что этот раздел относится к флоу и пейволам, созданным в билдерах Adapty. Если вы реализуете пользовательские пейволы, обратитесь к разделу Получение пейволов и продуктов для кастомных пейволов в мобильном приложении.
Хотите увидеть реальный пример интеграции Adapty SDK в мобильное приложение? Посмотрите наши примеры приложений, которые демонстрируют полную настройку, включая отображение пейволов, совершение покупок и другую базовую функциональность.
Прежде чем начать
Вам понадобится:
- Продукты в дашборде Adapty: Создайте продукты.
- Флоу с продуктами: Создайте его в Flow & Paywall Builder и назначьте продукты.
- Плейсмент: Создайте плейсмент и назначьте ему флоу.
- Установленный SDK: Смотрите руководство по установке Flutter SDK.
Получение флоу/пейвола
Если вы создали флоу или пейвол в конструкторе, не нужно беспокоиться о его рендеринге в коде мобильного приложения для отображения пользователю. Такой флоу или пейвол содержит всё необходимое — и что именно показывать, и как это делать. Тем не менее, вам нужно получить его ID через плейсмент, конфигурацию его представления, а затем отобразить в мобильном приложении.
Получите флоу или пейвол и создайте его представление как можно раньше — в идеале задолго до его показа. Метод createFlowView загружает конфигурацию представления и запускает фоновое скачивание и кэширование изображений. Чем раньше вы его вызовете, тем больше времени будет на загрузку. К моменту показа флоу или пейвола его конфигурация и изображения уже могут быть закэшированы и готовы к отображению.
Чтобы прогреть несколько плейсментов сразу, вызовите preloadFlows (Flutter SDK 4.3.0+). Метод кэширует только JSON плейсмента, поэтому createFlowView всё равно загружает макет и изображения.
Чтобы получить флоу или пейвол, используйте метод getFlow:
try {
final flow = await Adapty().getFlow(placementId: 'YOUR_PLACEMENT_ID');
// the requested flow/paywall
} on AdaptyError catch (adaptyError) {
// handle the error
} catch (e) {
// handle the error
}Параметры:
| Параметр | Наличие | Описание |
|---|---|---|
| placementId | обязательный | Идентификатор нужного плейсмента. Это значение вы указывали при создании плейсмента в дашборде Adapty. |
| fetchPolicy | по умолчанию: AdaptyFlowFetchPolicy.reloadRevalidatingCacheData |
Однако если вы считаете, что у ваших пользователей нестабильное интернет-соединение, рассмотрите Третья политика, Обратите внимание, что кэш сохраняется при перезапуске приложения и очищается только при его переустановке или вручную. Adapty SDK хранит пейволы локально в двух слоях: регулярно обновляемый кэш, описанный выше, и резервные пейволы. Также используется CDN для более быстрой загрузки пейволов и отдельный резервный сервер на случай недоступности CDN. Эта система обеспечивает получение актуальной версии пейволов и надёжность даже при плохом интернет-соединении. |
| loadTimeout | по умолчанию: 5 сек |
Обратите внимание, что в редких случаях метод может завершиться чуть позже указанного в |
Параметры ответа
| Параметр | Описание |
|---|---|
| Flow | Объект AdaptyFlow с идентификаторами флоу (instanceIdentity, variationId), именем, плейсментом, вариантами пейволов (paywalls) и Remote Config (remoteConfigs). |
Получение конфигурации представления
Убедитесь, что опубликовали флоу. Флоу с неопубликованными изменениями имеет статус Dirty, и его плейсмент продолжает показывать последнюю опубликованную версию.
Если плейсмент был создан в Flow & Paywall Builder или старом Paywall Builder, Adapty отрисовывает интерфейс самостоятельно — свойство hasViewConfiguration полученного флоу равно true. Создайте представление с помощью createFlowView, затем покажите флоу или пейвол. Если плейсмент является кастомным пейволом без Builder-интерфейса (hasViewConfiguration равно false), отрисуйте его самостоятельно.
По умолчанию при закрытии результат метода createFlowView освобождается, и повторно показать его не получится. Если нужно снова показать флоу или пейвол, вызовите метод createFlowView заново или закройте без освобождения — доступно в SDK 4.1 и выше.
try {
final view = await AdaptyUI().createFlowView(flow: flow);
} on AdaptyError catch (e) {
// handle the error
} catch (e) {
// handle the error
}Параметры:
| Параметр | Наличие | Описание |
|---|---|---|
| flow | required | Объект AdaptyFlow для получения представления нужного флоу/пейвола. |
| locale | optional | Идентификатор локализации флоу для отображения представления — например, en или pt-br. Если не указать, представление отображается на en или в локализации флоу по умолчанию, если флоу не имеет en. См. Локализации и коды языков. |
| customLayoutId | optional default: SDK 4.1+ | Пользовательский ID макета в конфигурации макетов флоу. Передайте его, чтобы отрисовать именно этот макет вместо того, который SDK выбирает автоматически исходя из типа устройства и размера экрана. Если ни один макет не соответствует ID, вызов завершится ошибкой AdaptyError. Flow & Paywall Builder пока не назначает пользовательские ID макетам, поэтому оставьте этот параметр пустым. |
| customTags | optional | Значения вашего приложения для кастомных тегов флоу в виде словаря, где ключ — полное имя тега. Подробнее см. в разделе Передача данных во флоу. |
| customTimers | optional | Даты окончания таймеров Developer defined во флоу в виде словаря из ID таймеров и значений DateTime. Подробнее см. в разделе Настройка таймеров, задаваемых разработчиком. |
| preloadProducts | optional | Включите, чтобы оптимизировать время отображения продуктов на экране. При значении true AdaptyUI автоматически загрузит необходимые продукты. По умолчанию: false. |
| loadTimeout | optional | Duration, ограничивающий время загрузки конфигурации представления. При достижении таймаута будут использованы кешированные данные или локальный резервный вариант. |
Если вы используете несколько языков, узнайте, как добавить локализацию флоу и как правильно использовать коды локалей здесь.
После того как вы получили представление, отобразите флоу/пейвол.
Получение флоу или пейвола для аудитории по умолчанию ради ускорения загрузки
Как правило, флоу и пейволы загружаются почти мгновенно, поэтому беспокоиться об ускорении этого процесса не нужно. Однако если у вас много аудиторий и плейсментов, а у пользователей слабое интернет-соединение, загрузка флоу или пейвола может занять больше времени, чем хотелось бы. В таких ситуациях имеет смысл показывать флоу или пейвол по умолчанию — это обеспечит плавный пользовательский опыт вместо пустого экрана.
Чтобы решить эту проблему, используйте метод getFlowForDefaultAudience, который получает флоу или пейвол указанного плейсмента для аудитории All Users. Однако важно понимать, что рекомендуемый подход — получать флоу или пейвол через метод getFlow, как описано в разделе Получение флоу/пейвола выше.
Почему мы рекомендуем использовать getFlow
Метод getFlowForDefaultAudience имеет ряд существенных недостатков:
- Потенциальные проблемы обратной совместимости: если вам нужно показывать разные пейволы для разных версий приложения (текущей и будущих), могут возникнуть сложности. Придётся либо проектировать пейволы с поддержкой текущей (устаревшей) версии, либо мириться с тем, что пользователи этой версии могут столкнуться с нерендеренными пейволами.
- Потеря таргетинга: все пользователи будут видеть один и тот же пейвол, настроенный для аудитории All Users, — это означает потерю персонализированного таргетинга (в том числе по странам, маркетинговой атрибуции или собственным пользовательским атрибутам).
Если вы готовы принять эти недостатки ради более быстрой загрузки флоу или пейвола, используйте метод getFlowForDefaultAudience следующим образом. В противном случае используйте getFlow, описанный выше.
try {
final flow = await Adapty().getFlowForDefaultAudience(placementId: 'YOUR_PLACEMENT_ID');
// the requested flow/paywall
} on AdaptyError catch (adaptyError) {
// handle error
} catch (e) {
// handle unknown error
}
| Параметр | Наличие | Описание |
|---|---|---|
| placementId | обязательный | Идентификатор плейсмента. Это значение вы указали при создании плейсмента в дашборде Adapty. |
| fetchPolicy | по умолчанию: AdaptyFlowFetchPolicy.reloadRevalidatingCacheData |
Однако если у ваших пользователей нестабильный интернет, рассмотрите Третья политика, Обратите внимание, что кэш сохраняется при перезапуске приложения и очищается только при переустановке приложения или в результате ручной очистки. |
Настройка ресурсов
Чтобы настроить изображения и видео во флоу или пейволе, реализуйте пользовательские ресурсы.
У главных изображений и видео есть предопределённые идентификаторы: hero_image и hero_video. В пакете пользовательских ресурсов вы обращаетесь к этим элементам по их идентификаторам и настраиваете их поведение.
Для остальных изображений и видео необходимо задать пользовательский идентификатор в дашборде Adapty.
Например, вы можете:
- Показывать разные изображения или видео разным пользователям.
- Показывать локальное превью, пока загружается основное изображение из сети.
- Показывать превью перед воспроизведением видео.
- Показывать медиафайлы, встроенные в приложение, чтобы первый экран отображался без загрузки. См. Отображение медиа первого экрана из бандла приложения.
Вот пример того, как можно передавать пользовательские ресурсы через простой словарь:
final customAssets = {
// Show a local image using a custom ID
'custom_image': AdaptyCustomAsset.localImageAsset(
assetId: 'assets/images/image_name.png',
),
// Show a local video with a preview image
'hero_video': AdaptyCustomAsset.localVideoAsset(
assetId: 'assets/videos/custom_video.mp4',
),
};
try {
final view = await AdaptyUI().createFlowView(
flow: flow,
customAssets: customAssets,
);
} on AdaptyError catch (e) {
// handle the error
} catch (e) {
// handle the error
}Если ресурс не найден, флоу/пейвол вернётся к внешнему виду по умолчанию.
Настройка таймеров, управляемых разработчиком
Используйте этот раздел для таймера с поведением Developer defined в Flow & Paywall Builder. В билдере у каждого такого таймера есть Timer ID (см. Позвольте приложению задавать дату окончания), а приложение задаёт для него дату окончания. Используйте в коде тот же Timer ID, что и в билдере, — символ в символ, включая регистр букв и пробелы. Если идентификаторы не совпадают, таймер не получит дату окончания от приложения.
Чтобы задать конечные даты, передайте карту customTimers в метод createFlowView. Каждый ключ карты — это идентификатор таймера, а его значение — объект DateTime, определяющий время окончания таймера. Пример:
try {
final view = await AdaptyUI().createFlowView(
flow: flow,
customTimers: {
'CUSTOM_TIMER_6H': DateTime.now().add(const Duration(hours: 6)),
'CUSTOM_TIMER_NY': DateTime(DateTime.now().year + 1), // next New Year's Day
},
);
} on AdaptyError catch (e) {
// handle the error
} catch (e) {
// handle the error
}Для флоу, встроенного через AdaptyUIFlowPlatformView, передайте такой же словарь в параметр customTimers.
В этом примере CUSTOM_TIMER_NY и CUSTOM_TIMER_6H — это идентификаторы двух таймеров типа Developer defined в билдере:
CUSTOM_TIMER_NY: время до следующего Нового года.CUSTOM_TIMER_6H: время до окончания 6-часового периода, который начался в момент создания экрана в вашем приложении.
SDK считывает customTimers один раз — в момент создания представления, поэтому вычисленная дата, например CUSTOM_TIMER_6H, отсчитывается с этого момента, в том числе при повторном открытии экрана. Если дата уже в прошлом, таймер сразу показывает ноль и срабатывает триггер On timer end. Если в customTimers нет ключа для данного Timer ID, таймер отсчитывает один час с момента открытия экрана.
После того как вы разработали визуальную часть пейвола в старом Paywall Builder на дашборде Adapty, его можно отобразить в мобильном приложении. Первый шаг — получить пейвол, связанный с плейсментом, и его конфигурацию отображения, как описано ниже.
Пейволы, созданные в Paywall Builder для SDK 3.x, требуют Flutter SDK версии 3.3.0 или выше.
Пожалуйста, обратите внимание, что эта тема относится к пейволам, настроенным с помощью Paywall Builder. Если вы реализуете кастомные пейволы, обратитесь к теме Получение пейволов и продуктов для кастомных пейволов в мобильном приложении.
Хотите увидеть реальный пример интеграции Adapty SDK в мобильное приложение? Посмотрите наши примеры приложений, которые демонстрируют полную настройку, включая отображение пейволов, совершение покупок и другую базовую функциональность.
Прежде чем начать отображать пейволы в мобильном приложении (нажмите, чтобы развернуть)
- Создайте продукты в дашборде Adapty.
- Создайте пейвол и добавьте в него продукты в дашборде Adapty.
- Создайте плейсменты и добавьте в них пейвол в дашборде Adapty.
- Установите Adapty SDK в своё мобильное приложение.
Получение пейвола, созданного в Paywall Builder
Если вы создали пейвол с помощью Paywall Builder, вам не нужно беспокоиться о его отображении в коде мобильного приложения. Такой пейвол содержит как то, что должно быть показано, так и то, как именно это должно быть показано. Тем не менее, вам нужно получить его ID через плейсмент, конфигурацию отображения, а затем показать пейвол в вашем мобильном приложении.
Для обеспечения оптимальной производительности крайне важно получать пейвол и его конфигурацию отображения как можно раньше, чтобы изображения успели загрузиться до того, как пользователь увидит пейвол.
Для получения пейвола используйте метод getPaywall:
try {
final paywall = await Adapty().getPaywall(placementId: "YOUR_PLACEMENT_ID", locale: "en");
// the requested paywall
} on AdaptyError catch (adaptyError) {
// handle the error
} catch (e) {
}Параметры:
| Параметр | Наличие | Описание |
|---|---|---|
| placementId | обязательный | Идентификатор нужного плейсмента. Это значение вы указали при создании плейсмента в дашборде Adapty. |
| locale | опциональный по умолчанию: | Идентификатор локализации пейвола. Ожидается код языка, состоящий из одного или двух подтегов, разделённых символом минус (-). Первый подтег — язык, второй — регион. Пример: Подробнее о кодах локализации и рекомендациях по их использованию — в разделе Локализации и коды локалей. |
| fetchPolicy | по умолчанию: AdaptyPaywallFetchPolicy.reloadRevalidatingCacheData |
Однако если у ваших пользователей нестабильный интернет, рассмотрите Третья политика, Обратите внимание: кэш сохраняется при перезапуске приложения и очищается только при переустановке или вручную. Adapty SDK хранит пейволы локально в двух слоях: регулярно обновляемый кэш, описанный выше, и резервные пейволы. Также используется CDN для ускорения загрузки и отдельный резервный сервер на случай недоступности CDN. Система разработана так, чтобы вы всегда получали актуальную версию пейволов, сохраняя надёжность даже при нестабильном интернете. |
| loadTimeout | по умолчанию: 5 сек |
Обратите внимание: в редких случаях метод может завершиться по таймауту чуть позже указанного в |
Параметры ответа:
| Параметр | Описание |
|---|---|
| Paywall | Объект AdaptyPaywall со списком идентификаторов продуктов, идентификатором пейвола, Remote Config и рядом других свойств. |
Получение конфигурации пейвола, созданного в Paywall Builder
Убедитесь, что в Paywall Builder включён переключатель Show on device. Если эта опция не активирована, конфигурация отображения не будет доступна для получения.
После получения пейвола проверьте, содержит ли он ViewConfiguration — это признак того, что пейвол был создан в Paywall Builder. Именно это определяет способ его отображения. Если ViewConfiguration присутствует, обрабатывайте его как пейвол Paywall Builder; если нет — обработайте его как кастомный пейвол.
try {
final view = await AdaptyUI().createPaywallView(
paywall: paywall,
);
} on AdaptyError catch (e) {
// handle the error
} catch (e) {
// handle the error
}Когда представление готово, покажите пейвол.
Получение пейвола для аудитории по умолчанию для более быстрой загрузки
Как правило, пейволы загружаются практически мгновенно, поэтому беспокоиться об ускорении этого процесса не нужно. Однако если у вас много аудиторий и пейволов, а интернет-соединение у пользователей нестабильное, загрузка пейвола может занять больше времени, чем хотелось бы. В таких случаях имеет смысл показывать пейвол для аудитории по умолчанию — это обеспечит плавный пользовательский опыт вместо ситуации, когда пейвол не отображается вовсе.
Чтобы решить эту задачу, вы можете использовать метод getPaywallForDefaultAudience, который загружает пейвол указанного плейсмента для аудитории All Users. Однако важно понимать, что рекомендуемый подход — загружать пейвол методом getPaywall, как описано в разделе Получение информации о пейволе выше.
Почему мы рекомендуем использовать getPaywall
Метод getPaywallForDefaultAudience имеет ряд существенных недостатков:
- Возможные проблемы обратной совместимости: если вам нужно показывать разные пейволы для разных версий приложения (текущей и будущих), могут возникнуть трудности. Придётся либо создавать пейволы, совместимые с текущей (устаревшей) версией, либо смириться с тем, что пользователи на текущей (устаревшей) версии могут столкнуться с нерендерящимися пейволами.
- Потеря таргетинга: все пользователи будут видеть один и тот же пейвол, созданный для аудитории All Users, — то есть вы теряете персонализированный таргетинг (включая таргетинг по странам, маркетинговой атрибуции или собственным пользовательским атрибутам).
Если вы готовы принять эти ограничения ради более быстрой загрузки пейвола, используйте метод getPaywallForDefaultAudience следующим образом. В противном случае придерживайтесь метода getPaywall, описанного выше.
try {
final paywall = await Adapty().getPaywallForDefaultAudience(placementId: 'YOUR_PLACEMENT_ID');
} on AdaptyError catch (adaptyError) {
// handle error
} catch (e) {
// handle unknown error
}Метод getPaywallForDefaultAudience доступен начиная с Flutter SDK версии 3.2.0.
| Параметр | Наличие | Описание |
|---|---|---|
| placementId | обязательный | Идентификатор плейсмента. Это значение, которое вы указали при создании плейсмента в дашборде Adapty. |
| locale | опциональный по умолчанию: | Идентификатор локализации пейвола. Ожидается, что этот параметр будет языковым кодом, состоящим из одного или нескольких подтегов, разделённых символом минус (-). Первый подтег обозначает язык, второй — регион. Например: Подробнее о кодах локалей и рекомендациях по их использованию — в разделе Локализации и коды локалей. |
| fetchPolicy | по умолчанию: AdaptyPaywallFetchPolicy.reloadRevalidatingCacheData |
Однако если ваши пользователи часто работают в нестабильном интернете, рассмотрите Третья политика, Обратите внимание: кеш сохраняется при перезапуске приложения и очищается только при его переустановке или вручную. |
Настройка ресурсов
Чтобы настроить изображения и видео на пейволе, реализуйте пользовательские ресурсы.
Для изображений-заголовков и видео-заголовков есть предопределённые идентификаторы: hero_image и hero_video. В пакете пользовательских ресурсов вы обращаетесь к этим элементам по их идентификаторам и настраиваете их поведение.
Для других изображений и видео нужно задать пользовательский идентификатор в дашборде Adapty.
Например, вы можете:
- Показывать разные изображения или видео разным пользователям.
- Показывать локальное превью, пока загружается основное удалённое изображение.
- Показывать превью перед запуском видео.
Чтобы использовать эту функцию, обновите Flutter SDK Adapty до версии 3.8.0 или выше.
Вот пример того, как можно передавать пользовательские ресурсы через простой словарь:
final customAssets = {
// Show a local image using a custom ID
'custom_image': AdaptyCustomAsset.localImageAsset(
assetId: 'assets/images/image_name.png',
),
// Show a local video with a preview image
'hero_video': AdaptyCustomAsset.localVideoAsset(
assetId: 'assets/videos/custom_video.mp4',
),
};
try {
final view = await AdaptyUI().createPaywallView(
paywall: paywall,
customAssets: customAssets,
);
} on AdaptyError catch (e) {
// handle the error
} catch (e) {
// handle the error
}Если ресурс не найден, пейвол вернётся к внешнему виду по умолчанию.
Настройка таймеров, определяемых разработчиком
Чтобы использовать пользовательские таймеры в мобильном приложении, передайте словарь customTimers в метод createPaywallView. Каждый ключ словаря — это идентификатор таймера, а значение — объект DateTime, определяющий момент окончания таймера. Пример:
try {
final view = await AdaptyUI().createPaywallView(
paywall: paywall,
customTimers: {
'CUSTOM_TIMER_6H': DateTime.now().add(const Duration(seconds: 3600 * 6)),
'CUSTOM_TIMER_NY': DateTime(2025, 1, 1), // New Year 2025
},
);
} on AdaptyError catch (e) {
// handle the error
} catch (e) {
// handle the error
}В этом примере CUSTOM_TIMER_NY и CUSTOM_TIMER_6H — это Timer ID пользовательских таймеров, которые вы задали в дашборде Adapty. Словарь customTimers гарантирует, что приложение динамически обновит каждый таймер с нужным значением. Например:
CUSTOM_TIMER_NY: время до окончания таймера, например до Нового года.CUSTOM_TIMER_6H: оставшееся время в 6-часовом периоде, который начался, когда пользователь открыл пейвол.