--- title: "Migrer le SDK Adapty Capacitor vers la v. 4.0" description: "Migrez vers le SDK Adapty Capacitor v4.0 (bêta) en remplaçant les API paywall par des API flow, compatibles avec le Flow Builder et le Paywall Builder." --- 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 \{#quick-reference\} | 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](#fallback-files). 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](#onboarding-api-deprecation). Certains comportements par défaut ont changé — voir [Changements de comportement par défaut](#default-behavior-changes). ## Versions minimales \{#minimum-versions\} 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 \{#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 : ```bash showLineNumbers npm install @adapty/capacitor@4.0.0-beta.3 ``` Synchronisez ensuite les projets natifs : ```bash showLineNumbers npx cap sync ``` ### iOS : Swift Package Manager uniquement \{#ios-swift-package-manager-only\} [Le dépôt de specs CocoaPods passe en lecture seule en décembre 2026](https://blog.cocoapods.org/CocoaPods-Specs-Repo/), 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 : ```bash showLineNumbers 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](https://capacitorjs.com/docs/ios/spm#using-spm-in-an-existing-capacitor-project). Consultez [Installer le SDK Adapty](sdk-installation-capacitor) pour la configuration complète. ## Récupération des flows \{#fetching-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` : ```diff showLineNumbers - 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 : ```diff showLineNumbers - 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` : ```diff showLineNumbers - const products = await adapty.getPaywallProducts({ paywall }); + const products = await adapty.getPaywallProducts({ flow }); ``` ### Fichiers de secours \{#fallback-files\} Le format du fichier de secours [a changé avec le SDK v4](fallback-flows). Téléchargez le nouveau fichier depuis **[Placements](https://app.adapty.io/placements)** > **Fallbacks** et intégrez-le dans votre application. ## Modèle de données \{#data-model\} `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](#displaying-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 : ```diff showLineNumbers - const ids = paywall.products; + const ids = flow.paywalls[0].productIdentifiers; ``` ## Méthodes de paywall web \{#web-paywall-methods\} `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 : ```diff showLineNumbers 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 \{#tracking-flow-views\} ### 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. ```diff showLineNumbers - 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](adapty-flow-builder) ou le [Paywall Builder](adapty-paywall-builder) — Adapty suit ces vues automatiquement. ## Affichage des flows \{#displaying-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` : ```diff showLineNumbers - 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 : ```diff showLineNumbers - 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 + } ``` :::note Une vue de flow est à usage unique : après avoir appelé `dismiss()`, la vue est détruite et ses gestionnaires d'événements sont effacés. Appelez à nouveau `createFlowView` pour afficher le flow une nouvelle fois. ::: ### Marges de zone sécurisée Android \{#android-safe-area-paddings\} `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 : ```typescript showLineNumbers const view = await createFlowView(flow, { android: { enableSafeArea: true }, }); ``` ## Gestion des événements \{#handling-events\} 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 : ```diff showLineNumbers - 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](capacitor-handling-events) 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](capacitor-present-flows-in-observer-mode). ## Changements de comportement par défaut \{#default-behavior-changes\} 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 \{#removed-apis\} ### 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 : ```diff showLineNumbers - await adapty.activate({ apiKey: 'PUBLIC_SDK_KEY', params: { lockMethodsUntilReady: true } }); + await adapty.activate({ apiKey: 'PUBLIC_SDK_KEY' }); ``` ### makePurchase : paramètres Android \{#makepurchase-android-parameters\} 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](capacitor-making-purchases) pour un exemple complet. ## Dépréciation de l'API onboarding \{#onboarding-api-deprecation\} L'ancienne API onboarding est dépréciée depuis la v4.0 au profit du [Flow Builder](adapty-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`.