Получение флоу и пейволов — Unity
GetFlow После того как вы разработали свой флоу, его можно отобразить в мобильном приложении. Первый шаг — получить флоу или пейвол, привязанный к плейсменту, вместе с его конфигурацией отображения, как описано ниже.
Хотите увидеть реальный пример интеграции Adapty SDK в мобильное приложение? Посмотрите наши примеры приложений, которые демонстрируют полную настройку, включая отображение пейволов, совершение покупок и другую базовую функциональность.
Прежде чем начать
Вам понадобится:
- Продукты в дашборде Adapty: Создайте продукты.
- Флоу с продуктами: Создайте его в Flow & Paywall Builder и назначьте продукты.
- Плейсмент: Создайте плейсмент и назначьте ему флоу.
- Установленный SDK: Смотрите руководство по установке Unity SDK.
Получение флоу/пейвола
Если вы создали флоу или пейвол в билдере, вам не нужно думать о том, как отрендерить его в коде мобильного приложения для показа пользователю. Такой флоу или пейвол уже содержит и то, что должно отображаться, и то, как именно это должно выглядеть. Тем не менее вам нужно получить его ID через плейсмент, конфигурацию вида, а затем показать его в мобильном приложении.
Для оптимальной производительности важно получать флоу или пейвол и его конфигурацию отображения как можно раньше — чтобы изображения успели загрузиться до того, как вы покажете их пользователю.
Чтобы прогреть несколько плейсментов сразу, вызовите Adapty.PreloadFlows (Unity SDK 4.3.0+). Метод кэширует только JSON плейсмента, поэтому CreateFlowView всё равно загружает макет и изображения.
Чтобы получить флоу или пейвол, используйте метод GetFlow:
Adapty.GetFlow(
"YOUR_PLACEMENT_ID",
AdaptyPlacementFetchPolicy.Default,
TimeSpan.FromSeconds(5),
(flow, error) => {
if (error != null) {
// handle the error
return;
}
// flow - the requested flow/paywall
}
);Параметры:
| Параметр | Наличие | Описание |
|---|---|---|
| placementId | обязательный | Идентификатор нужного плейсмента. Это значение вы указываете при создании плейсмента в дашборде Adapty. |
| fetchPolicy | по умолчанию: AdaptyPlacementFetchPolicy.Default |
Однако если у ваших пользователей нестабильное интернет-соединение, рассмотрите Третья политика, Обратите внимание, что кэш сохраняется при перезапуске приложения и очищается только при его переустановке или вручную. Adapty SDK хранит флоу и пейволы локально в двух слоях: регулярно обновляемый кэш, описанный выше, и резервные пейволы. Мы также используем CDN для ускорения загрузки и отдельный резервный сервер на случай недоступности CDN. Система спроектирована так, чтобы вы всегда получали актуальную версию даже при нестабильном интернет-соединении. |
| loadTimeout | по умолчанию: 5 сек | Это значение ограничивает таймаут данного метода. Если сервер Adapty не отвечает вовремя или возвращает ошибку, SDK возвращает кэшированный флоу. Если кэш пуст, а сервер превысил таймаут или вернул ошибку, SDK запрашивает флоу с резервного сервера (копия CDN, обслуживающая только аудиторию All Users плейсмента). В крайнем случае SDK возвращает флоу из вашего резервного файла. Обратите внимание, что в редких случаях метод может завершить работу немного позже, чем указано в |
Параметры ответа:
| Параметр | Описание |
|---|---|
| Flow | Объект AdaptyFlow, содержащий плейсмент, идентификаторы (InstanceIdentity, VariationId), название, название варианта (VariationName, SDK 4.3.0+), варианты пейвола (Paywalls — список объектов AdaptyFlowPaywall) и Remote Config (RemoteConfigs — список с одной записью на каждую локаль). Чтобы получить продукты для предзагрузки, кастомного UI или программных проверок, вызовите GetPaywallProducts(flow). |
Получение конфигурации представления
После получения флоу или пейвола загрузите конфигурацию представления и создайте представление за один шаг с помощью метода CreateFlowView. Отдельного флага для проверки нет: если плейсмент был создан в Flow & Paywall Builder (флоу) или в old Paywall Builder (пейвол), CreateFlowView вернёт представление, готовое к показу. Если плейсмент — это кастомный пейвол без интерфейса Builder, CreateFlowView вернёт ошибку — отрисуйте его самостоятельно.
Убедитесь, что вы опубликовали флоу. Флоу с неопубликованными изменениями имеет статус Dirty, и его плейсмент продолжает отдавать последнюю опубликованную версию.
var parameters = new AdaptyUICreateFlowViewParameters()
.SetPreloadProducts(true)
.SetLoadTimeout(TimeSpan.FromSeconds(5));
AdaptyUI.CreateFlowView(flow, parameters, (view, error) => {
if (error != null) {
// the flow has no view configured, or view creation failed
return;
}
// use view
});
| Параметр | Наличие | Описание |
|---|---|---|
| flow | обязательный | Объект AdaptyFlow, полученный через Adapty.GetFlow. |
| Locale | необязательный | Идентификатор локализации Builder для отображения флоу или пейвола, например en или pt-br. Флоу локализуется при создании вью, поэтому это единственное место для выбора локализации. SDK не считывает локаль устройства: если параметр не указан, флоу отображается на en или в локали по умолчанию, если локализация en отсутствует. Код должен точно совпадать с кодом локализации флоу. См. Использование локализаций и кодов локалей. |
| LoadTimeout | необязательный | Ограничивает таймаут для этого метода. При достижении таймаута будут возвращены кэшированные данные или локальный резервный вариант. Обратите внимание, что в редких случаях метод может завершиться чуть позже значения, указанного в LoadTimeout, поскольку операция может состоять из нескольких запросов. |
| PreloadProducts | необязательный | Установите значение true, чтобы заранее загрузить продукты для повышения производительности. При включении продукты загружаются заблаговременно, сокращая время отображения флоу или пейвола. |
| CustomTags | необязательный | Значения вашего приложения для кастомных тегов флоу в виде словаря, где ключ — полное имя тега. Передайте словарь в метод SetCustomTags. Подробнее см. в разделе Передача данных во флоу. |
| CustomTimers | необязательный | Даты окончания таймеров Developer defined флоу в виде словаря из идентификаторов таймеров и значений DateTime. Передайте словарь в метод SetCustomTimers. Подробнее см. в разделе Настройка таймеров, определяемых разработчиком. |
| ProductPurchaseParameters | необязательный | Только для Android (игнорируется на iOS). Словарь из AdaptyProductIdentifier в AdaptyPurchaseParameters. Используйте для настройки параметров покупки, например персонализированных предложений или параметров обновления подписки для отдельных продуктов во флоу или пейволе. |
| EnableSafeAreaPaddings | необязательный | Только для Android (игнорируется на iOS). Если true, вью флоу применяет отступы безопасной зоны. По умолчанию: true. Значение по умолчанию подходит для большинства случаев. |
Если вы используете несколько языков, узнайте, как добавить локализацию в Builder.
После загрузки покажите флоу или пейвол.
Получите флоу или пейвол для аудитории по умолчанию, чтобы ускорить загрузку
Обычно флоу и пейволы загружаются почти мгновенно, так что беспокоиться об ускорении этого процесса не нужно. Однако если у вас много аудиторий и плейсментов, а у пользователей слабое интернет-соединение, загрузка флоу или пейвола может занять больше времени, чем хотелось бы. В таких ситуациях имеет смысл показывать флоу или пейвол по умолчанию — это обеспечит плавный пользовательский опыт вместо пустого экрана.
Чтобы решить эту задачу, можно воспользоваться методом GetFlowForDefaultAudience, который получает флоу или пейвол указанного плейсмента для аудитории All Users. Однако важно понимать, что рекомендуемый подход — получать флоу или пейвол через метод GetFlow, как описано в разделе Получение флоу/пейвола выше.
Почему мы рекомендуем использовать GetFlow
Метод GetFlowForDefaultAudience имеет ряд существенных недостатков:
- Возможные проблемы с обратной совместимостью: если нужно показывать разные флоу для разных версий приложения (текущей и будущих), могут возникнуть сложности. Придётся либо проектировать флоу с учётом текущей (устаревшей) версии, либо мириться с тем, что у пользователей этой версии флоу может не отображаться.
- Потеря таргетинга: все пользователи будут видеть один и тот же флоу, настроенный для аудитории All Users, — то есть вы теряете персонализированный таргетинг (в том числе по странам, маркетинговой атрибуции или собственным кастомным атрибутам).
Если вы готовы принять эти ограничения ради более быстрой загрузки флоу или пейвола, используйте метод GetFlowForDefaultAudience следующим образом. В противном случае используйте GetFlow, описанный выше.
Adapty.GetFlowForDefaultAudience(
"YOUR_PLACEMENT_ID",
AdaptyPlacementFetchPolicy.Default,
(flow, error) => {
if (error != null) {
// handle the error
return;
}
// flow - the requested flow
}
);
| Параметр | Наличие | Описание |
|---|---|---|
| placementId | обязательный | Идентификатор плейсмента. Это значение вы указали при создании плейсмента в дашборде Adapty. |
| fetchPolicy | по умолчанию: AdaptyPlacementFetchPolicy.Default |
Однако если вы считаете, что у ваших пользователей нестабильное интернет-соединение, рассмотрите вариант Третья политика, Обратите внимание, что кэш сохраняется при перезапуске приложения и очищается только при его переустановке или принудительной очистке вручную. |
Настройка ресурсов
Чтобы настроить изображения и видео в своём флоу или пейволе, используйте пользовательские ресурсы.
Главные изображения и видео имеют предопределённые идентификаторы: hero_image и hero_video. В наборе пользовательских ресурсов вы обращаетесь к этим элементам по их идентификаторам и настраиваете их поведение.
Для других изображений и видео необходимо задать пользовательский идентификатор в дашборде Adapty.
Например, вы можете:
- Показывать разные изображения или видео разным пользователям.
- Показывать локальное превью, пока загружается основное изображение с сервера.
- Показывать превью перед воспроизведением видео.
- Показывать медиафайлы, встроенные в приложение, чтобы первый экран отображался без загрузки. См. Показ медиа первого экрана из бандла приложения.
Вот пример того, как можно передавать пользовательские ресурсы через простой словарь:
var customAssets = new Dictionary<string, AdaptyCustomAsset>
{
{ "custom_image", AdaptyCustomAsset.LocalImageFile("custom_assets/images/custom_image.png") },
{ "hero_video", AdaptyCustomAsset.LocalVideoFile("custom_assets/videos/custom_video.mp4") }
};
var parameters = new AdaptyUICreateFlowViewParameters()
.SetCustomAssets(customAssets)
.SetLoadTimeout(TimeSpan.FromSeconds(3));
AdaptyUI.CreateFlowView(flow, parameters, (view, error) => {
// handle the result
});Если ресурс не найден или не загружается, флоу или пейвол вернётся к внешнему виду по умолчанию, заданному в Builder.
Настройка таймеров, заданных разработчиком
Используйте этот раздел для таймера с поведением Developer defined в Flow & Paywall Builder. В билдере каждый такой таймер имеет Timer ID (см. Позвольте вашему приложению задать дату окончания), и ваше приложение устанавливает для него дату окончания. Используйте в коде тот же Timer ID, что и в билдере, символ в символ, включая регистр и пробелы. Если ID не совпадают, таймер не получит дату окончания от вашего приложения.
Чтобы задать даты окончания, передайте словарь с идентификаторами таймеров и их датами окончания в метод SetCustomTimers. Объект DateTime с DateTimeKind.Utc интерпретируется как UTC-время; объект DateTime без указания типа считается локальным временем пользователя. Пример:
var customTimers = new Dictionary<string, DateTime> {
{ "CUSTOM_TIMER_6H", DateTime.Now.AddHours(6) },
{ "CUSTOM_TIMER_NY", new DateTime(DateTime.Now.Year + 1, 1, 1) } // next New Year's Day, local time
};
var parameters = new AdaptyUICreateFlowViewParameters()
.SetCustomTimers(customTimers)
.SetLoadTimeout(TimeSpan.FromSeconds(3));
AdaptyUI.CreateFlowView(flow, parameters, (view, error) => {
if (error != null) {
// handle the error
return;
}
// use view
});В этом примере CUSTOM_TIMER_NY и CUSTOM_TIMER_6H — это идентификаторы двух таймеров типа Developer defined в билдере:
CUSTOM_TIMER_NY: время, оставшееся до следующего Нового года.CUSTOM_TIMER_6H: время, оставшееся в 6-часовом периоде, который начался, когда ваше приложение создало вью.
SDK считывает пользовательские таймеры один раз — в момент создания представления. Поэтому вычисляемая дата, например CUSTOM_TIMER_6H, отсчитывается с этого момента, даже если пользователь открывает экран повторно. Если дата уже в прошлом, таймер сразу показывает ноль и срабатывает триггер On timer end. Если в словаре нет ключа для Timer ID, таймер отсчитывает один час с момента открытия экрана.
После того как вы разработали визуальную часть пейвола в старом Paywall Builder в дашборде Adapty, вы можете отобразить его в своём мобильном приложении. Первый шаг — получить пейвол, связанный с плейсментом, и его конфигурацию отображения, как описано ниже.
Пейволы, созданные в Paywall Builder для SDK 3.x, требуют Unity SDK версии 3.3.0 или выше.
Пожалуйста, учтите, что эта тема относится к пейволам, настроенным с помощью Paywall Builder. Если вы используете кастомные пейволы, обратитесь к разделу Получение пейволов и продуктов для кастомных пейволов в мобильном приложении.
Хотите увидеть реальный пример интеграции Adapty SDK в мобильное приложение? Посмотрите наши примеры приложений, которые демонстрируют полную настройку, включая отображение пейволов, совершение покупок и другую базовую функциональность.
Перед тем как начать показывать пейволы в мобильном приложении (нажмите, чтобы развернуть)
- Создайте продукты в дашборде Adapty.
- Создайте пейвол и добавьте в него продукты в дашборде Adapty.
- Создайте плейсменты и добавьте в них пейвол в дашборде Adapty.
- Установите Adapty SDK в своём мобильном приложении.
Получение пейвола, созданного в Paywall Builder
Если вы создали пейвол в Paywall Builder, вам не нужно беспокоиться о его отображении в коде мобильного приложения — пейвол уже содержит всё необходимое: что и как должно быть показано. Тем не менее, вам нужно получить его ID через плейсмент, конфигурацию отображения, а затем показать пейвол в приложении.
Для оптимальной производительности важно получать пейвол и его конфигурацию отображения как можно раньше, чтобы изображения успели загрузиться до того, как пользователь увидит пейвол.
Чтобы получить пейвол, используйте метод GetPaywall:
Adapty.GetPaywall("YOUR_PLACEMENT_ID", "en", (paywall, error) => {
if(error != null) {
// handle the error
return;
}
// paywall - the resulting object
});Параметры:
| Параметр | Наличие | Описание |
|---|---|---|
| placementId | обязательный | Идентификатор нужного плейсмента. Это значение вы указывали при создании плейсмента в дашборде Adapty. |
| locale | необязательный по умолчанию: | Идентификатор локализации пейвола. Ожидается код языка, состоящий из одного или двух подтегов, разделённых символом минус (-). Первый подтег обозначает язык, второй — регион. Например: Подробнее о кодах локализаций и рекомендациях по их использованию см. в разделе Локализации и коды локалей. |
| fetchPolicy | по умолчанию: AdaptyPlacementFetchPolicy.Default |
Однако если у ваших пользователей нестабильное интернет-соединение, рассмотрите Третья политика, Обратите внимание: кеш сохраняется при перезапуске приложения и очищается только при его переустановке или вручную. Adapty SDK хранит пейволы локально в двух слоях: регулярно обновляемый кеш, описанный выше, и резервные пейволы. Также используется CDN для более быстрой загрузки пейволов и отдельный резервный сервер на случай недоступности CDN. Система спроектирована так, чтобы вы всегда получали актуальную версию пейволов, сохраняя надёжность даже при плохом интернет-соединении. |
| loadTimeout | по умолчанию: 5 сек | Это значение ограничивает таймаут данного метода. Если сервер Adapty не отвечает вовремя или возвращает ошибку, SDK возвращает пейвол с резервного сервера (копия из CDN, которая обслуживает только аудиторию All Users данного плейсмента), из кеша или из вашего резервного файла. Обратите внимание: в редких случаях таймаут этого метода может наступить немного позже, чем указано в |
Параметры ответа:
| Параметр | Описание |
|---|---|
| Paywall | Объект AdaptyPaywall со списком ID продуктов, идентификатором пейвола, Remote Config и рядом других свойств. |
Получение конфигурации отображения пейвола, созданного в Paywall Builder
Убедитесь, что в Paywall Builder включён переключатель Show on device. Если эта опция не активирована, конфигурация отображения не будет доступна для получения.
После получения пейвола проверьте, содержит ли он ViewConfiguration — это признак того, что пейвол был создан с помощью Paywall Builder. Это определит, как именно его отображать. Если ViewConfiguration присутствует, обрабатывайте пейвол как созданный в Paywall Builder; если нет — обработайте его как кастомный пейвол.
В Unity SDK напрямую вызывайте метод CreatePaywallView, не запрашивая конфигурацию вью вручную.
Результат метода CreatePaywallView можно использовать только один раз. Если нужно использовать его повторно, вызовите CreatePaywallView заново. Повторный вызов без пересоздания может привести к ошибке AdaptyUIError.viewAlreadyPresented.
var parameters = new AdaptyUICreatePaywallViewParameters()
.SetPreloadProducts(preloadProducts)
.SetLoadTimeout(new TimeSpan(0, 0, 3));
AdaptyUI.CreatePaywallView(paywall, parameters, (view, error) => {
// handle the result
});Параметры:
| Параметр | Наличие | Описание |
|---|---|---|
| paywall | обязательный | Объект AdaptyPaywall для получения контроллера нужного пейвола. |
| loadTimeout | по умолчанию: 5 сек | Ограничивает таймаут для этого метода. Если таймаут истёк, будут возвращены кешированные данные или локальный резервный пейвол. Обратите внимание, что в редких случаях метод может завершиться с небольшой задержкой сверх значения loadTimeout, поскольку операция может включать несколько запросов под капотом. |
| PreloadProducts | опциональный | Передайте массив AdaptyPaywallProducts для оптимизации времени отображения продуктов на экране. Если передать nil, AdaptyUI автоматически загрузит необходимые продукты. |
| CustomTags | опциональный | Задайте словарь пользовательских тегов и их значений. Пользовательские теги служат плейсхолдерами в контенте пейвола и динамически заменяются конкретными строками для персонализации. Подробнее см. в разделе о пользовательских тегах в Paywall Builder. |
| CustomTimers | опциональный | Задайте словарь пользовательских таймеров и дат их окончания. Пользовательские таймеры позволяют отображать обратный отсчёт на пейволе. |
Если вы поддерживаете несколько языков, добавьте локализацию к вашему пейволу. Коды для использования см. в Локализации и коды локалей.
Когда у вас есть представление, покажите пейвол.
Настройка ассетов
Чтобы настроить изображения и видео на пейволе, используйте кастомные ассеты.
Hero-изображения и видео имеют предопределённые идентификаторы: hero_image и hero_video. В бандле кастомных ассетов вы обращаетесь к этим элементам по их идентификаторам и настраиваете их поведение.
Для остальных изображений и видео нужно задать кастомный идентификатор в дашборде Adapty.
Например, вы можете:
- Показывать разные изображения или видео разным пользователям.
- Показывать локальное превью-изображение, пока загружается основное удалённое.
- Показывать превью-изображение перед запуском видео.
Чтобы использовать эту функцию, обновите Adapty Unity SDK до версии 3.8.0 или выше.
Вот пример того, как можно передавать пользовательские ресурсы через простой словарь:
var customAssets = new Dictionary<string, AdaptyCustomAsset>
{
{ "custom_image", AdaptyCustomAsset.LocalImageFile("custom_assets/images/custom_image.png") },
{ "hero_video", AdaptyCustomAsset.LocalVideoFile("custom_assets/videos/custom_video.mp4") }
};
var parameters = new AdaptyUICreatePaywallViewParameters()
.SetCustomAssets(customAssets)
.SetLoadTimeout(new TimeSpan(0, 0, 3));
AdaptyUI.CreatePaywallView(paywall, parameters, (view, error) => {
// handle the result
});Если ресурс не найден, пейвол вернётся к внешнему виду по умолчанию.
Настройка таймеров, заданных разработчиком
Чтобы использовать кастомные таймеры в Unity-приложении, передайте словарь с ID таймеров и датами их окончания напрямую в метод SetCustomTimers. Пример:
var customTimers = new Dictionary<string, DateTime> {
{ "CUSTOM_TIMER_6H", DateTime.Now.AddHours(6) },
{ "CUSTOM_TIMER_NY", new DateTime(2025, 1, 1) }
};
var parameters = new AdaptyUICreatePaywallViewParameters()
.SetCustomTimers(customTimers)
.SetLoadTimeout(new TimeSpan(0, 0, 3));
AdaptyUI.CreatePaywallView(paywall, parameters, (view, error) => {
// handle the result
});В этом примере CUSTOM_TIMER_NY и CUSTOM_TIMER_6H — это Timer ID таймеров, заданных разработчиком в дашборде Adapty. Резолвер таймеров обеспечивает динамическое обновление каждого таймера с правильным значением. Например:
CUSTOM_TIMER_NY: время, оставшееся до окончания таймера, например до Нового года.CUSTOM_TIMER_6H: время, оставшееся в 6-часовом периоде, который начался, когда пользователь открыл пейвол.
Ускорьте загрузку пейвола с помощью пейвола аудитории по умолчанию
Как правило, пейволы загружаются почти мгновенно, и беспокоиться об ускорении этого процесса не нужно. Однако если у вас много аудиторий и пейволов, а пользователи работают в условиях слабого интернет-соединения, загрузка пейвола может занять больше времени, чем хотелось бы. В таких ситуациях стоит показывать пейвол по умолчанию — это обеспечит плавный пользовательский опыт вместо полного отсутствия пейвола.
Чтобы решить эту задачу, можно использовать метод GetPaywallForDefaultAudience, который получает пейвол указанного плейсмента для аудитории All Users. Однако важно понимать, что рекомендуемый подход — получать пейвол методом getPaywall, как описано в разделе Получение пейвола выше.
Рекомендуем использовать GetPaywall вместо GetPaywallForDefaultAudience, так как последний имеет важные ограничения:
- Проблемы совместимости: могут возникнуть сложности при поддержке нескольких версий приложения — придётся либо делать обратно совместимые дизайны, либо мириться с тем, что в старых версиях пейвол может отображаться некорректно.
- Нет персонализации: показывает контент только для аудитории «Все пользователи», без таргетинга по стране, атрибуции или кастомным атрибутам.
Если скорость загрузки важнее этих недостатков для вашего сценария использования, используйте GetPaywallForDefaultAudience, как показано ниже. В противном случае используйте GetPaywall, как описано выше.
Adapty.GetPaywallForDefaultAudience("YOUR_PLACEMENT_ID", "en", (paywall, error) => {
if(error != null) {
// handle the error
return;
}
// paywall - the resulting object
});Параметры:
| Параметр | Наличие | Описание |
|---|---|---|
| placementId | обязательный | Идентификатор нужного плейсмента. Это значение, которое вы указали при создании плейсмента в дашборде Adapty. |
| locale | опциональный по умолчанию: | Идентификатор локализации пейвола. Ожидается языковой код, состоящий из одного или двух подтегов, разделённых символом минус (-). Первый подтег — язык, второй — регион. Например: |
| fetchPolicy | по умолчанию: AdaptyPlacementFetchPolicy.Default |
Однако если у ваших пользователей нестабильный интернет, рассмотрите Третья политика, Обратите внимание: кэш сохраняется при перезапуске приложения и очищается только при его переустановке или вручную. Adapty SDK хранит пейволы локально в двух слоях: регулярно обновляемый кэш, описанный выше, и резервные пейволы. Для более быстрой загрузки мы также используем CDN и отдельный резервный сервер на случай недоступности CDN. Система спроектирована так, чтобы вы всегда получали актуальную версию пейволов с надёжностью даже при слабом интернет-соединении. |