Le SDK Adapty Unity 4.1 est la première version stable de la ligne 4.x — la 4.0 n’a été publiée qu’en bêta, donc si vous êtes sur la 3.x, migrez directement vers la 4.1. Ce guide couvre l’intégralité de la migration : les flows introduits en 4.0 et les changements apportés par la 4.1.

La version 4.x introduit les flows et renomme les API de paywall en conséquence. Les nouvelles API fonctionnent avec les flows, et elles continuent de fonctionner avec les paywalls de l’ancien builder — aucune modification de configuration n’est requise côté Adapty Dashboard. De plus, la version 4.1 renomme les API d’attribution externe, rend l’attribution Adapty opt-in, ajoute une méthode de listener obligatoire et modifie le format du fichier de secours.

Référence rapide

v3	v4.1
Adapty.GetPaywall(placementId, locale, ...)	Adapty.GetFlow(placementId, ...)
Adapty.GetPaywallForDefaultAudience(placementId, locale, ...)	Adapty.GetFlowForDefaultAudience(placementId, ...)
Adapty.GetPaywallProducts(paywall, ...)	Adapty.GetPaywallProducts(flow, ...)
Adapty.LogShowPaywall(paywall, ...)	Adapty.LogShowFlow(flow, ...)
AdaptyPaywall	AdaptyFlow
AdaptyUI.CreatePaywallView(paywall, ...)	AdaptyUI.CreateFlowView(flow, ...)
AdaptyUICreatePaywallViewParameters	AdaptyUICreateFlowViewParameters
AdaptyUIPaywallView	AdaptyUIFlowView
AdaptyUI.PresentPaywallView(view, ...) / DismissPaywallView(view, ...)	AdaptyUI.PresentFlowView(view, ...) / DismissFlowView(view, ...)
Adapty.SetPaywallsEventsListener(listener)	Adapty.SetFlowsEventsListener(listener)
AdaptyPaywallsEventsListener	IAdaptyFlowsEventsListener
AdaptyEventListener	IAdaptyEventListener, avec une nouvelle méthode obligatoire OnReceivePromotedPurchase
AdaptyOnboardingsEventsListener	IAdaptyOnboardingsEventsListener
PaywallViewDidPerformAction, PaywallViewDidAppear, et autres callbacks PaywallView...	FlowViewDidPerformAction, FlowViewDidAppear, et autres callbacks FlowView...
PaywallViewDidFailRendering	FlowViewDidReceiveError
Adapty.UpdateAttribution(data, source, ...) avec une source de type string	Adapty.UpdateExternalAttribution(jsonString, provider, ...) avec un AdaptyExternalAttributionProvider
AdaptyProfile.AppliedAttributionSources en tant que IReadOnlyList<string>	AdaptyProfile.AppliedExternalAttributionProviders en tant que IReadOnlyList<AdaptyExternalAttributionProvider>
Attribution Adapty activée automatiquement	désactivée par défaut — à activer avec Builder.SetAdaptyAttributionEnabled(true)
Fichier de secours téléchargé pour la version 3.x	nouveau format de fichier de secours — téléchargez à nouveau le fichier
Adapty.SetFallbackPaywalls(...) (déprécié en v3)	supprimé — utilisez Adapty.SetFallback(fileName, ...)
Builder.SetIDFACollectionDisabled(...) (déprécié en v3)	supprimé — utilisez Builder.SetAppleIDFACollectionDisabled(...)
paywall.Products (une liste de AdaptyProductReference)	supprimé — utilisez ProductIdentifiers ou VendorProductIds, ou appelez GetPaywallProducts(flow) pour les produits complets
AdaptyProductReference	supprimé en tant que type public — voir Modèle de données
paywall.RemoteConfigString	supprimé — utilisez flow.RemoteConfig?.Data

AdaptyPaywallProduct conserve son nom — les produits appartiennent toujours à un flow, et GetPaywallProducts conserve é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) sont inchangées. SetFallback conserve sa signature, mais le fichier qu’il lit doit être téléchargé à nouveau — voir Fichiers de secours. 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.

Installation

Pour installer le SDK 4.1 via le Unity Package Manager, ajoutez le tag de version à l’URL Git :

https://github.com/adaptyteam/AdaptySDK-Unity.git?path=/Packages/com.adapty.unity-sdk#4.1.0

Si vous installez via le package Unity, téléchargez adapty-unity-plugin-4.1.0.unitypackage depuis la version 4.1.0. Consultez Installer Adapty SDK pour la configuration complète.

Deux changements de configuration de build accompagnent la version 4.x :

• Les dépendances iOS passent à Swift Package Manager. Le SDK iOS natif d’Adapty est désormais déclaré comme un package Swift distant plutôt que comme un pod CocoaPods. Mettez à jour l’External Dependency Manager vers la version 1.2.188 ou ultérieure — les versions antérieures ne prennent pas en charge les dépendances Swift Package Manager. Les étapes CocoaPods (iOS Resolver -> Install Cocoapods, ouverture de Unity-iPhone.xcworkspace) ne s’appliquent plus. La compilation pour iOS nécessite désormais Xcode 26 ou une version ultérieure, car le package Swift est compilé avec Swift tools 6.2.
• La cible de déploiement iOS doit être 15.0 ou ultérieure. Un nouveau validateur de build dans l’Unity Editor bloque la compilation iOS si la cible est inférieure à cette version.

Les SDK natifs Adapty sous-jacents passent à la version 4.x sur les deux plateformes et sont résolus automatiquement — aucune autre modification de build n’est nécessaire.

Récupération des flows

GetPaywall → GetFlow

Le type retourné passe de AdaptyPaywall à AdaptyFlow, et le paramètre locale est supprimé — lors du rendu d’un flow, la locale est résolue automatiquement ; pour les paywalls personnalisés, toutes les locales sont retournées dans flow.RemoteConfigs :

- Adapty.GetPaywall("YOUR_PLACEMENT_ID", "en", (paywall, error) => {
+ Adapty.GetFlow("YOUR_PLACEMENT_ID", (flow, error) => {
      if (error != null) {
          // handle the error
          return;
      }
-     // use the paywall
+     // use the flow
  });

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

- Adapty.GetPaywallForDefaultAudience("YOUR_PLACEMENT_ID", "en", (paywall, error) => { /* ... */ });
+ Adapty.GetFlowForDefaultAudience("YOUR_PLACEMENT_ID", (flow, error) => { /* ... */ });

GetPaywallProducts(paywall) → GetPaywallProducts(flow)

GetPaywallProducts conserve son nom mais prend désormais un AdaptyFlow :

- Adapty.GetPaywallProducts(paywall, (products, error) => {
+ Adapty.GetPaywallProducts(flow, (products, error) => {
      if (error != null) {
          // handle the error
          return;
      }
      // use the products
  });

Modèle de données

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

Propriété v3 AdaptyPaywall	Propriété v4 AdaptyFlow	Action
RemoteConfig (unique, nullable)	RemoteConfigs (liste)	Un flow contient une Remote Config par langue configurée. Lisez celle qui correspond à l’utilisateur via flow.RemoteConfigs. Le raccourci flow.RemoteConfig renvoie la première entrée.
(nouveau)	Paywalls (liste de AdaptyFlowPaywall)	Chaque entrée est une variation de paywall dans le flow, avec son propre Name, VariationId et ProductIdentifiers. Les méthodes de paywall web prennent un AdaptyFlowPaywall — voir Méthodes de paywall web.
ProductIdentifiers, VendorProductIds	conservé	Sur AdaptyFlow, ces propriétés agrègent les produits de toutes les variations de paywall. Chaque variation expose également ses propres ProductIdentifiers et VendorProductIds. Pour récupérer les produits, continuez d’appeler GetPaywallProducts(flow).
HasViewConfiguration	supprimé	Supprimez tout contrôle HasViewConfiguration de votre code — CreateFlowView renvoie une erreur à la place (voir Affichage des flows).
Products (liste de AdaptyProductReference)	supprimé	AdaptyProductReference n’est plus public, et avec lui les valeurs PromotionalOfferId, WinBackOfferId et AndroidOfferId qu’il portait. Utilisez ProductIdentifiers — une liste de AdaptyProductIdentifier avec VendorProductId et le BasePlanId réservé à Android (le AndroidBasePlanId de la v3) — ou appelez GetPaywallProducts(flow) quand vous avez besoin d’objets AdaptyPaywallProduct complets avec les prix et les offres.
RemoteConfigString	supprimé	Lisez la chaîne directement depuis la Remote Config : flow.RemoteConfig?.Data, ou l’entrée correspondante dans flow.RemoteConfigs.
(nouveau)	FlowVersionId (nullable)	L’identifiant de version du flow, ou null s’il n’est pas disponible.

AdaptyPaywallProduct gagne un champ supplémentaire : FlowProductId, l’identifiant du produit au sein du flow, qui est null pour les produits n’appartenant pas à un flow.

Méthodes de paywall web

OpenWebPaywall et CreateWebPaywallUrl conservent leurs noms, mais l’argument paywall accepte désormais un AdaptyFlowPaywall — l’une des variantes dans flow.Paywalls. Vous pouvez toujours passer un AdaptyPaywallProduct à la place :

- Adapty.OpenWebPaywall(paywall, AdaptyWebPresentation.ExternalBrowser, (error) => { /* ... */ });
+ var flowPaywall = flow.Paywalls.FirstOrDefault();
+ if (flowPaywall != null) {
+     Adapty.OpenWebPaywall(flowPaywall, AdaptyWebPresentation.ExternalBrowser, (error) => { /* ... */ });
+ }

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, ainsi les métriques de funnel et de test A/B continuent de fonctionner sans modification dans le tableau de bord.

- Adapty.LogShowPaywall(paywall, (error) => { /* ... */ });
+ Adapty.LogShowFlow(flow, (error) => { /* ... */ });

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 Adapty — Adapty suit ces vues automatiquement.

Afficher des flows

CreatePaywallView → CreateFlowView

Renommez la méthode factory et passez l’AdaptyFlow. Le type de vue retourné est renommé de AdaptyUIPaywallView en AdaptyUIFlowView, mais ses méthodes (Present, Dismiss) restent inchangées, et l’objet de paramètres optionnels conserve les mêmes champs (LoadTimeout, PreloadProducts, CustomTags, CustomTimers, CustomAssets, ProductPurchaseParameters) sous le nouveau nom AdaptyUICreateFlowViewParameters, plus deux nouveaux — Locale et EnableSafeAreaPaddings :

- AdaptyUI.CreatePaywallView(paywall, parameters, (view, error) => {
+ AdaptyUI.CreateFlowView(flow, parameters, (view, error) => {
      if (error != null) {
          // handle the error
          return;
      }
      view.Present((error) => { /* handle the error */ });
  });

CreateFlowView renvoie une erreur si le flow n’a pas de vue configurée — cela remplace la vérification HasViewConfiguration de la v3 :

- if (paywall.HasViewConfiguration) {
-     AdaptyUI.CreatePaywallView(paywall, null, (view, error) => { /* ... */ });
- }
+ AdaptyUI.CreateFlowView(flow, (view, error) => {
+     if (error != null) {
+         // the flow has no view configured, or view creation failed
+         return;
+     }
+     view.Present((error) => { /* handle the error */ });
+ });

Marges de zone sécurisée Android

AdaptyUICreateFlowViewParameters ajoute EnableSafeAreaPaddings, qui contrôle les marges de zone sécurisée Android à l’exécution. Il est ignoré sur iOS et vaut true par défaut :

var parameters = new AdaptyUICreateFlowViewParameters()
    .SetEnableSafeAreaPaddings(false);

Gestion des événements

Les interfaces de listener suivent désormais la convention C# avec préfixe I — il n’existe plus d’alias hérités : renommez AdaptyEventListener en IAdaptyEventListener et AdaptyOnboardingsEventsListener en IAdaptyOnboardingsEventsListener partout où vous les implémentez.

L’écouteur d’événements de flow est renommé de AdaptyPaywallsEventsListener en IAdaptyFlowsEventsListener, sa méthode d’enregistrement de SetPaywallsEventsListener en SetFlowsEventsListener, et ses callbacks remplacent le préfixe PaywallView par FlowView. Le corps des handlers existants ne nécessite aucune modification — il suffit de renommer l’interface et les méthodes :

- public class MyListener : MonoBehaviour, AdaptyPaywallsEventsListener {
-     public void PaywallViewDidFinishPurchase(
-         AdaptyUIPaywallView view,
+ public class MyListener : MonoBehaviour, IAdaptyFlowsEventsListener {
+     public void FlowViewDidFinishPurchase(
+         AdaptyUIFlowView view,
          AdaptyPaywallProduct product,
          AdaptyPurchaseResult purchasedResult
      ) {
          // custom logic after purchase
      }
      // ...
  }

- Adapty.SetPaywallsEventsListener(myListener);
+ Adapty.SetFlowsEventsListener(myListener);

Un callback est renommé : PaywallViewDidFailRendering devient FlowViewDidReceiveError. Il se déclenche pour les mêmes erreurs de rendu qu’auparavant, plus d’autres erreurs d’exécution non liées aux achats :

- public void PaywallViewDidFailRendering(AdaptyUIPaywallView view, AdaptyError error) { }
+ public void FlowViewDidReceiveError(AdaptyUIFlowView view, AdaptyError error) { }

Consultez Gérer les événements de flow et de paywall pour la liste complète des callbacks.

Nouvelle méthode requise : OnReceivePromotedPurchase

À partir de la version 4.1 du SDK, IAdaptyEventListener comporte une méthode supplémentaire. Toute classe l’implémentant ne compilera plus tant que vous n’aurez pas ajouté :

public void OnReceivePromotedPurchase(AdaptyPromotedProduct product) {
    // The user tapped one of your in-app purchases on your App Store product page.
    // Complete the purchase through Adapty:
    Adapty.MakePromotedPurchase(product, (result, error) => { /* ... */ });
}

Cette méthode concerne les achats intégrés mis en avant sur l’App Store et n’est jamais appelée sur Android. Ne laissez pas le corps vide : sur iOS 16.4 et versions ultérieures, le SDK transmet l’achat ici et attend que vous le finalisiez — un corps vide abandonne donc un achat que l’utilisateur a déjà initié. Sur les versions antérieures, ces achats étaient finalisés automatiquement. Voir Achats intégrés mis en avant sur l’App Store.

Nouvelles API

• Adapty.SetObserverModeResolver(...) avec un IAdaptyUIObserverModeResolver — gérer les achats et restaurations initiés depuis les flows lorsque le SDK fonctionne en mode Observer. Auparavant, cette fonctionnalité n’était disponible que dans les SDKs natifs iOS et Android. Voir Présenter les flows en mode Observer.
• Adapty.SetSystemRequestsHandler(...) avec un IAdaptyUISystemRequestsHandler — réservé aux requêtes système provenant d’un flow : invites de permission OS (FlowViewDidAskPermission) et demandes d’avis sur l’app (FlowViewDidRequestAppReview). Les flows ne déclenchent pas encore ces requêtes, vous n’avez donc pas besoin d’enregistrer un handler.
• AdaptyUICreateFlowViewParameters.Locale (à définir avec SetLocale) — afficher un flow ou un paywall avec une localisation Builder spécifique plutôt que celle par défaut du flow. Un flow est localisé au moment de la création de sa vue, c’est donc le seul endroit pour choisir sa localisation, et la vue créée indique la localisation avec laquelle elle a été construite dans view.Locale. Voir Utiliser les localisations et les codes de langue.
• Le nouveau callback FlowViewDidReceiveAnalyticEvent sur IAdaptyFlowsEventsListener remonte les événements analytiques d’un flow, en commençant par une vue d’écran pour chaque écran qu’un utilisateur ouvre. Voir Suivre les vues d’écran des flows.
• AdaptyUI.OpenUrl(url, openIn, ...) et AdaptyUI.RequestAppReview(...) — le traitement natif derrière les actions open_url et les demandes d’avis sur l’app. Appelez OpenUrl depuis FlowViewDidPerformAction pour conserver le comportement URL par défaut ; RequestAppReview sert d’appui à l’invite d’avis sur l’app par défaut, que les flows ne déclenchent pas encore.

API d’attribution externe renommées

À partir de la version 4.1 du SDK, les API permettant de transmettre des données d’attribution depuis un fournisseur externe (Adjust, AppsFlyer, Branch, Tenjin ou un fournisseur personnalisé) sont renommées pour s’aligner sur les SDK natifs, et le fournisseur passe d’une chaîne de caractères à un type. Il n’existe pas d’alias dépréciés, donc les appels existants ne compileront plus tant que vous ne les aurez pas mis à jour :

Avant 4.1	4.1
Adapty.UpdateAttribution(data, source, ...)	Adapty.UpdateExternalAttribution(jsonString, provider, ...)
source en tant que string	provider en tant qu’AdaptyExternalAttributionProvider
AdaptyProfile.AppliedAttributionSources en tant qu’IReadOnlyList<string>	AdaptyProfile.AppliedExternalAttributionProviders en tant qu’IReadOnlyList<AdaptyExternalAttributionProvider>

Renommer la méthode seule ne suffit pas — remplacez également l’argument provider dans la même modification :

- Adapty.UpdateAttribution(attributionJsonString, "adjust", (error) => { /* ... */ });
+ Adapty.UpdateExternalAttribution(attributionJsonString, AdaptyExternalAttributionProvider.Adjust, (error) => { /* ... */ });

AdaptyExternalAttributionProvider transporte l’identifiant que le backend associe au fournisseur, avec six instances partagées : AppleAds (apple_search_ads), Adjust, Appsflyer, Branch, Tenjin et Custom. Pour un fournisseur qu’Adapty ajoute après cette version du SDK, construisez-en un à partir de son identifiant — new AdaptyExternalAttributionProvider("your_provider") — et il parvient au backend tel quel. Les espaces environnants sont supprimés.

Les données d’attribution sont transmises sous forme de chaîne JSON sérialisée. Si vous les avez sous forme de dictionnaire, sérialisez-les d’abord :

var attributionJsonString = Newtonsoft.Json.JsonConvert.SerializeObject(attribution);

Du côté du profil, lisez les fournisseurs appliqués via le nouveau type :

- if (profile.AppliedAttributionSources.Contains("apple_search_ads")) {
+ if (profile.AppliedExternalAttributionProviders.Contains(AdaptyExternalAttributionProvider.AppleAds)) {
      // Apple Ads attribution has been applied
  }

L’attribution Adapty est désactivée par défaut

Dans les versions précédentes, le SDK enregistrait automatiquement les installations pour l’attribution Adapty. À partir de la version 4.1 du SDK, cette fonctionnalité est désactivée par défaut : le SDK n’enregistre plus les installations, les callbacks OnInstallationDetailsSuccess et OnInstallationDetailsFail ne se déclenchent jamais, et GetCurrentInstallationStatus renvoie le statut NotAvailable.

Si vous utilisez Adapty Attribution, activez-la lors de l’initialisation du SDK :

var builder = new AdaptyConfiguration.Builder("YOUR_PUBLIC_SDK_KEY")
    .SetAdaptyAttributionEnabled(true);

Si vous n’utilisez pas Adapty Attribution, aucune modification n’est nécessaire.

Fichiers de secours

Le format du fichier de secours a changé dans le SDK 4.1. Téléchargez à nouveau les fichiers de secours iOS et Android depuis Placements > Fallbacks et remplacez ceux qui se trouvent dans Assets/StreamingAssets, même si vous les aviez déjà téléchargés pour une version antérieure.

Changements de comportement par défaut

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

• Finalisation d’achat : en v3, la vue se fermait automatiquement après un achat réussi. En v4, un flow reste ouvert après un achat ou une erreur jusqu’à ce que vous le fermiez — le SDK n’applique aucun comportement par défaut. Appelez vous-même view.Dismiss(...) dans FlowViewDidFinishPurchase dès que l’utilisateur obtient l’accès.
• Bouton retour Android : le bouton retour système (ou le geste de retour) est transmis à FlowViewDidPerformAction sous la forme d’une action SystemBack et ne ferme plus le flow par lui-même — alignement avec iOS, où un flow ne peut pas être fermé par un geste système. Donnez aux utilisateurs un moyen de sortir explicite (un bouton Close ou une action on_device_back), ou fermez la vue vous-même lors du traitement de l’action.
• Les vues sont à usage unique : après Dismiss, la vue est détruite. Appelez à nouveau CreateFlowView pour présenter le flow une nouvelle fois.
• Transactions en mode Observer : ReportTransaction ne remonte plus d’erreur de décodage en cas de succès — en v3, la réponse de succès était mal analysée, si bien qu’un rapport réussi se terminait toujours avec une erreur.

Dépréciation de l’API onboarding

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

Symboles dépréciés : GetOnboarding, GetOnboardingForDefaultAudience, AdaptyUI.CreateOnboardingView, AdaptyUI.PresentOnboardingView, AdaptyUI.DismissOnboardingView et Adapty.SetOnboardingsEventsListener.