Récupérer les flows et paywalls - Flutter
getFlow Après avoir conçu votre flow, vous pouvez l’afficher dans votre application mobile. La première étape consiste à récupérer le flow ou le paywall associé au placement et sa configuration d’affichage, comme décrit ci-dessous.
Notez que cette rubrique concerne les flows et les paywalls conçus avec les builders d’Adapty. Si vous implémentez des paywalls personnalisés, consultez la rubrique Récupérer les paywalls et les produits pour les paywalls personnalisés dans votre application mobile.
Vous souhaitez voir un exemple concret d’intégration du SDK Adapty dans une application mobile ? Découvrez nos applications exemples, qui illustrent la configuration complète, notamment l’affichage des paywalls, la réalisation d’achats et d’autres fonctionnalités de base.
Avant de commencer
Vous avez besoin de :
- Des produits dans l’Adapty Dashboard : Créez vos produits.
- Un flow avec des produits : Créez-le dans le Flow & Paywall Builder et associez-y des produits.
- Un placement : Créez un placement et assignez-y votre flow.
- Le SDK installé : Consultez le guide d’installation du SDK Flutter.
Récupérer un flow/paywall
Si vous avez conçu un flow ou un paywall dans le builder, vous n’avez pas à vous soucier de son rendu dans le code de votre application mobile pour l’afficher à l’utilisateur. Un tel flow ou paywall contient à la fois ce qui doit être affiché et la manière dont il doit l’être. Vous devez néanmoins récupérer son ID via le placement, sa configuration de vue, puis le présenter dans votre application mobile.
Récupérez le flow ou le paywall et créez sa vue le plus tôt possible — idéalement bien avant de l’afficher. La méthode createFlowView charge la configuration de la vue et lance le téléchargement et la mise en cache des images en arrière-plan. Plus vous l’appelez tôt, plus ces téléchargements ont de temps pour se terminer. Au moment d’afficher le flow ou le paywall, sa configuration et ses images peuvent déjà être en cache et prêtes à l’affichage.
Pour préchauffer plusieurs placements à la fois, appelez preloadFlows (Flutter SDK 4.3.0+). Cette méthode ne met en cache que le JSON du placement, donc createFlowView charge quand même la mise en page et les images.
Pour récupérer un flow ou un paywall, utilisez la méthode getFlow :
try {
final flow = await Adapty().getFlow(placementId: 'YOUR_PLACEMENT_ID');
// the requested flow/paywall
} on AdaptyError catch (adaptyError) {
// handle the error
} catch (e) {
// handle the error
}Paramètres :
| Paramètre | Présence | Description |
|---|---|---|
| placementId | requis | L’identifiant du Placement souhaité. Il s’agit de la valeur que vous avez spécifiée lors de la création d’un placement dans l’Adapty Dashboard. |
| fetchPolicy | par défaut : AdaptyFlowFetchPolicy.reloadRevalidatingCacheData |
Cependant, si vous pensez que vos utilisateurs ont une connexion internet instable, envisagez Une troisième politique, Notez que le cache reste intact lors du redémarrage de l’application et n’est effacé que lors de la désinstallation de l’application ou par un nettoyage manuel. Le SDK Adapty stocke les paywalls localement en deux couches : le cache mis à jour régulièrement décrit ci-dessus et les paywalls de secours. Nous utilisons également un CDN pour récupérer les paywalls plus rapidement et un serveur de secours indépendant en cas d’inaccessibilité du CDN. Ce système est conçu pour vous garantir toujours la dernière version de vos paywalls tout en assurant la fiabilité même lorsque la connexion internet est limitée. |
| loadTimeout | par défaut : 5 sec | Une Notez que dans de rares cas, cette méthode peut expirer légèrement plus tard que ce qui est spécifié dans |
Paramètres de réponse
| Paramètre | Description |
|---|---|
| Flow | Un objet AdaptyFlow contenant les identifiants du flow (instanceIdentity, variationId), son nom, son placement, ses variations de paywall (paywalls), ainsi que les éventuelles configurations distantes (remoteConfigs). |
Récupérer la configuration de la vue
Assurez-vous de publier le flow. Un flow avec des modifications non publiées a le statut Dirty et son placement continue à servir la dernière version publiée.
Si le placement a été conçu dans le Flow & Paywall Builder ou l’ancien Paywall Builder, Adapty génère l’interface à votre place — la propriété hasViewConfiguration du flow récupéré est true. Créez la vue avec createFlowView, puis affichez le flow ou le paywall. Si le placement est un paywall personnalisé sans interface Builder (hasViewConfiguration est false), affichez-le vous-même à la place.
Par défaut, fermer le résultat de la méthode createFlowView le libère, vous ne pouvez donc pas le présenter à nouveau. Si vous avez besoin de présenter le flow ou le paywall à nouveau, appelez la méthode createFlowView une nouvelle fois, ou fermez-le sans le libérer avec le SDK 4.1 et versions ultérieures.
try {
final view = await AdaptyUI().createFlowView(flow: flow);
} on AdaptyError catch (e) {
// handle the error
} catch (e) {
// handle the error
}Paramètres :
| Paramètre | Présence | Description |
|---|---|---|
| flow | requis | Un objet AdaptyFlow pour obtenir une vue pour le flow/paywall souhaité. |
| locale | optionnel | L’identifiant de la localisation du flow avec laquelle afficher la vue — par exemple, en ou pt-br. Sans cette valeur, la vue s’affiche en en, ou dans la localisation par défaut du flow s’il n’a pas de version en. Voir Localisations et codes de langue. |
| customLayoutId | optionnel défaut : SDK 4.1+ | L’ID personnalisé d’un layout dans la configuration des layouts du flow. Passez-le pour afficher ce layout spécifique au lieu de celui sélectionné automatiquement par le SDK selon le type d’appareil et la taille d’écran. Si aucun layout ne correspond à cet ID, l’appel échoue avec une AdaptyError. Le Flow & Paywall Builder n’attribue pas encore d’IDs de layout personnalisés, ne définissez donc pas cette valeur. |
| customTags | optionnel | Les valeurs de votre application pour les tags personnalisés du flow, dans une map indexée par le nom complet de chaque tag. Pour en savoir plus, lisez Passer des données aux flows. |
| customTimers | optionnel | Les dates de fin des minuteurs Developer defined du flow, dans une map d’IDs de minuteur vers des valeurs DateTime. Pour en savoir plus, lisez Configurer les minuteurs définis par le développeur. |
| preloadProducts | optionnel | Activez cette option pour optimiser le moment d’affichage des produits à l’écran. Lorsque true, AdaptyUI récupère automatiquement les produits nécessaires. Par défaut : false. |
| loadTimeout | optionnel | Une Duration qui limite le temps de chargement de la configuration de la vue. Si le délai est atteint, les données en cache ou le fallback local sont utilisés. |
Si vous utilisez plusieurs langues, découvrez comment ajouter une localisation de flow et comment utiliser correctement les codes de langue ici.
Une fois que vous avez la vue, présentez le flow/paywall.
Récupérer un flow ou un paywall pour l’audience par défaut afin d’accélérer le chargement
En général, les flows et les paywalls sont récupérés presque instantanément, et vous n’avez donc pas à vous soucier d’accélérer ce processus. Cependant, si vous avez de nombreuses audiences et placements, et que vos utilisateurs ont une connexion internet faible, la récupération d’un flow ou d’un paywall peut prendre plus de temps que souhaité. Dans ce cas, vous pourriez vouloir afficher un flow ou un paywall par défaut pour garantir une expérience utilisateur fluide plutôt que de ne rien afficher du tout.
Pour y remédier, vous pouvez utiliser la méthode getFlowForDefaultAudience, qui récupère le flow ou le paywall du placement spécifié pour l’audience All Users. Cependant, il est important de comprendre que l’approche recommandée est de récupérer le flow ou le paywall via la méthode getFlow, comme décrit dans la section Récupérer le flow/paywall ci-dessus.
Pourquoi nous recommandons d’utiliser getFlow
La méthode getFlowForDefaultAudience présente quelques inconvénients importants :
- Problèmes potentiels de rétrocompatibilité : si vous devez afficher des paywalls différents selon les versions de l’application (actuelle et future), vous pourrez rencontrer des difficultés. Vous devrez soit concevoir des paywalls compatibles avec la version actuelle (héritée), soit accepter que les utilisateurs de cette version puissent rencontrer des problèmes avec des paywalls non affichés.
- Perte de ciblage : tous les utilisateurs verront le même paywall conçu pour l’audience All Users, ce qui signifie que vous perdez le ciblage personnalisé (notamment selon les pays, l’attribution marketing ou vos propres attributs personnalisés).
Si vous acceptez ces inconvénients pour bénéficier d’un chargement plus rapide des flows ou des paywalls, utilisez la méthode getFlowForDefaultAudience comme suit. Sinon, restez sur getFlow décrit ci-dessus.
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
}
| Paramètre | Présence | Description |
|---|---|---|
| placementId | requis | L’identifiant du Placement. C’est la valeur que vous avez spécifiée lors de la création d’un placement dans votre Adapty Dashboard. |
| fetchPolicy | défaut : AdaptyFlowFetchPolicy.reloadRevalidatingCacheData |
Cependant, si vous pensez que vos utilisateurs sont soumis à une connexion internet instable, envisagez Une troisième politique, Notez que le cache reste intact lors du redémarrage de l’application et n’est effacé que lors de la réinstallation de l’application ou via un nettoyage manuel. |
Personnaliser les ressources
Pour personnaliser les images et vidéos de votre flow/paywall, implémentez des ressources personnalisées.
Les images et vidéos hero ont des identifiants prédéfinis : hero_image et hero_video. Dans un bundle de ressources personnalisées, vous ciblez ces éléments par leurs identifiants et personnalisez leur comportement.
Pour les autres images et vidéos, vous devez définir un identifiant personnalisé dans l’Adapty Dashboard.
Par exemple, vous pouvez :
- Afficher une image ou une vidéo différente à certains utilisateurs.
- Afficher une image de prévisualisation locale pendant le chargement d’une image principale distante.
- Afficher une image de prévisualisation avant de lancer une vidéo.
- Afficher des médias intégrés à l’application, afin que le premier écran s’affiche sans téléchargement. Voir Afficher les médias du premier écran depuis le bundle de l’application.
Voici un exemple de la façon dont vous pouvez fournir des assets personnalisés via un simple dictionnaire :
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
}Si une ressource est introuvable, le flow/paywall reviendra à son apparence par défaut.
Configurer les minuteries définies par le développeur
Utilisez cette section pour une minuterie avec le comportement Developer defined dans le Flow & Paywall Builder. Dans le builder, chaque minuterie de ce type possède un Timer ID (voir Laisser votre application définir la date de fin), et votre application définit la date de fin. Utilisez le même Timer ID dans votre code que dans le builder, caractère par caractère, en respectant la casse et les espaces. Si les ID diffèrent, la minuterie ne reçoit aucune date de fin de votre application.
Pour définir les dates de fin, passez une map customTimers à la méthode createFlowView. Chaque clé de la map est un Timer ID, et sa valeur est un objet DateTime qui définit quand le timer se termine. Voici un exemple :
try {
final view = await AdaptyUI().createFlowView(
flow: flow,
customTimers: {
'CUSTOM_TIMER_6H': DateTime.now().add(const Duration(hours: 6)),
'CUSTOM_TIMER_NY': DateTime(DateTime.now().year + 1), // next New Year's Day
},
);
} on AdaptyError catch (e) {
// handle the error
} catch (e) {
// handle the error
}Pour un flow intégré avec AdaptyUIFlowPlatformView, passez la même map à son paramètre customTimers.
Dans cet exemple, CUSTOM_TIMER_NY et CUSTOM_TIMER_6H sont les ID de timer de deux minuteries définies par le développeur dans le builder :
CUSTOM_TIMER_NY: le temps restant jusqu’au prochain Nouvel An.CUSTOM_TIMER_6H: le temps restant dans une période de 6 heures qui a démarré au moment où votre application a créé la vue.
Le SDK lit customTimers une seule fois, au moment où il crée la vue. Ainsi, une date calculée comme CUSTOM_TIMER_6H est comptabilisée à partir de ce moment, même si l’utilisateur rouvre l’écran. Si la date est dans le passé, le minuteur affiche immédiatement zéro et son déclencheur On timer end s’exécute. Si customTimers ne contient pas de clé pour un Timer ID, le minuteur décompte une heure à partir de l’ouverture de l’écran.
Après avoir conçu la partie visuelle de votre paywall avec l’ancien Paywall Builder dans l’Adapty Dashboard, vous pouvez l’afficher dans votre application mobile. La première étape consiste à récupérer le paywall associé au placement ainsi que sa configuration d’affichage, comme décrit ci-dessous.
Les paywalls créés avec le Paywall Builder du SDK 3.x nécessitent la version 3.3.0 ou supérieure du SDK Flutter.
Veuillez noter que cette rubrique concerne les paywalls personnalisés avec le Paywall Builder. Si vous implémentez des paywalls personnalisés, consultez la rubrique Récupérer les paywalls et produits pour les paywalls personnalisés dans votre application mobile.
Vous souhaitez voir un exemple concret d’intégration du SDK Adapty dans une application mobile ? Découvrez nos applications exemples, qui illustrent la configuration complète, notamment l’affichage des paywalls, la réalisation d’achats et d’autres fonctionnalités de base.
Avant de commencer à afficher des paywalls dans votre application mobile (cliquez pour développer)
- Créez vos produits dans l’Adapty Dashboard.
- Créez un paywall et intégrez-y les produits dans l’Adapty Dashboard.
- Créez des placements et intégrez-y votre paywall dans l’Adapty Dashboard.
- Installez le SDK Adapty dans votre application mobile.
Récupérer un paywall conçu avec le Paywall Builder
Si vous avez conçu un paywall avec le Paywall Builder, vous n’avez pas à vous soucier de son rendu dans le code de votre application mobile pour l’afficher à l’utilisateur. Un tel paywall contient à la fois ce qui doit être affiché et la manière dont cela doit l’être. Vous devez néanmoins récupérer son identifiant via le placement, sa configuration d’affichage, puis le présenter dans votre application mobile.
Pour garantir des performances optimales, il est essentiel de récupérer le paywall et sa configuration d’affichage le plus tôt possible, afin de laisser suffisamment de temps aux images de se télécharger avant de les présenter à l’utilisateur.
Pour récupérer un paywall, utilisez la méthode 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) {
}Paramètres :
| Paramètre | Présence | Description |
|---|---|---|
| placementId | requis | L’identifiant du Placement souhaité. Il s’agit de la valeur que vous avez spécifiée lors de la création d’un placement dans l’Adapty Dashboard. |
| locale | optionnel par défaut : | L’identifiant de la localisation du paywall. Ce paramètre doit être un code de langue composé d’un ou deux sous-tags séparés par le caractère moins (-). Le premier sous-tag correspond à la langue, le second à la région. Exemple : Consultez Localisations et codes de langue pour plus d’informations sur les codes de langue et notre façon de les utiliser. |
| fetchPolicy | par défaut : AdaptyPaywallFetchPolicy.reloadRevalidatingCacheData |
Toutefois, si vous pensez que vos utilisateurs ont une connexion internet instable, envisagez Une troisième politique, Notez que le cache reste intact après un redémarrage de l’application et n’est effacé que lors d’une réinstallation ou d’un nettoyage manuel. Le SDK Adapty stocke les paywalls localement en deux couches : le cache régulièrement mis à jour décrit ci-dessus et les paywalls de secours. Nous utilisons également un CDN pour récupérer les paywalls plus rapidement ainsi qu’un serveur de secours indépendant en cas d’inaccessibilité du CDN. Ce système est conçu pour vous garantir toujours la dernière version de vos paywalls tout en assurant la fiabilité même lorsque la connexion internet est limitée. |
| loadTimeout | par défaut : 5 sec | Une Notez que dans de rares cas, cette méthode peut expirer légèrement après le délai spécifié dans |
Paramètres de réponse
| Paramètre | Description |
|---|---|
| Paywall | Un objet AdaptyPaywall contenant une liste d’identifiants de produits, l’identifiant du paywall, le Remote Config et plusieurs autres propriétés. |
Récupérer la configuration d’affichage d’un paywall conçu avec le Paywall Builder
Assurez-vous d’activer le bouton Show on device dans le Paywall Builder. Si cette option n’est pas activée, la configuration d’affichage ne sera pas disponible.
Après avoir récupéré le paywall, vérifiez s’il contient une ViewConfiguration, ce qui indique qu’il a été créé avec le Paywall Builder. Cela vous guidera sur la façon d’afficher le paywall. Si la ViewConfiguration est présente, traitez-le comme un paywall Paywall Builder ; sinon, gérez-le comme un paywall personnalisé.
try {
final view = await AdaptyUI().createPaywallView(
paywall: paywall,
);
} on AdaptyError catch (e) {
// handle the error
} catch (e) {
// handle the error
}Une fois que vous avez la vue, affichez le paywall.
Obtenir un paywall pour une audience par défaut afin d’accélérer la récupération
En général, les paywalls sont récupérés presque instantanément, il n’est donc pas nécessaire de chercher à optimiser ce processus. Cependant, si vous avez de nombreuses audiences et paywalls et que vos utilisateurs disposent d’une connexion internet faible, la récupération d’un paywall peut prendre plus de temps que souhaité. Dans ce cas, vous pouvez afficher un paywall par défaut pour garantir une expérience utilisateur fluide plutôt que de ne rien afficher du tout.
Pour résoudre ce problème, vous pouvez utiliser la méthode getPaywallForDefaultAudience, qui récupère le paywall du placement spécifié pour l’audience All Users. Cependant, il est essentiel de comprendre que l’approche recommandée est de récupérer le paywall via la méthode getPaywall, comme détaillé dans la section Récupérer les informations du paywall ci-dessus.
Pourquoi nous recommandons d’utiliser getPaywall
La méthode getPaywallForDefaultAudience présente quelques inconvénients importants :
- Problèmes potentiels de compatibilité descendante : si vous devez afficher des paywalls différentes pour différentes versions de l’application (actuelle et futures), vous risquez de rencontrer des difficultés. Vous devrez soit concevoir des paywalls compatibles avec la version actuelle (legacy), soit accepter que les utilisateurs de cette version puissent rencontrer des problèmes avec des paywalls non affichées.
- Perte de ciblage : tous les utilisateurs verront la même paywall conçue pour l’audience All Users, ce qui signifie que vous perdez le ciblage personnalisé (notamment par pays, attribution marketing ou attributs personnalisés).
Si vous êtes prêt à accepter ces inconvénients pour bénéficier d’une récupération plus rapide du paywall, utilisez la méthode getPaywallForDefaultAudience comme suit. Sinon, utilisez getPaywall décrit ci-dessus.
try {
final paywall = await Adapty().getPaywallForDefaultAudience(placementId: 'YOUR_PLACEMENT_ID');
} on AdaptyError catch (adaptyError) {
// handle error
} catch (e) {
// handle unknown error
}La méthode getPaywallForDefaultAudience est disponible à partir de la version 3.2.0 du SDK Flutter.
| Paramètre | Présence | Description |
|---|---|---|
| placementId | requis | L’identifiant du Placement. C’est la valeur que vous avez spécifiée lors de la création d’un placement dans votre Adapty Dashboard. |
| locale | optionnel par défaut : | L’identifiant de la localisation du paywall. Ce paramètre doit être un code de langue composé d’un ou plusieurs sous-tags séparés par le caractère moins (-). Le premier sous-tag correspond à la langue, le second à la région. Exemple : Consultez Localisations et codes de langue pour plus d’informations sur les codes de langue et nos recommandations d’utilisation. |
| fetchPolicy | par défaut : AdaptyPaywallFetchPolicy.reloadRevalidatingCacheData |
Cependant, si vos utilisateurs ont une connexion internet instable, envisagez Une troisième option, Notez que le cache est conservé lors du redémarrage de l’application et n’est effacé que lors de la désinstallation ou d’un nettoyage manuel. |
Personnaliser les assets
Pour personnaliser les images et vidéos de votre paywall, implémentez des assets personnalisés.
Les images et vidéos hero ont des identifiants prédéfinis : hero_image et hero_video. Dans un bundle d’assets personnalisés, vous ciblez ces éléments par leurs identifiants pour personnaliser leur comportement.
Pour les autres images et vidéos, vous devez définir un identifiant personnalisé dans l’Adapty Dashboard.
Par exemple, vous pouvez :
- Afficher une image ou une vidéo différente à certains utilisateurs.
- Afficher une image de prévisualisation locale pendant le chargement d’une image principale distante.
- Afficher une image de prévisualisation avant de lancer une vidéo.
Pour utiliser cette fonctionnalité, mettez à jour le SDK Flutter d’Adapty vers la version 3.8.0 ou supérieure.
Voici un exemple montrant comment fournir des ressources personnalisées via un simple dictionnaire :
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
}Si un asset est introuvable, le paywall reviendra à son apparence par défaut.
Configurer les minuteries définies par le développeur
Pour utiliser des minuteries personnalisées dans votre application mobile, passez une map customTimers à la méthode createPaywallView. Chaque clé de la map est un identifiant de minuterie, et sa valeur est un objet DateTime qui définit quand la minuterie se termine. Voici un exemple :
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
}Dans cet exemple, CUSTOM_TIMER_NY et CUSTOM_TIMER_6H sont les Timer IDs des minuteurs définis par le développeur dans l’Adapty Dashboard. La map customTimers permet à votre application de mettre à jour dynamiquement chaque minuteur avec la valeur correcte. Par exemple :
CUSTOM_TIMER_NY: le temps restant jusqu’à la fin du minuteur, par exemple le Jour de l’An.CUSTOM_TIMER_6H: le temps restant dans une période de 6 heures démarrée lorsque l’utilisateur a ouvert le paywall.