Migrer le SDK React Native Adapty vers v4.0

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

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.

Version iOS minimale

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

Mettre à jour le package

Mettez à jour le package react-native-adapty vers la v4.0 :

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, 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 et définissez les frameworks iOS en dynamique dans app.json (ou app.config.js) :

{
  "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 :

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 :

use_frameworks! :linkage => :dynamic

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.

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

Récupérer des 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 :

- 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.

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

- 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 :

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

Fichiers de secours

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

Modèle de données

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:

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

Méthodes de paywall web

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.

  const flow = await adapty.getFlow('YOUR_PLACEMENT_ID');
- await adapty.openWebPaywall(paywall);
+ await adapty.openWebPaywall(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 automatiquement ces vues.

Afficher des 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 :

- 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 :

- import { AdaptyPaywallView } from 'react-native-adapty';
+ import { AdaptyFlowView } from 'react-native-adapty';

- <AdaptyPaywallView paywall={paywall} /* … */ />
+ <AdaptyFlowView flow={flow} /* … */ />

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

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 :

- 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 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.

APIs supprimées et dépréciées

setFallbackPaywalls → setFallback

setFallbackPaywalls est supprimé. Utilisez setFallback, qui prend le même argument :

- await adapty.setFallbackPaywalls(fileLocation);
+ await adapty.setFallback(fileLocation);

Exports supprimés

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 :

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

makePurchase : mise à jour des abonnements Android

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 pour l’exemple complet.

Android : marges de zone de sécurité

La ressource booléenne Android <bool name="adapty_paywall_enable_safe_area_paddings">…</bool> 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é :

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

Mode mock

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

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

L’ancienne API onboarding est dépréciée dans la v4.0 au profit du 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.