Optimizar la obtención de flows y paywalls en el SDK de Flutter
Una obtención fiable de un flow o paywall en Flutter hace tres cosas: se renderiza rápido, devuelve la variación dirigida a la audiencia correspondiente y tiene un respaldo elegante cuando la red es lenta. Las reglas que se describen a continuación cubren los patrones de temporización, caché y respaldo necesarios para lograrlo.
Las reglas asumen que Adapty().activate() y Adapty().identify() ya se han resuelto. Consulta Orden de llamadas en el SDK de Flutter.
Reglas y errores comunes
| Haz esto | No hagas esto | Por qué |
|---|---|---|
Obtén el placement que vas a mostrar, o precalienta la caché con preloadFlows (SDK 4.3.0+). | Lanza tus propias llamadas concurrentes a getFlow al arrancar. | Un burst de prefetch manual bloquea el hilo principal y produce una pantalla en negro. preloadFlows está diseñado para esto y envía el lote al SDK nativo en una sola llamada. |
Llama a getFlow después de que la atribución haya tenido tiempo de resolverse — por ejemplo, 1–2 segundos después de activate o tras dispararse didUpdateProfileStream. | Llames a getFlow en main() antes de runApp. | La atribución aún no ha llegado. El flow se resuelve contra la audiencia por defecto y omite silenciosamente los segmentos y la personalización de ASA. |
Define un loadTimeout y configura un paywall de respaldo para cada placement. | Esperes a getFlow indefinidamente. | Sin timeout, los usuarios con mala conexión ven una pantalla en blanco hasta que la red responde — o cierran la app. |
Consulta Obtener paywalls y productos personalizados para la referencia de los parámetros fetchPolicy y loadTimeout, y Placements para elegir el placement adecuado.
Precargar placements
preloadFlows y preloadFlowsForDefaultAudience están disponibles a partir de la versión 4.3.0 del SDK.
preloadFlows guarda en caché el JSON del flow con antelación. Luego lo utilizas de la forma habitual: getFlow para obtener el flow y createFlowView para su vista.
fetchPolicy decide qué capa lee primero un getFlow posterior, no si puede acceder a la caché:
AdaptyFlowFetchPolicy.returnCacheDataElseLoadlee primero la copia precargada y solo accede a la red cuando no hay nada en caché.AdaptyFlowFetchPolicy.returnCacheDataIfNotExpiredElseLoad(maxAge)hace lo mismo mientras la copia sea más reciente quemaxAge.- El valor predeterminado,
AdaptyFlowFetchPolicy.reloadRevalidatingCacheData, accede primero a la red y recurre a la copia precargada cuando la solicitud falla o se agota el tiempo de espera.
La precarga es beneficiosa en cualquier caso, pero de distinta forma: una política cache-first elimina la solicitud, mientras que la predeterminada la mantiene y obtiene una copia en caché como respaldo. En un dispositivo de prueba, getFlow omite la caché con cualquier política y solo usa la copia precargada si falla la solicitud de red.
Úsalo cuando sepas qué placements necesitará la sesión pero no quieras mostrarlos todavía — por ejemplo, justo después de que activate e identify completen, para el flow detrás de un botón que el usuario aún no ha pulsado.
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,
);
Parámetros:
placementIds(obligatorio): los placements a precargar.loadTimeout(opcional): cuánto tiempo espera la precarga para los flows con audiencia específica. Por defecto son 5 segundos; los valores por debajo de 1 segundo se elevan a 1 segundo. Cuando se alcanza el tiempo límite, el SDK puede cargar los flows de la audiencia predeterminada en su lugar.
Comportamiento que conviene conocer:
- La llamada falla solo cuando se han intentado todos los placements, con un único
AdaptyErrorque cubre todos los placements fallidos. El fallo en un placement no detiene los demás, y los placements que se cargaron correctamente permanecen en caché. - La precarga siempre va a la red: no tiene
fetchPolicypropia. - La precarga solo calienta la caché. No devuelve contenido — para mostrarlo, debes llamar a
getFlow.
Qué cubre una precarga
Un flow llega a la pantalla por capas. Una precarga cubre la primera, exactamente igual que getFlow:
| Capa | Obtenida por | Precargada con un preload |
|---|---|---|
| Flow JSON — la variante elegida, sus IDs de producto y el Remote Config | getFlow | Sí |
| Diseño de UI — la estructura, el estilo y el texto de la pantalla | createFlowView | No |
| Imágenes, incluido el fotograma fijo que sustituye a un elemento de vídeo | createFlowView, en segundo plano | No |
| Productos | createFlowView o getPaywallProducts | No |
| Archivos de vídeo | El reproductor del sistema, al renderizar la pantalla | El SDK no los almacena en caché |
Así que el primer createFlowView para un layout concreto sigue requiriendo un viaje de ida y vuelta incluso tras una precarga. El SDK nativo guarda ese layout en su caché de disco, que sobrevive a los reinicios de la app, por lo que el coste recae en la primera solicitud y no en cada una de ellas.
Omitir la segmentación de audiencia
Para calentar la caché sin esperar la segmentación de audiencia, usa la variante de audiencia predeterminada. No tiene ningún tiempo de espera:
await Adapty().preloadFlowsForDefaultAudience(placementIds: ['main_paywall']);
Un getFlowForDefaultAudience posterior lee la copia de la misma forma en que getFlow lee una copia de preloadFlows.
Mostrar el contenido multimedia de la primera pantalla desde el bundle de la app
Un flow descarga sus imágenes y vídeos desde Adapty. Para mostrar el contenido multimedia de la primera pantalla al instante, sírvelo desde el bundle de la app. Es una buena forma de reutilizar recursos que ya incluyes en la app, como los visuales de un onboarding nativo existente.
- En el Flow & Paywall Builder, asigna un ID de medio personalizado a la imagen o el vídeo. El archivo que subas ahí se usará como respaldo.
- Añade el archivo a los assets de Flutter y regístralo en
assetsdentro depubspec.yaml. - Al crear la vista del flow, pasa el archivo incluido para ese ID en
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
}
Los archivos incluidos aumentan el tamaño de descarga de tu app, así que incluye solo los recursos que el usuario ve primero.
Los archivos multimedia que no incluyas en el bundle aparecerán igualmente de inmediato: el layout del flow incluye una copia en baja resolución de cada imagen, incluyendo el fotograma estático de los vídeos, y la muestra hasta que se cargue el archivo completo.
Para la referencia completa de customAssets, consulta Personalizar assets.
Ajusta para conectividad deficiente
Para mercados con conectividad consistentemente deficiente (zonas rurales, transporte, regiones afectadas por enrutamiento):
- Establece
fetchPolicy: AdaptyFlowFetchPolicy.returnCacheDataElseLoaden cada llamada excepto la primera. - Configura un paywall de respaldo para cada placement en el Adapty Dashboard.
- Establece
loadTimeoutentre 3 y 5 segundos y acepta el respaldo cuando se agote el tiempo. - No bloquees la visualización del flow esperando
getProfile(). Llama agetFlowde forma independiente para que un perfil lento no bloquee la interfaz.