Получение флоу и пейволов — Unity

После того как вы разработали свой флоу, его можно отобразить в мобильном приложении. Первый шаг — получить флоу или пейвол, привязанный к плейсменту, вместе с его конфигурацией отображения, как описано ниже.

Прежде чем начать

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

• Продукты в дашборде Adapty: Создайте продукты.
• Флоу с продуктами: Создайте его в Flow & Paywall Builder и назначьте продукты.
• Плейсмент: Создайте плейсмент и назначьте ему флоу.
• Установленный SDK: Смотрите руководство по установке Unity SDK.

Получение флоу/пейвола

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

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

Чтобы получить флоу или пейвол, используйте метод 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	fetchPolicy определяет, какой слой SDK читает первым, а не то, может ли он использовать кэш. По умолчанию SDK сначала обращается к серверу и возвращает кэшированные данные, если запрос не удался. Мы рекомендуем этот вариант, поскольку он гарантирует, что пользователи всегда получают актуальные данные. Однако если у ваших пользователей нестабильное интернет-соединение, рассмотрите AdaptyPlacementFetchPolicy.ReturnCacheDataElseLoad — он меняет порядок на обратный: сначала читает кэш и обращается к серверу только если кэш пуст. Пользователи могут не получить самые свежие данные, зато загрузка будет быстрее вне зависимости от качества соединения. Кэш регулярно обновляется, поэтому его безопасно использовать в течение сессии, чтобы сократить количество сетевых запросов. Третья политика, AdaptyPlacementFetchPolicy.ReturnCacheDataIfNotExpiredElseLoad(maxAge), находится между двумя описанными: она сначала читает кэш, пока его копия «моложе» переданного значения TimeSpan, и обращается к серверу, когда кэш устарел. Обратите внимание: кэш сохраняется при перезапуске приложения и очищается только при его переустановке или при ручной очистке. Adapty SDK хранит флоу и пейволы локально в двух слоях: регулярно обновляемый кэш, описанный выше, и резервные пейволы. Мы также используем CDN для более быстрой загрузки и отдельный резервный сервер на случай недоступности CDN. Эта система гарантирует, что вы всегда получаете актуальную версию, обеспечивая надёжность даже при слабом интернет-соединении.
loadTimeout	по умолчанию: 5 сек	Это значение ограничивает таймаут для данного метода. Если таймаут истекает, возвращаются кэшированные данные или локальный резервный вариант. Обратите внимание: в редких случаях метод может завершиться чуть позже указанного в loadTimeout значения, поскольку операция может включать несколько запросов под капотом.

Параметр	Описание
Flow	Объект AdaptyFlow, содержащий плейсмент, идентификаторы (InstanceIdentity, VariationId), название, варианты пейволов (Paywalls — список объектов AdaptyFlowPaywall) и Remote Config (RemoteConfigs — список с одной записью на каждую локаль). Чтобы получить продукты для предзагрузки, кастомного UI или программных проверок, вызовите GetPaywallProducts(flow).

Получение конфигурации вида

После получения флоу или пейвола загрузите конфигурацию вида и создайте его в один шаг с помощью метода CreateFlowView. Отдельного флага для проверки нет: если плейсмент был создан в Flow & Paywall Builder (флоу) или old Paywall Builder (пейвол), CreateFlowView возвращает вид, готовый к показу. Если плейсмент — это кастомный пейвол без интерфейса Builder, CreateFlowView возвращает ошибку — обработайте его как пейвол с Remote Config.

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. Подробнее: Передача данных во флоу.
ProductPurchaseParameters	необязательный	Только Android (игнорируется на iOS). Словарь AdaptyProductIdentifier → AdaptyPurchaseParameters. Используется для настройки параметров покупки — например, персонализированных предложений или параметров обновления подписки — для отдельных продуктов во флоу или пейволе.
EnableSafeAreaPaddings	необязательный	Только Android (игнорируется на iOS). Если true, представление флоу применяет отступы для безопасной зоны. По умолчанию: true. Значение по умолчанию подходит для большинства случаев.

После загрузки покажите флоу или пейвол.

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

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

Чтобы решить эту задачу, можно воспользоваться методом GetFlowForDefaultAudience, который получает флоу или пейвол указанного плейсмента для аудитории All Users. Однако важно понимать, что рекомендуемый подход — получать флоу или пейвол через метод 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	fetchPolicy определяет, какой слой SDK читает первым, а не то, может ли он использовать кэш. По умолчанию SDK сначала обращается к серверу и возвращает кэшированные данные, если запрос не удался. Мы рекомендуем этот вариант, поскольку он гарантирует, что пользователи всегда получают актуальные данные. Однако если вы считаете, что у ваших пользователей нестабильное интернет-соединение, рассмотрите вариант AdaptyPlacementFetchPolicy.ReturnCacheDataElseLoad, который меняет порядок на обратный — сначала читает кэш и обращается к серверу только тогда, когда кэш пуст. Пользователи могут не получить самые последние данные, но загрузка будет быстрее вне зависимости от качества соединения. Кэш регулярно обновляется, поэтому его безопасно использовать в течение сессии, чтобы избежать лишних сетевых запросов. Третья политика, AdaptyPlacementFetchPolicy.ReturnCacheDataIfNotExpiredElseLoad(maxAge), занимает промежуточное положение: она читает кэш, пока его возраст меньше переданного значения TimeSpan, и обращается к серверу, когда кэш устарел. Обратите внимание, что кэш сохраняется при перезапуске приложения и очищается только при его переустановке или принудительной очистке вручную.

Настройка ресурсов

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

Главные изображения и видео имеют предопределённые идентификаторы: 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
});

Настройка таймеров, заданных разработчиком

Чтобы использовать пользовательские таймеры в приложении Unity, передайте словарь с идентификаторами таймеров и датами их окончания в метод SetCustomTimers. Пример:

var customTimers = new Dictionary<string, DateTime> {
    { "CUSTOM_TIMER_6H", DateTime.Now.AddHours(6) },
    { "CUSTOM_TIMER_NY", new DateTime(2026, 1, 1) }
};

var parameters = new AdaptyUICreateFlowViewParameters()
    .SetCustomTimers(customTimers)
    .SetLoadTimeout(TimeSpan.FromSeconds(3));

AdaptyUI.CreateFlowView(flow, parameters, (view, error) => {
    // handle the result
});

В этом примере CUSTOM_TIMER_NY и CUSTOM_TIMER_6H — это Timer ID пользовательских таймеров, заданных вами в дашборде Adapty. Резолвер таймеров обеспечивает динамическое обновление каждого таймера корректным значением в вашем приложении. Например:

• CUSTOM_TIMER_NY: время, оставшееся до окончания действия таймера, например до Нового года.
• CUSTOM_TIMER_6H: время, оставшееся в 6-часовом периоде, который начался, когда пользователь открыл флоу или пейвол.

После того как вы разработали визуальную часть пейвола в старом Paywall Builder в дашборде Adapty, вы можете отобразить его в своём мобильном приложении. Первый шаг — получить пейвол, связанный с плейсментом, и его конфигурацию отображения, как описано ниже.

Обратите внимание: эта тема относится к пейволам, созданным с помощью Paywall Builder. Если вы реализуете пейволы вручную, обратитесь к теме Получение пейволов и продуктов для пейволов с Remote Config в мобильном приложении.

Прежде чем начать отображать пейволы в мобильном приложении (нажмите, чтобы развернуть)

1. Создайте продукты в дашборде Adapty.
2. Создайте пейвол и добавьте в него продукты в дашборде Adapty.
3. Создайте плейсменты и добавьте в них пейвол в дашборде Adapty.
4. Установите 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	опциональный по умолчанию: en	Идентификатор локализации пейвола. Ожидается код языка, состоящий из одного или двух подтегов, разделённых символом минуса (-). Первый подтег — язык, второй — регион. Например: en означает английский, pt-br — бразильский португальский. Подробнее о кодах локализации и рекомендациях по их использованию см. в разделе Локализации и коды локалей.
fetchPolicy	по умолчанию: AdaptyPlacementFetchPolicy.Default	fetchPolicy определяет, какой слой SDK читает первым, а не то, может ли он использовать кэш. По умолчанию SDK сначала обращается к серверу и возвращает кэшированные данные, если запрос не удался. Мы рекомендуем этот вариант, так как он гарантирует, что пользователи всегда получают актуальные данные. Однако если у ваших пользователей нестабильное интернет-соединение, рассмотрите AdaptyPlacementFetchPolicy.ReturnCacheDataElseLoad — он меняет порядок: сначала читает кэш и обращается к серверу только при отсутствии кэшированных данных. Пользователи могут не получить самые свежие данные, зато загрузка будет быстрее независимо от качества соединения. Кэш регулярно обновляется, поэтому его безопасно использовать в рамках сессии, чтобы избежать лишних сетевых запросов. Третья политика, AdaptyPlacementFetchPolicy.ReturnCacheDataIfNotExpiredElseLoad(maxAge), находится между двумя описанными: она читает кэш, пока его возраст не превышает переданный TimeSpan, и обращается к серверу, когда кэш устарел. Обратите внимание: кэш сохраняется после перезапуска приложения и очищается только при переустановке или вручную. Adapty SDK хранит пейволы локально в двух слоях: регулярно обновляемый кэш, описанный выше, и резервные пейволы. Для более быстрой загрузки пейволов используется CDN, а также отдельный резервный сервер на случай недоступности CDN. Эта система гарантирует, что вы всегда получаете актуальную версию пейволов, обеспечивая надёжность даже при слабом интернете.
loadTimeout	по умолчанию: 5 сек	Значение ограничивает тайм-аут этого метода. При его истечении будут возвращены кэшированные данные или локальный резервный пейвол. Обратите внимание: в редких случаях метод может завершиться с небольшой задержкой относительно указанного в loadTimeout, поскольку операция может включать несколько запросов.

Параметры ответа:

Параметр	Описание
Paywall	Объект AdaptyPaywall со списком ID продуктов, идентификатором пейвола, Remote Config и рядом других свойств.

Получение конфигурации отображения пейвола, созданного в Paywall Builder

После загрузки пейвола проверьте, содержит ли он ViewConfiguration — это признак того, что пейвол создан в Paywall Builder. Это поможет вам понять, как отображать пейвол. Если ViewConfiguration присутствует, обрабатывайте его как пейвол Paywall Builder; если нет — обработайте его как пейвол с Remote Config.

В Unity SDK напрямую вызывайте метод CreatePaywallView, не запрашивая конфигурацию вью вручную.

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.

Например, вы можете:

• Показывать разные изображения или видео разным пользователям.
• Показывать локальное превью-изображение, пока загружается основное удалённое.
• Показывать превью-изображение перед запуском видео.

Вот пример того, как можно передавать пользовательские ресурсы через простой словарь:

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, как описано в разделе Получение пейвола выше.

Adapty.GetPaywallForDefaultAudience("YOUR_PLACEMENT_ID", "en", (paywall, error) => {
  if(error != null) {
    // handle the error
    return;
  }
  
  // paywall - the resulting object
});

Параметры:

Параметр	Наличие	Описание
placementId	обязательный	Идентификатор нужного плейсмента. Это значение, которое вы указали при создании плейсмента в дашборде Adapty.
locale	опциональный по умолчанию: en	Идентификатор локализации пейвола. Ожидается языковой код, состоящий из одного или двух подтегов, разделённых символом минус (-). Первый подтег — язык, второй — регион. Например: en означает английский, pt-br — бразильский португальский.
fetchPolicy	по умолчанию: AdaptyPlacementFetchPolicy.Default	fetchPolicy определяет, какой слой SDK читает первым, а не то, может ли он использовать кэш. По умолчанию SDK сначала обращается к серверу и возвращает кэшированные данные, если запрос не удался. Мы рекомендуем этот вариант — он гарантирует, что пользователи всегда получают актуальные данные. Однако если у ваших пользователей нестабильный интернет, рассмотрите AdaptyPlacementFetchPolicy.ReturnCacheDataElseLoad — он меняет порядок на обратный: сначала читает кэш и обращается к серверу только при его отсутствии. Пользователи могут получить не самые свежие данные, зато загрузка будет быстрее независимо от качества соединения. Кэш регулярно обновляется, поэтому его безопасно использовать в рамках сессии для сокращения сетевых запросов. Третья политика, AdaptyPlacementFetchPolicy.ReturnCacheDataIfNotExpiredElseLoad(maxAge), находится между двумя вышеописанными: сначала читает кэш, пока его возраст меньше переданного TimeSpan, и обращается к серверу, когда кэш устаревает. Обратите внимание: кэш сохраняется при перезапуске приложения и очищается только при его переустановке или вручную. Adapty SDK хранит пейволы локально в двух слоях: регулярно обновляемый кэш, описанный выше, и резервные пейволы. Для более быстрой загрузки мы также используем CDN и отдельный резервный сервер на случай недоступности CDN. Система спроектирована так, чтобы вы всегда получали актуальную версию пейволов с надёжностью даже при слабом интернет-соединении.