Optimiser la récupération des flows et paywalls avec le SDK Flutter
Une récupération fiable d’un flow ou d’un paywall avec Flutter repose sur trois points : un rendu rapide, le retour de la variante ciblée par audience, et un repli gracieux lorsque le réseau est lent. Les règles ci-dessous couvrent le timing, la mise en cache et les patterns de secours pour y parvenir.
Ces règles supposent que Adapty().activate() et Adapty().identify() ont déjà été résolus. Consultez Ordre des appels dans le SDK Flutter.
Règles et pièges
| Faites ceci | Ne faites pas cela | Pourquoi |
|---|---|---|
Récupérez le placement que vous êtes sur le point d’afficher, ou préchauffez le cache avec preloadFlows (SDK 4.3.0+). | Lancez vos propres appels getFlow concurrents au démarrage. | Un burst de prefetch manuel bloque le thread principal et produit un écran noir. preloadFlows est conçu pour ça et envoie le lot au SDK natif en un seul appel. |
Appelez getFlow après que l’attribution a eu le temps de se résoudre — par exemple, 1 à 2 secondes après activate ou après le déclenchement de didUpdateProfileStream. | Appelez getFlow dans main() avant runApp. | L’attribution n’est pas encore arrivée. Le flow se résout sur l’audience par défaut et contourne silencieusement les segments et la personnalisation ASA. |
Définissez un loadTimeout et configurez un paywall de secours pour chaque placement. | Attendez getFlow indéfiniment. | Sans timeout, les utilisateurs avec une mauvaise connexion voient un écran blanc jusqu’à ce que le réseau réponde — ou ferment l’application. |
Consultez Récupérer les paywalls personnalisés et les produits pour la référence des paramètres fetchPolicy et loadTimeout, et Placements pour choisir le bon placement.
Précharger les placements
preloadFlows et preloadFlowsForDefaultAudience sont disponibles à partir de la version 4.3.0 du SDK.
preloadFlows met en cache le JSON du flow à l’avance. Vous l’utilisez ensuite comme d’habitude : getFlow pour le flow, createFlowView pour sa vue.
fetchPolicy détermine quelle couche un appel ultérieur à getFlow consulte en premier, et non si le cache est accessible :
AdaptyFlowFetchPolicy.returnCacheDataElseLoadlit d’abord la copie préchargée et ne fait appel au réseau que si rien n’est en cache.AdaptyFlowFetchPolicy.returnCacheDataIfNotExpiredElseLoad(maxAge)fait de même tant que la copie est plus récente quemaxAge.- La valeur par défaut,
AdaptyFlowFetchPolicy.reloadRevalidatingCacheData, interroge d’abord le réseau et se rabat sur la copie préchargée en cas d’échec ou de dépassement de délai.
Un préchargement est toujours utile, mais différemment selon la politique : une politique cache-first supprime la requête, tandis que la politique par défaut la conserve et dispose d’une copie en cache en cas de besoin. Sur un appareil de test, getFlow ignore le cache quelle que soit la politique et n’utilise la copie préchargée que si la requête réseau échoue.
Utilisez-le quand vous savez quels placements la session va nécessiter, mais que vous ne souhaitez pas encore les afficher — par exemple, juste après la fin de activate et identify, pour le flow derrière un bouton que l’utilisateur n’a pas encore appuyé.
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,
);
Paramètres :
placementIds(requis) : les placements à précharger.loadTimeout(optionnel) : durée d’attente du préchargement pour les flows ciblés par audience. Par défaut 5 secondes ; les valeurs inférieures à 1 seconde sont ramenées à 1 seconde. À l’expiration du délai, le SDK peut charger les flows de l’audience par défaut à la place.
Points importants à retenir :
- L’appel échoue uniquement après que tous les placements ont été tentés, avec une seule
AdaptyErrorcouvrant tous les placements en échec. L’échec d’un placement n’interrompt pas les autres, et les placements chargés restent dans le cache. - Le préchargement passe toujours par le réseau : il ne dispose pas de
fetchPolicypropre. - Le préchargement sert uniquement à alimenter le cache. Il ne retourne pas de contenu — vous appelez toujours
getFlowpour l’afficher.
Ce que couvre un préchargement
Un flow s’affiche à l’écran en plusieurs couches. Un préchargement couvre la première, exactement comme getFlow :
| Couche | Récupérée par | Pré-chargée |
|---|---|---|
| JSON du flow — la variante choisie, ses identifiants de produits et le Remote Config | getFlow | Oui |
| Mise en page UI — structure, style et texte des écrans | createFlowView | Non |
| Images, y compris la miniature remplaçant un élément vidéo | createFlowView, en arrière-plan | Non |
| Produits | createFlowView ou getPaywallProducts | Non |
| Fichiers vidéo | Le lecteur système, au moment du rendu de l’écran | Non mis en cache par le SDK |
Ainsi, le premier createFlowView pour un layout donné implique toujours un aller-retour réseau après un préchargement. Le SDK natif conserve ensuite ce layout dans son cache disque, qui survit aux redémarrages de l’application, de sorte que le coût se produit uniquement lors de la première requête, et non à chaque fois.
Ignorer la segmentation d’audience
Pour réchauffer le cache sans attendre la segmentation d’audience, utilisez la variante default-audience. Elle ne prend aucun timeout :
await Adapty().preloadFlowsForDefaultAudience(placementIds: ['main_paywall']);
Un getFlowForDefaultAudience appelé ensuite lit la copie de la même façon que getFlow lit une copie preloadFlows.
Afficher les médias du premier écran depuis le bundle de l’application
Un flow télécharge ses images et vidéos depuis Adapty. Pour afficher instantanément les médias du premier écran, servez-les depuis le bundle de l’application. C’est un bon moyen de réutiliser des médias que vous embarquez déjà, comme les visuels d’un onboarding natif existant.
- Dans le Flow & Paywall Builder, définissez un identifiant multimédia personnalisé sur l’image ou la vidéo. Le fichier que vous y téléchargez reste en tant que fallback.
- Ajoutez le fichier à vos assets Flutter et listez-le sous
assetsdanspubspec.yaml. - Lorsque vous créez la vue du flow, transmettez le fichier groupé pour cet identifiant dans
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
}
Les fichiers intégrés augmentent la taille de téléchargement de votre application, ne bundlez donc que les médias que les utilisateurs voient en premier.
Les médias non inclus dans le bundle s’affichent quand même immédiatement : le layout du flow contient une petite copie basse résolution de chaque image, y compris une image fixe pour les vidéos, et l’affiche jusqu’au chargement complet du fichier.
Pour la référence complète de customAssets, consultez Personnaliser les assets.
Optimiser pour une connectivité médiocre
Pour les marchés où la connectivité est durablement mauvaise (zones rurales, transports, régions touchées par des problèmes de routage) :
- Définissez
fetchPolicy: AdaptyFlowFetchPolicy.returnCacheDataElseLoadsur chaque appel sauf le tout premier. - Configurez un paywall de secours pour chaque placement dans l’Adapty Dashboard.
- Réglez
loadTimeoutà 3–5 secondes et acceptez le paywall de secours quand le délai expire. - N’attendez pas
getProfile()pour afficher le flow. AppelezgetFlowindépendamment afin qu’un profil lent ne bloque pas l’interface.