Оптимизация загрузки флоу и пейволов в Flutter SDK
Надёжная загрузка флоу или пейвола во Flutter решает три задачи: быстрый рендеринг, возврат вариации, нацеленной на нужную аудиторию, и корректный резервный сценарий при медленной сети. Правила ниже охватывают тайминг, кэширование и резервные паттерны для достижения этих целей.
Подразумевается, что 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 см. в разделе Получение пейволов и продуктов, а информацию о выборе подходящего плейсмента — в разделе Плейсменты.
Предзагрузка плейсментов
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 Config | getFlow | Да |
| Макет UI — структура экрана, стили и текст | createFlowView | Нет |
| Изображения, включая статичный кадр-заглушку для видеоэлемента | createFlowView, в фоне | Нет |
| Продукты | createFlowView или getPaywallProducts | Нет |
| Видеофайлы | Системный плеер при отрисовке экрана | SDK не кэширует |
Таким образом, первый вызов createFlowView для конкретного макета всё равно требует одного обращения к серверу даже после предзагрузки. Однако затем нативный SDK сохраняет этот макет в дисковый кэш, который переживает перезапуски приложения, — поэтому затраты приходятся только на первый запрос, а не на каждый последующий.
Пропуск сегментации аудитории
Чтобы прогреть кэш без ожидания сегментации аудитории, используйте вариант для аудитории по умолчанию. Он не требует таймаута:
await Adapty().preloadFlowsForDefaultAudience(placementIds: ['main_paywall']);
Последующий вызов getFlowForDefaultAudience читает копию так же, как getFlow читает копию preloadFlows.
Показ медиа первого экрана из бандла приложения
Флоу загружает изображения и видео из Adapty. Чтобы медиа первого экрана отображалось мгновенно, раздавайте его из бандла приложения. Это удобно, если вы уже поставляете такие медиафайлы — например, визуальные элементы существующего нативного онбординга.
- В Flow & Paywall Builder задайте пользовательский медиа-ID для изображения или видео. Загруженный там файл остаётся в качестве резервного.
- Добавьте файл в ресурсы Flutter и укажите его в разделе
assetsфайлаpubspec.yaml. - При создании представления флоу передайте 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независимо, чтобы медленный профиль не задерживал отрисовку интерфейса.