Le SDK Adapty Capacitor 4.0 (bêta) introduit les flows et renomme les API paywall en conséquence. Les nouvelles API fonctionnent aussi bien avec le nouveau Flow Builder qu’avec le Paywall Builder existant — aucune modification de configuration n’est requise côté Adapty Dashboard.

Référence rapide

v3	v4
adapty.getPaywall({ placementId, locale?, params? })	adapty.getFlow({ placementId, params? })
adapty.getPaywallForDefaultAudience({ placementId, locale?, params? })	adapty.getFlowForDefaultAudience({ placementId, params? })
adapty.getPaywallProducts({ paywall })	adapty.getPaywallProducts({ flow })
adapty.logShowPaywall({ paywall })	adapty.logShowFlow({ flow })
AdaptyPaywall (type)	AdaptyFlow + AdaptyFlowPaywall
createPaywallView(paywall, params?)	createFlowView(flow, params?)
PaywallViewController	FlowViewController
EventHandlers (type)	FlowEventHandlers
CreatePaywallViewParamsInput	CreateFlowViewParamsInput
onRenderingFailed	onError

AdaptyPaywallProduct garde son nom — les produits appartiennent toujours à un flow, et getPaywallProducts garde également son nom, en prenant désormais un AdaptyFlow. Les méthodes getFlow et getFlowForDefaultAudience ne prennent plus de paramètre locale. Les API d’achat et de profil (makePurchase, restorePurchases, getProfile, identify, updateProfile) et setFallback conservent les mêmes signatures, mais le fichier de secours lui-même doit être re-téléchargé — voir Fichiers de secours. Les méthodes de vue present, dismiss, setEventHandlers et showDialog, ainsi que les gestionnaires d’événements onCloseButtonPress, onUrlPress, onCustomAction, onProductSelected, onPurchaseStarted, onPurchaseCompleted, onPurchaseFailed, onRestoreStarted, onRestoreCompleted, onRestoreFailed, onLoadingProductsFailed, onWebPaymentNavigationFinished et onAndroidSystemBack gardent les mêmes noms qu’en v3. Les méthodes d’onboarding fonctionnent toujours mais sont dépréciées — voir Dépréciation de l’API onboarding. Certains comportements par défaut ont changé — voir Changements de comportement par défaut.

Versions minimales

Les prérequis d’exécution restent inchangés depuis la v3.16+ : iOS 15.0, Android minSdk 24 et Capacitor 8. Aucune modification de la cible de déploiement n’est nécessaire.

Un nouveau prérequis de build s’ajoute : Xcode 26 ou version ultérieure — le SDK iOS Adapty natif 4.0.1 inclus dans cette version utilise Swift tools 6.2.

La v4 embarque les SDK natifs Adapty iOS 4.0.1 et Android BOM 4.0.0.

Installation

Mettre à jour le package

La v4.0 est une version préliminaire, il faut donc épingler la version exacte — npm ne sélectionne pas les versions préliminaires avec les plages caret/tilde :

npm install @adapty/capacitor@4.0.0-beta.3

Synchronisez ensuite les projets natifs :

npx cap sync

iOS : Swift Package Manager uniquement

Le dépôt de specs CocoaPods passe en lecture seule en décembre 2026, donc à partir de la v4, le fichier AdaptyCapacitor.podspec est supprimé et le SDK s’installe sur iOS uniquement via Swift Package Manager (SPM). Le projet iOS de votre application doit utiliser l’intégration SPM de Capacitor :

• Nouvelles applications : ajoutez la plateforme iOS avec le gestionnaire de paquets SPM :

npx cap add ios --packagemanager SPM

• Applications existantes basées sur CocoaPods : migrez le projet iOS en suivant le guide Capacitor pour utiliser SPM dans un projet existant.

Consultez Installer le SDK Adapty pour la configuration complète.

Récupération des flows

getPaywall → getFlow

Le type de retour change de AdaptyPaywall en AdaptyFlow, et l’option locale est supprimée — quand vous affichez un flow, la locale est résolue automatiquement ; pour les paywalls personnalisés, toutes les locales sont renvoyées dans flow.remoteConfigs :

- const paywall = await adapty.getPaywall({ placementId: 'YOUR_PLACEMENT_ID', locale: 'en' });
+ const flow = await adapty.getFlow({ placementId: 'YOUR_PLACEMENT_ID' });

getPaywallForDefaultAudience est renommé de la même façon :

- const paywall = await adapty.getPaywallForDefaultAudience({ placementId: 'YOUR_PLACEMENT_ID', locale: 'en' });
+ const flow = await adapty.getFlowForDefaultAudience({ placementId: 'YOUR_PLACEMENT_ID' });

getPaywallProducts(paywall) → getPaywallProducts(flow)

getPaywallProducts conserve son nom mais accepte désormais un AdaptyFlow :

- const products = await adapty.getPaywallProducts({ paywall });
+ const products = await adapty.getPaywallProducts({ flow });

Fichiers de secours

Le format du fichier de secours a changé avec le SDK v4. Téléchargez le nouveau fichier depuis Placements > Fallbacks et intégrez-le dans votre application.

Modèle de données

getFlow retourne un AdaptyFlow au lieu d’un AdaptyPaywall, et la structure de l’objet a changé :

Champ v3 AdaptyPaywall	Champ v4 AdaptyFlow	Action
remoteConfig? (unique)	remoteConfigs?: AdaptyRemoteConfig[] (tableau)	Un flow porte un Remote Config par langue configurée. Lisez celui qui correspond à l’utilisateur : flow.remoteConfigs?.find((c) => c.lang === 'en').
products	flow.paywalls[i].productIdentifiers	Les identifiants de produits se trouvent désormais sur chaque variation du flow, et non sur le flow lui-même.
webPurchaseUrl?	flow.paywalls[i].webPurchaseUrl	Déplacé du flow vers chaque variation de paywall.
version?: number	flowVersionId?: string	Renommé, et le type est passé de number à string.
hasViewConfiguration	supprimé	Supprimez tout contrôle hasViewConfiguration de votre code — createFlowView lève désormais une exception à la place (voir Affichage des flows).
requestLocale	supprimé	La langue ne fait plus partie du modèle.
(nouveau)	paywalls: AdaptyFlowPaywall[]	Chaque entrée correspond à une variation de paywall dans le flow.
(nouveau)	responseCreatedAt: number	Horodatage de la réponse du serveur, en millisecondes.

hasViewConfiguration et requestLocale restent sur AdaptyOnboarding — seul le modèle de flow les supprime.

Les identifiants de produits ont été déplacés du flow vers chaque variante :

- const ids = paywall.products;
+ const ids = flow.paywalls[0].productIdentifiers;

Méthodes de paywall web

openWebPaywall et createWebPaywallUrl conservent leurs noms, mais l’option paywallOrProduct accepte désormais un AdaptyFlowPaywall (une variante de flow) plutôt qu’un AdaptyPaywall. Vous pouvez toujours passer un AdaptyPaywallProduct. Vérifiez que flow.paywalls n’est pas vide avant de lire la première entrée :

  const flow = await adapty.getFlow({ placementId: 'YOUR_PLACEMENT_ID' });
- await adapty.openWebPaywall({ paywallOrProduct: paywall });
+ await adapty.openWebPaywall({ paywallOrProduct: flow.paywalls[0] });

Suivi des vues de flow

logShowPaywall → logShowFlow

logShowPaywall est renommé en logShowFlow et prend désormais un AdaptyFlow. L’événement est toujours enregistré pour la même variation, donc les métriques de funnel et de test A/B existantes continuent de fonctionner sans modification du tableau de bord.

- await adapty.logShowPaywall({ paywall });
+ await adapty.logShowFlow({ flow });

Comme dans la v3, vous n’avez pas besoin d’appeler cette méthode lors de l’affichage de flows ou de paywalls rendus par le Flow Builder ou le Paywall Builder — Adapty suit ces vues automatiquement.

Affichage des flows

createPaywallView → createFlowView

Renommez la fonction factory et passez l’AdaptyFlow. Le contrôleur retourné est renommé de PaywallViewController en FlowViewController, mais ses méthodes (present, dismiss, setEventHandlers, showDialog) restent inchangées. Le type des paramètres est renommé de CreatePaywallViewParamsInput en CreateFlowViewParamsInput :

- import { createPaywallView } from '@adapty/capacitor';
+ import { createFlowView } from '@adapty/capacitor';

- const view = await createPaywallView(paywall);
+ const view = await createFlowView(flow);
  await view.present();

createFlowView lève une AdaptyError si le flow n’a pas de vue configurée — ce qui remplace la vérification hasViewConfiguration de la v3 :

- if (paywall.hasViewConfiguration) {
-   const view = await createPaywallView(paywall);
-   await view.present();
- }
+ try {
+   const view = await createFlowView(flow);
+   await view.present();
+ } catch (error) {
+   // the flow has no view configured, or view creation failed
+ }

Marges de zone sécurisée Android

CreateFlowViewParamsInput ajoute un nouveau paramètre : enableSafeArea, qui contrôle les marges de zone sécurisée Android à l’exécution. Il est imbriqué sous la clé android et vaut true par défaut :

const view = await createFlowView(flow, {
  android: { enableSafeArea: true },
});

Gestion des événements

L’interface du gestionnaire d’événements est renommée de EventHandlers en FlowEventHandlers, et un callback est renommé. Les corps des gestionnaires existants n’ont pas besoin d’être modifiés — il suffit de renommer :

- onRenderingFailed: (error) => { /* … */ },
+ onError: (error) => { /* … */ },

Tous les autres gestionnaires d’événements conservent leur nom. Deux d’entre eux reçoivent également un deuxième argument : onPurchaseCompleted devient (purchaseResult, product) et onPurchaseFailed devient (error, product), où product est l’AdaptyPaywallProduct concerné. Consultez Gérer les événements de flow et de paywall pour la liste complète.

v4 ajoute également quelques fonctionnalités que vous pouvez activer :

• Les méthodes adapty.openWebUrl({ url, openIn }) et adapty.requestAppReview() — elles alimentent les gestionnaires par défaut onUrlPress et onRequestAppReview, de sorte que les URLs et les demandes d’évaluation de l’application sont gérées nativement sans configuration particulière. Ne les appelez directement que si vous remplacez ces gestionnaires.
• Gestion des achats en mode Observateur dans les flows via les nouveaux gestionnaires onObserverPurchaseInitiated / onObserverRestoreInitiated. Voir Présenter des flows en mode Observateur.

Changements de comportement par défaut

Ces changements ne provoquent pas d’erreurs de compilation, testez-les donc à l’exécution :

• onAndroidSystemBack: Le comportement par défaut est passé de la fermeture de la vue à son maintien ouvert. Pour retrouver l’ancien comportement, renvoyez true depuis le handler.
• onPurchaseCompleted: Le comportement par défaut est passé de la fermeture de la vue (sauf si l’utilisateur a annulé l’achat) à son maintien ouvert dans tous les cas. Pour retrouver l’ancien comportement, renvoyez purchaseResult.type !== 'user_cancelled' depuis le handler.
• onRestoreCompleted: Le comportement par défaut est passé de la fermeture de la vue après une restauration réussie à son maintien ouvert. Pour retrouver l’ancien comportement, renvoyez true depuis le handler.
• onUrlPress: Le comportement par défaut ouvre désormais l’URL via la couche native, en respectant le paramètre de navigateur intégré ou externe configuré dans le tableau de bord. Surchargez le handler pour ouvrir les URL vous-même.
• Les vues sont à usage unique : après dismiss(), la vue est détruite. Appelez createFlowView à nouveau pour afficher le flow une nouvelle fois.

API supprimées

Exports supprimés

Ces symboles ne sont plus exportés depuis @adapty/capacitor. Supprimez leurs imports :

• AdaptyPaywall : Utilisez AdaptyFlow et AdaptyFlowPaywall à la place.
• ProductReference : Utilisez AdaptyProductIdentifier, accessible via flow.paywalls[i].productIdentifiers.
• AdaptyPaywallBuilder : Supprimé. Les flows et paywalls s’affichent nativement.
• AdaptyAndroidSubscriptionUpdateParameters : Utilisez la structure imbriquée des paramètres d’achat android (voir ci-dessous).

activate: lockMethodsUntilReady

lockMethodsUntilReady (déjà obsolète et sans effet en v3) est supprimé. Retirez-le de votre appel activate — le conserver ne compile plus :

- await adapty.activate({ apiKey: 'PUBLIC_SDK_KEY', params: { lockMethodsUntilReady: true } });
+ await adapty.activate({ apiKey: 'PUBLIC_SDK_KEY' });

makePurchase : paramètres Android

La forme Android plate (deprecated) de MakePurchaseParamsInput est supprimée — seule la forme imbriquée subsiste. Déplacez les paramètres d’achat Android dans params: { android: { ... } }. Consultez Effectuer des achats pour un exemple complet.

Dépréciation de l’API onboarding

L’ancienne API onboarding est dépréciée depuis la v4.0 au profit du Flow Builder. Elle fonctionne toujours, mais sera supprimée dans une future version — prévoyez donc la migration de vos onboardings vers le Flow Builder.

Symboles dépréciés : getOnboarding, getOnboardingForDefaultAudience, createOnboardingView et OnboardingViewController.