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

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

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

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

1. Создайте продукты в дашборде Adapty.
2. Создайте флоу/пейвол и добавьте в него продукты в дашборде Adapty.
3. Создайте плейсменты и добавьте в них флоу/пейвол в дашборде Adapty.
4. Установите Adapty SDK в своём мобильном приложении.

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

Если вы создали флоу или пейвол с помощью Flow Builder или Paywall Builder, вам не нужно беспокоиться о его отображении в коде мобильного приложения. Такой флоу или пейвол содержит всё необходимое: и то, что должно отображаться, и то, как это должно выглядеть. Тем не менее вам нужно получить его ID через плейсмент, настроить конфигурацию отображения и затем показать его в мобильном приложении. Загрузите флоу или пейвол и создайте его представление как можно раньше — желательно задолго до его отображения. Метод createFlowView загружает конфигурацию представления и начинает скачивать и кешировать изображения в фоне. Чем раньше вы его вызовете, тем больше времени останется на завершение загрузок. К моменту показа флоу или пейвола его конфигурация и изображения уже могут быть закешированы и готовы к отображению.

Чтобы получить флоу или пейвол, используйте метод getFlow:

try {
  final flow = await Adapty().getFlow(placementId: 'YOUR_PLACEMENT_ID');
  // запрошенный флоу/пейвол
} on AdaptyError catch (adaptyError) {
  // обработка ошибки
} catch (e) {
  // обработка ошибки
}

Параметры:

Параметр	Наличие	Описание
placementId	обязательный	Идентификатор нужного плейсмента. Это значение вы указали при создании плейсмента в дашборде Adapty.
fetchPolicy	по умолчанию: .reloadRevalidatingCacheData	По умолчанию SDK пытается загрузить данные с сервера и возвращает кэшированные данные в случае ошибки. Мы рекомендуем этот вариант, так как он гарантирует, что пользователи всегда получают самые актуальные данные. Однако если у ваших пользователей нестабильное интернет-соединение, рассмотрите использование .returnCacheDataElseLoad, чтобы возвращать кэшированные данные, если они существуют. В этом случае пользователи могут не получать самые последние данные, но загрузка будет быстрее вне зависимости от качества соединения. Кэш регулярно обновляется, поэтому его безопасно использовать в течение сессии, чтобы избежать лишних сетевых запросов. Обратите внимание: кэш сохраняется при перезапуске приложения и очищается только при его переустановке или ручной очистке. Adapty SDK хранит пейволы локально в двух слоях: регулярно обновляемый кэш, описанный выше, и резервные пейволы. Для более быстрой загрузки пейволов также используется CDN и отдельный резервный сервер на случай недоступности CDN. Такая система гарантирует, что вы всегда получаете актуальную версию пейволов, обеспечивая надёжность даже при слабом интернет-соединении.
loadTimeout	по умолчанию: 5 сек	Duration, ограничивающий таймаут этого метода. При достижении таймаута будут возвращены кэшированные данные или локальный резервный вариант. Обратите внимание: в редких случаях метод может завершиться с задержкой относительно значения, указанного в loadTimeout, поскольку операция может включать несколько запросов под капотом.

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

Параметр	Описание
Flow	Объект AdaptyFlow с идентификаторами флоу (instanceIdentity, variationId), именем, плейсментом, вариантами пейволов (paywalls) и Remote Config (remoteConfigs).

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

Если плейсмент был создан в Flow Builder или Paywall Builder, Adapty самостоятельно отрисовывает UI — свойство hasViewConfiguration полученного флоу равно true. Создайте представление с помощью createFlowView, затем отобразите флоу или пейвол. Если плейсмент — это кастомный пейвол без UI Builder (hasViewConfiguration равно false), обработайте его как пейвол с Remote Config.

try {
  final view = await AdaptyUI().createFlowView(flow: flow);
} on AdaptyError catch (e) {
  // handle the error
} catch (e) {
  // handle the error
}

Параметры:

Параметр	Наличие	Описание
flow	обязательный	Объект AdaptyFlow для получения представления нужного флоу/пейвола.
customTags	необязательный	Задайте карту пользовательских тегов и их значений. Пользовательские теги служат плейсхолдерами в контенте и динамически заменяются конкретными строками для персонализации контента во флоу/пейволе. Подробнее см. в разделе Пользовательские теги в Paywall Builder.
preloadProducts	необязательный	Включите, чтобы оптимизировать время отображения продуктов на экране. При значении true AdaptyUI автоматически загрузит необходимые продукты. По умолчанию: false.
loadTimeout	необязательный	Значение типа Duration, ограничивающее время загрузки конфигурации представления. При истечении таймаута будут использованы кешированные данные или локальный резервный вариант.

После того как вы получили представление, отобразите флоу/пейвол.

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

Как правило, флоу и пейволы загружаются почти мгновенно, поэтому беспокоиться об ускорении этого процесса не нужно. Однако если у вас много аудиторий и плейсментов, а у пользователей слабое интернет-соединение, загрузка флоу или пейвола может занять больше времени, чем хотелось бы. В таких ситуациях имеет смысл показывать флоу или пейвол по умолчанию — это обеспечит плавный пользовательский опыт вместо пустого экрана. Чтобы решить эту проблему, используйте метод getFlowForDefaultAudience, который получает флоу или пейвол указанного плейсмента для аудитории All Users. Однако важно понимать, что рекомендуемый подход — получать флоу или пейвол через метод 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	по умолчанию: .reloadRevalidatingCacheData	По умолчанию SDK пытается загрузить данные с сервера и возвращает кэшированные данные в случае неудачи. Мы рекомендуем этот вариант, поскольку он гарантирует, что пользователи всегда получают самые актуальные данные. Однако если вы считаете, что у ваших пользователей нестабильный интернет, рассмотрите вариант .returnCacheDataElseLoad — он возвращает кэшированные данные, если они есть. В этом случае пользователи могут не получить самые последние данные, зато загрузка будет быстрее, независимо от качества соединения. Кэш регулярно обновляется, поэтому его безопасно использовать в течение сессии для сокращения числа сетевых запросов. Обратите внимание: кэш сохраняется при перезапуске приложения и очищается только при его переустановке или при ручной очистке.

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

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

У изображений-героев и видео-героев есть предопределённые ID: hero_image и hero_video. В бандле кастомных ассетов вы обращаетесь к этим элементам по их ID и настраиваете их поведение.

Для остальных изображений и видео необходимо задать кастомный ID в дашборде 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
}

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

Чтобы использовать кастомные таймеры в мобильном приложении, передайте карту customTimers в метод createFlowView. Каждый ключ карты — это идентификатор таймера, а значение — объект DateTime, определяющий момент окончания таймера. Пример:

try {
  final view = await AdaptyUI().createFlowView(
    flow: flow,
    customTimers: {
      'CUSTOM_TIMER_6H': DateTime.now().add(const Duration(seconds: 3600 * 6)),
      'CUSTOM_TIMER_NY': DateTime(2027, 1, 1), // New Year 2027
    },
  );
} 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-часовом периоде, который начался, когда пользователь открыл флоу.

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

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

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

1. Создайте продукты в дашборде Adapty.
2. Создайте пейвол и добавьте в него продукты в дашборде Adapty.
3. Создайте плейсменты и добавьте в них пейвол в дашборде Adapty.
4. Установите 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	опциональный по умолчанию: en	Идентификатор локализации пейвола. Ожидается языковой код, состоящий из одного или двух подтегов, разделённых символом минус (-). Первый подтег указывает язык, второй — регион. Пример: en означает английский, pt-br — бразильский португальский. Подробнее о кодах локалей и рекомендациях по их использованию см. в разделе Локализации и коды локалей.
fetchPolicy	по умолчанию: .reloadRevalidatingCacheData	По умолчанию SDK пытается загрузить данные с сервера и возвращает кешированные данные в случае сбоя. Мы рекомендуем этот вариант, так как он гарантирует, что пользователи всегда получают актуальные данные. Однако если у ваших пользователей нестабильное соединение, рассмотрите использование .returnCacheDataElseLoad — оно возвращает кешированные данные при их наличии. В этом случае пользователи могут не получить самые свежие данные, но загрузка будет заметно быстрее вне зависимости от качества соединения. Кеш регулярно обновляется, поэтому его безопасно использовать в рамках сессии для сокращения числа сетевых запросов. Обратите внимание: кеш сохраняется при перезапуске приложения и очищается только при переустановке или ручной очистке. Adapty SDK хранит пейволы локально в двух слоях: регулярно обновляемый кеш, описанный выше, и резервные пейволы. Для ускорения загрузки используется CDN, а при его недоступности — отдельный резервный сервер. Такая система обеспечивает получение актуальных пейволов и надёжность даже при нестабильном интернете.
loadTimeout	по умолчанию: 5 сек	Ограничивает таймаут для этого метода. При истечении таймаута возвращаются кешированные данные или локальный резервный вариант. Обратите внимание: в редких случаях метод может завершиться с небольшой задержкой относительно значения loadTimeout, так как операция может включать несколько запросов под капотом. Для Android: TimeInterval можно создать с помощью функций-расширений (например, 5.seconds, где .seconds импортируется из import com.adapty.utils.seconds) или через TimeInterval.seconds(5). Чтобы убрать ограничение, используйте TimeInterval.INFINITE.
Параметры ответа:
Параметр	Описание
:--------	:----------------------------------------------------------------------------------------------------------------------------------------------------------
Paywall	Объект AdaptyPaywall со списком идентификаторов продуктов, идентификатором пейвола, Remote Config и рядом других свойств.

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

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

try {
  final view = await AdaptyUI().createPaywallView(
        paywall: paywall,
      );
} on AdaptyError catch (e) {
  // handle the error
} catch (e) {
  // handle the error
}

Когда представление готово, покажите пейвол.

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

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

try {
    final paywall = await Adapty().getPaywallForDefaultAudience(placementId: 'YOUR_PLACEMENT_ID');
} on AdaptyError catch (adaptyError) {
    // handle error
} catch (e) {
    // handle unknown error
}

Параметр	Наличие	Описание
placementId	обязательный	Идентификатор плейсмента. Это значение, которое вы указали при создании плейсмента в дашборде Adapty.
locale	опциональный по умолчанию: en	Идентификатор локализации пейвола. Ожидается, что этот параметр будет языковым кодом, состоящим из одного или нескольких подтегов, разделённых символом минуса (-). Первый подтег — язык, второй — регион. Пример: en означает английский, pt-br — бразильский португальский. Подробнее о кодах локалей и рекомендациях по их использованию см. в разделе Локализации и коды локалей.
fetchPolicy	по умолчанию: .reloadRevalidatingCacheData	По умолчанию SDK пытается загрузить данные с сервера и возвращает кэшированные данные в случае ошибки. Мы рекомендуем этот вариант, так как он гарантирует, что пользователи всегда получают актуальные данные. Однако если у ваших пользователей нестабильное интернет-соединение, рассмотрите использование .returnCacheDataElseLoad — оно вернёт кэшированные данные, если они есть. В этом случае пользователи могут не получить самые последние данные, но загрузка будет быстрее независимо от качества соединения. Кэш регулярно обновляется, поэтому его безопасно использовать в течение сессии, чтобы избежать лишних сетевых запросов. Обратите внимание, что кэш сохраняется при перезапуске приложения и очищается только при переустановке приложения или вручную.

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

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

Для изображений-заголовков и видео-заголовков есть предопределённые идентификаторы: 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().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-часовом периоде, который начался, когда пользователь открыл пейвол.