Оптимизация загрузки флоу и пейволов в Flutter SDK

Надёжная загрузка флоу или пейвола во Flutter решает три задачи: быстрый рендеринг, возврат вариации, нацеленной на нужную аудиторию, и корректный резервный сценарий при медленной сети. Правила ниже охватывают тайминг, кэширование и резервные паттерны для достижения этих целей.

Tip

Подразумевается, что Adapty().activate() и Adapty().identify() уже завершились. См. Порядок вызовов в Flutter SDK.

Правила и подводные камни

Делайте такНе делайте такПочему
Загружайте нужный плейсмент или прогревайте кэш с помощью preloadFlows (SDK 4.3.0+).Не запускайте параллельные вызовы getFlow при старте приложения.Самостоятельная пакетная предзагрузка блокирует главный поток и приводит к чёрному экрану. preloadFlows создан именно для этого и передаёт пакет в нативный SDK одним вызовом.
Вызывайте getFlow после того, как атрибуция успела разрешиться — например, через 1–2 секунды после activate или после срабатывания didUpdateProfileStream.Не вызывайте getFlow в main() до runApp.Атрибуция ещё не получена. Флоу разрешится для аудитории по умолчанию и незаметно обойдёт сегменты и персонализацию ASA.
Задайте loadTimeout и настройте резервный пейвол для каждого плейсмента.Не ждите ответа getFlow бесконечно.Без таймаута пользователи с плохим соединением видят пустой экран до восстановления сети — или просто закрывают приложение.

Описание параметров fetchPolicy и loadTimeout см. в разделе Получение пейволов и продуктов, а информацию о выборе подходящего плейсмента — в разделе Плейсменты.

Предзагрузка плейсментов

Info

preloadFlows и preloadFlowsForDefaultAudience доступны начиная с версии SDK 4.3.0.

preloadFlows заранее кэширует JSON флоу. Затем вы используете его как обычно: getFlow — для получения флоу, createFlowView — для создания его представления.

fetchPolicy определяет, из какого источника getFlow будет читать данные в первую очередь, а не то, сможет ли он вообще обратиться к кэшу:

  • AdaptyFlowFetchPolicy.returnCacheDataElseLoad сначала читает предзагруженную копию и обращается к сети только если кэш пуст. AdaptyFlowFetchPolicy.returnCacheDataIfNotExpiredElseLoad(maxAge) делает то же самое, пока копии не больше maxAge.
  • По умолчанию используется AdaptyFlowFetchPolicy.reloadRevalidatingCacheData — он сначала идёт в сеть и возвращается к предзагруженной копии, если запрос не удался или завершился по таймауту.

Предзагрузка окупается в любом случае, но по-разному: политика «кэш прежде всего» убирает запрос полностью, а политика по умолчанию сохраняет его, получая тёплую копию для отката. На тестовом устройстве getFlow при любой политике пропускает кэш и использует предзагруженную копию только при сбое сетевого запроса.

Используйте предзагрузку, когда знаете, какие плейсменты понадобятся в сессии, но не хотите показывать их сразу — например, сразу после завершения activate и identify, для флоу за кнопкой, которую пользователь ещё не нажал.

try {
  await Adapty().preloadFlows(
    placementIds: ['onboarding', 'main_paywall'],
    loadTimeout: const Duration(seconds: 5),
  );
} on AdaptyError catch (adaptyError) {
  // at least one placement failed to preload
}

// Later, when the user reaches the paywall:
final flow = await Adapty().getFlow(
  placementId: 'main_paywall',
  fetchPolicy: AdaptyFlowFetchPolicy.returnCacheDataElseLoad,
);

Параметры:

  • placementIds (обязательный): плейсменты для предзагрузки.
  • loadTimeout (необязательный): как долго ждать загрузки флоу, привязанных к аудитории. По умолчанию 5 секунд; значения ниже 1 секунды автоматически повышаются до 1 секунды. По истечении таймаута SDK может загрузить флоу для аудитории по умолчанию.

Важные особенности поведения:

  • Вызов завершается ошибкой только после того, как были обработаны все плейсменты, с одной AdaptyError, охватывающей все неудачные плейсменты. Ошибка для одного плейсмента не останавливает остальные, а загруженные плейсменты остаются в кэше.
  • Предзагрузка всегда обращается к сети: у неё нет собственного fetchPolicy.
  • Предзагрузка только прогревает кэш. Она не возвращает контент — для отображения вы всё равно вызываете getFlow.

Что охватывает предзагрузка

Флоу отображается на экране послойно. Предзагрузка охватывает первый слой — ровно так же, как это делает getFlow:

СлойКто загружаетПрогревается предзагрузкой
Flow JSON — выбранный вариант, идентификаторы продуктов и Remote ConfiggetFlowДа
Макет UI — структура экрана, стили и текстcreateFlowViewНет
Изображения, включая статичный кадр-заглушку для видеоэлементаcreateFlowView, в фонеНет
ПродуктыcreateFlowView или getPaywallProductsНет
ВидеофайлыСистемный плеер при отрисовке экранаSDK не кэширует

Таким образом, первый вызов createFlowView для конкретного макета всё равно требует одного обращения к серверу даже после предзагрузки. Однако затем нативный SDK сохраняет этот макет в дисковый кэш, который переживает перезапуски приложения, — поэтому затраты приходятся только на первый запрос, а не на каждый последующий.

Пропуск сегментации аудитории

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

await Adapty().preloadFlowsForDefaultAudience(placementIds: ['main_paywall']);

Последующий вызов getFlowForDefaultAudience читает копию так же, как getFlow читает копию preloadFlows.

Показ медиа первого экрана из бандла приложения

Флоу загружает изображения и видео из Adapty. Чтобы медиа первого экрана отображалось мгновенно, раздавайте его из бандла приложения. Это удобно, если вы уже поставляете такие медиафайлы — например, визуальные элементы существующего нативного онбординга.

  1. В Flow & Paywall Builder задайте пользовательский медиа-ID для изображения или видео. Загруженный там файл остаётся в качестве резервного.
  2. Добавьте файл в ресурсы Flutter и укажите его в разделе assets файла pubspec.yaml.
  3. При создании представления флоу передайте bundled-файл для этого ID в customAssets:
// "welcome_video" is the custom media ID set in the Flow & Paywall Builder
final bundledAssets = {
  'welcome_video': AdaptyCustomAsset.localVideoAsset(
    assetId: 'assets/videos/welcome.mp4',
  ),
};

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

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

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

Полный справочник по customAssets см. в разделе Настройка ассетов.

Настройка для нестабильного подключения

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

  • Устанавливайте fetchPolicy: AdaptyFlowFetchPolicy.returnCacheDataElseLoad для каждого запроса, кроме самого первого.
  • Настройте резервный пейвол для каждого плейсмента на дашборде Adapty.
  • Задайте loadTimeout в 3–5 секунд и принимайте резервный пейвол при срабатывании таймаута.
  • Не блокируйте отображение флоу на getProfile(). Вызывайте getFlow независимо, чтобы медленный профиль не задерживал отрисовку интерфейса.