--- title: "Migrer le SDK React Native Adapty vers v4.0" description: "Migrez vers le SDK React Native Adapty v4.0 en remplaçant les API paywall par des API flow, compatibles avec le Flow Builder et le Paywall Builder." --- > **AI agents**: to search Adapty docs faster and with fewer tokens, install the Adapty skill. Claude Code (self-updating via plugin): `claude plugin marketplace add adaptyteam/adapty-sdk-integration-skill && claude plugin install adapty-sdk-integration@adapty` — other tools: `npx skills add adaptyteam/adapty-sdk-integration-skill --all` Le SDK React Native Adapty 4.0 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 nécessaire 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` | | `createPaywallView(paywall)` | `createFlowView(flow)` | | `AdaptyPaywallView` (composant) | `AdaptyFlowView` | | `EventHandlers` (type) | `FlowEventHandlers` | | `onPaywallShown` | `onAppeared` | | `onPaywallClosed` | `onDisappeared` | | `onRenderingFailed` | `onError` | `AdaptyPaywallProduct` garde son nom — les produits appartiennent toujours à un flow, et `getPaywallProducts` prend désormais un `AdaptyFlow`. Les méthodes `getFlow` et `getFlowForDefaultAudience` n'acceptent plus de paramètre `locale` — passez-le à `createFlowView` à la place. 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` conservent les mêmes noms qu'en v3. Certains comportements par défaut ont changé — voir [Changements de comportement par défaut](#default-behavior-changes). ## Version iOS minimale \{#minimum-ios-version\} Le SDK React Native Adapty 4.0 fait passer la version minimale de déploiement iOS de iOS 13.0 à **iOS 15.0**. Définissez votre cible de déploiement iOS à 15.0 ou supérieure avant de procéder à la mise à jour. ## Installation \{#installation\} ### Mettre à jour le package Mettez à jour le package `react-native-adapty` vers la v4.0 : ```bash showLineNumbers npm install react-native-adapty@4.0.2 # or yarn add react-native-adapty@4.0.2 ``` ### iOS : les SDK natifs passent désormais par Swift Package Manager [Le dépôt de specs CocoaPods passe en lecture seule en décembre 2026](https://blog.cocoapods.org/CocoaPods-Specs-Repo/), aussi à partir de la v4, les SDK natifs `Adapty`, `AdaptyUI` et `AdaptyPlugin` **ne sont plus inclus en tant que sous-dépendances CocoaPods** — le podspec les récupère via **Swift Package Manager** (grâce au helper `spm_dependency`). Deux points à respecter : - **React Native 0.75 ou version ultérieure** — nécessaire pour le helper de podspec `spm_dependency`. Sur une version plus ancienne, `pod install` échoue avec une erreur explicite ; mettez d'abord à jour React Native, ou restez sur `react-native-adapty` 3.x. - **Frameworks dynamiques** — les dépendances SPM nécessitent un linkage dynamique. La façon de l'activer diffère entre Expo et bare React Native. #### Expo Ajoutez le plugin de configuration [`expo-build-properties`](https://docs.expo.dev/versions/latest/sdk/build-properties/) et définissez les frameworks iOS en dynamique dans `app.json` (ou `app.config.js`) : ```json showLineNumbers title="app.json" { "expo": { "plugins": [ [ "expo-build-properties", { "ios": { "useFrameworks": "dynamic", "buildReactNativeFromSource": true } } ] ] } } ``` `buildReactNativeFromSource` est requis sur **Expo SDK 57 et versions ultérieures**. Expo SDK 57 embarque un framework React Native précompilé dont les en-têtes sont inaccessibles aux autres packages lorsque les frameworks sont dynamiques, ce qui provoque des erreurs de build iOS comme `'React/RCTBridge.h' file not found` dans `expo-updates` ou `@expo/ui`. Compiler React Native depuis les sources permet d'éviter ce conflit, au prix de builds iOS plus longs. Sur Expo SDK 56 et versions antérieures, vous pouvez omettre cette option. Installez ensuite le plugin et régénérez le projet natif : ```bash showLineNumbers npx expo install expo-build-properties npx expo prebuild --clean ``` #### Bare React Native Ajoutez les frameworks dynamiques à votre cible iOS, puis réinstallez les pods : ```ruby showLineNumbers title="ios/Podfile" use_frameworks! :linkage => :dynamic ``` ```bash showLineNumbers cd ios && pod install --repo-update ``` Si vous avez précédemment ajouté `Adapty`, `AdaptyUI` ou `AdaptyPlugin` en tant que sous-dépendances CocoaPods, supprimez d'abord toute ligne explicite `pod 'Adapty'`, `pod 'AdaptyUI'` ou `pod 'AdaptyPlugin'` de votre `Podfile`. :::warning Passer de la liaison statique par défaut aux frameworks dynamiques peut entrer en conflit avec des bibliothèques qui ne prennent pas encore en charge les en-têtes modulaires, et est incompatible avec Flipper. Si vous rencontrez des problèmes de compilation, consultez cet [article sur l'intégration de Swift Package Manager avec les bibliothèques React Native](https://www.callstack.com/blog/integrating-swift-package-manager-with-react-native-libraries). ::: Consultez [Installer le SDK Adapty](sdk-installation-reactnative) pour la configuration complète. ## Récupérer des flows \{#fetching-flows\} ### getPaywall → getFlow Le type retourné passe de `AdaptyPaywall` à `AdaptyFlow`, et le paramètre `locale` se déplace de l'appel de récupération vers `createFlowView` ; pour les paywalls personnalisés, toutes les locales sont retournées dans `flow.remoteConfigs` : ```diff showLineNumbers - const paywall = await adapty.getPaywall('YOUR_PLACEMENT_ID', 'en'); + const flow = await adapty.getFlow('YOUR_PLACEMENT_ID'); + const view = await createFlowView(flow, { locale: 'en' }); ``` `locale` reste optionnel dans `createFlowView` : si vous l'omettez, la vue s'affiche en `en`, ou dans la localisation par défaut du flow si celui-ci ne possède pas de version `en`. Cette fonctionnalité nécessite le SDK 4.0.2 ou une version ultérieure — voir [Localisations et codes de langue](react-native-localizations-and-locale-codes). `getPaywallForDefaultAudience` est renommé de la même façon : ```diff showLineNumbers - const paywall = await adapty.getPaywallForDefaultAudience('YOUR_PLACEMENT_ID', 'en'); + const flow = await adapty.getFlowForDefaultAudience('YOUR_PLACEMENT_ID'); ``` ### getPaywallProducts(paywall) → getPaywallProducts(flow) `getPaywallProducts` conserve son nom mais prend 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 des fichiers 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 à votre application. ## Modèle de données \{#data-model\} `getFlow` renvoie 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 contient 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 variante du flow, pas sur le flow lui-même. | | `webPurchaseUrl?` | `flow.paywalls[i].webPurchaseUrl` | Déplacé du flow vers chaque variante de paywall. | | `version?: number` | `flowVersionId?: string` | Renommé, et le type a changé de `number` à `string`. | | `hasViewConfiguration` | supprimé | Supprimez tout contrôle `hasViewConfiguration` de votre code. | | `requestLocale` | supprimé | La locale ne fait plus partie du modèle. | | _(nouveau)_ | `paywalls: AdaptyFlowPaywall[]` | Chaque entrée correspond à une variante de paywall dans le flow. | | _(nouveau)_ | `responseCreatedAt: number` | Horodatage de la réponse serveur, en millisecondes. | Product identifiers moved from the flow to each variation: ```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 le premier argument est désormais un `AdaptyFlowPaywall` (une variante de flow) au lieu d'un `AdaptyPaywall`. Vous pouvez toujours passer un `AdaptyPaywallProduct`. ```diff showLineNumbers const flow = await adapty.getFlow('YOUR_PLACEMENT_ID'); - await adapty.openWebPaywall(paywall); + await adapty.openWebPaywall(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 automatiquement ces vues. ## Afficher des flows \{#displaying-flows\} ### createPaywallView → createFlowView Renommez la fonction factory et passez l'`AdaptyFlow`. Les méthodes du contrôleur retourné (`present`, `dismiss`, `setEventHandlers`, `showDialog`) restent inchangées : ```diff showLineNumbers - import { createPaywallView } from 'react-native-adapty'; + import { createFlowView } from 'react-native-adapty'; - const view = await createPaywallView(paywall); + const view = await createFlowView(flow); await view.present(); ``` ### AdaptyPaywallView → AdaptyFlowView Si vous effectuez le rendu avec le composant React, renommez-le et passez la prop `flow` : ```diff showLineNumbers - import { AdaptyPaywallView } from 'react-native-adapty'; + import { AdaptyFlowView } from 'react-native-adapty'; - + ``` :::note Un flow view créé avec `createFlowView` est à usage unique : après avoir appelé `dismiss()`, la vue est détruite. Appelez donc à nouveau `createFlowView` pour afficher le flow une nouvelle fois. Un `AdaptyFlowView` intégré est fermé en le démontant — retourner `true` depuis un gestionnaire ne ferme pas une vue intégrée, modifiez donc votre propre état à la place, par exemple dans `onCloseButtonPress`. ::: ## Gestion des événements \{#handling-events\} L'interface du gestionnaire d'événements est renommée de `EventHandlers` en `FlowEventHandlers`, et trois callbacks sont renommés. Les corps des gestionnaires existants n'ont pas besoin de modification — il suffit de les renommer : ```diff showLineNumbers - onPaywallShown: () => { /* … */ }, + onAppeared: () => { /* … */ }, - onPaywallClosed: () => { /* … */ }, + onDisappeared: () => { /* … */ }, - onRenderingFailed: (error) => { /* … */ }, + onError: (error) => { /* … */ }, ``` Tous les autres gestionnaires d'événements conservent leur nom. Deux d'entre eux reçoivent également un second 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](react-native-handling-events-1) pour la liste complète. :::note `onDisappeared` se déclenche uniquement pour un flow présenté de façon modale avec `createFlowView().present()`. Le composant `AdaptyFlowView` n'expose pas cet événement en tant que prop — pour fermer une vue intégrée, il suffit de la démonter. ::: v4 ajoute également quelques fonctionnalités auxquelles vous pouvez adhérer : - Les méthodes `adapty.openWebUrl(url, openIn?)` et `adapty.requestAppReview()` — elles alimentent les handlers par défaut `onUrlPress` et `onRequestAppReview`, donc les URLs et les invites d'avis applicatif sont gérés nativement sans configuration. Ne les appelez directement que si vous surchargez ces handlers. - Gestion des achats en mode observateur dans les flows via les nouveaux handlers `onObserverPurchaseInitiated` / `onObserverRestoreInitiated`. Voir [Gérer les achats en mode observateur](react-native-handling-events-1#handle-purchases-in-observer-mode). ## APIs supprimées et dépréciées \{#removed-and-deprecated-apis\} ### setFallbackPaywalls → setFallback `setFallbackPaywalls` est supprimé. Utilisez `setFallback`, qui prend le même argument : ```diff showLineNumbers - await adapty.setFallbackPaywalls(fileLocation); + await adapty.setFallback(fileLocation); ``` ### Exports supprimés \{#removed-exports\} Ces symboles ne sont plus exportés depuis `react-native-adapty`. Supprimez leurs imports : - **`AdaptyPaywall`** : Utilisez `AdaptyFlow` à la place. - **`ProductReference`** : Utilisez `AdaptyProductIdentifier`, accessible via `flow.paywalls[i].productIdentifiers`. - **`AdaptyPaywallBuilder`** : Supprimé. Les flows et les paywalls s'affichent nativement. - **`AdaptyAndroidSubscriptionUpdateParameters`** : Utilisez la structure imbriquée `subscriptionUpdateParams` (voir ci-dessous). ### activate: lockMethodsUntilReady `lockMethodsUntilReady` est supprimé et ce comportement est désormais toujours actif. Retirez-le de votre appel `activate` — le conserver empêche la compilation : ```diff showLineNumbers - await adapty.activate('PUBLIC_SDK_KEY', { lockMethodsUntilReady: true }); + await adapty.activate('PUBLIC_SDK_KEY'); ``` ### makePurchase : mise à jour des abonnements Android \{#makepurchase-android-subscription-update\} La structure plate de mise à jour d'abonnement Android est supprimée. Déplacez `oldSubVendorProductId` et `prorationMode` dans un objet `subscriptionUpdateParams` imbriqué, et conservez `isOfferPersonalized` au niveau supérieur. Consultez [Effectuer des achats](react-native-making-purchases) pour l'exemple complet. ### Android : marges de zone de sécurité \{#android-safe-area-paddings\} La ressource booléenne Android `…` est supprimée. Retirez-la de `res/values/bools.xml` et contrôlez les marges de zone de sécurité au moment de l'exécution avec le paramètre `android.enableSafeArea` lors de la création de la vue du flow. Par défaut, cette valeur est `true` pour la présentation modale et `false` pour le composant intégré : ```typescript showLineNumbers const view = await createFlowView(flow, { android: { enableSafeArea: false, }, }); ``` ### Mode mock \{#mock-mode\} Si vous exécutez le SDK en mode mock (Expo Go ou prévisualisation web), renommez la clé de configuration mock `paywalls` en `flows`. ## Changements de comportement par défaut \{#default-behavior-changes\} Ces changements ne causent pas d'erreurs de compilation ; testez-les à l'exécution : - **`onAndroidSystemBack`** : Le comportement par défaut a changé : la vue reste ouverte au lieu de se fermer. Pour rétablir l'ancien comportement, retournez `true` depuis le handler. - **`onPurchaseCompleted`** : Le comportement par défaut a changé : la vue reste toujours ouverte au lieu de se fermer (sauf en cas d'annulation par l'utilisateur). Pour rétablir l'ancien comportement, retournez `purchaseResult.type !== 'user_cancelled'` depuis le handler. - **`onRestoreCompleted`** : Le comportement par défaut a changé : la vue reste ouverte au lieu de se fermer après une restauration réussie. Pour rétablir l'ancien comportement, retournez `true` depuis le handler. - **`onUrlPress`** : Par défaut, l'URL s'ouvre désormais via la couche native, en respectant le paramètre de navigateur intégré ou externe défini dans le tableau de bord. Remplacez le handler pour gérer vous-même l'ouverture des URL. ## Dépréciation de l'API onboarding \{#onboarding-api-deprecation\} L'ancienne API onboarding est dépréciée dans la v4.0 au profit du [Flow Builder](adapty-flow-builder). Elle fonctionne toujours, mais sera supprimée dans une version future — prévoyez donc la migration de vos onboardings vers le Flow Builder. Symboles dépréciés : `getOnboarding`, `getOnboardingForDefaultAudience`, `createOnboardingView` et `AdaptyOnboardingView`.