--- title: "Migrer le SDK Unity Adapty vers la v. 4.0" description: "Migrez vers le SDK Unity Adapty v4.0 (bêta) en remplaçant les API paywall par des API flow, compatibles avec Flow Builder et Paywall Builder." --- Le SDK Unity Adapty 4.0 (bêta) introduit les flows et renomme les API paywall en conséquence. Les nouvelles API fonctionnent à la fois avec le nouveau Flow Builder et 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, ...)` | `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` | | `AdaptyOnboardingsEventsListener` | `IAdaptyOnboardingsEventsListener` | | `PaywallViewDidPerformAction`, `PaywallViewDidAppear`, et autres callbacks `PaywallView...` | `FlowViewDidPerformAction`, `FlowViewDidAppear`, et autres callbacks `FlowView...` | | `PaywallViewDidFailRendering` | `FlowViewDidReceiveError` | | `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](#data-model) | | `paywall.RemoteConfigString` | supprimé — utilisez `flow.RemoteConfig?.Data` | `AdaptyPaywallProduct` garde son nom — les produits appartiennent toujours à un flow, et `GetPaywallProducts` garde également son nom, 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 les fallbacks via `SetFallback` sont inchangés. Les méthodes 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). ## Installation \{#installation\} La v4.0 est une pré-version, donc épinglez le tag bêta exact. Pour l'installer via le Unity Package Manager, ajoutez le tag à l'URL Git : ``` https://github.com/adaptyteam/AdaptySDK-Unity.git?path=/Packages/com.adapty.unity-sdk#4.0.0-beta.1 ``` Si vous installez via le package Unity, téléchargez `adapty-unity-plugin-4.0.0-beta.1.unitypackage` depuis la [version 4.0.0-beta.1](https://github.com/adaptyteam/AdaptySDK-Unity/releases/tag/4.0.0-beta.1). Consultez [Installer le SDK Adapty](sdk-installation-unity#install-adapty-sdk) pour la configuration complète. Deux changements de configuration de build sont introduits avec la v4 : - **Les dépendances iOS passent à Swift Package Manager.** Le SDK iOS natif Adapty 4.0 est déclaré comme package Swift distant au lieu d'un pod CocoaPods. Mettez à jour l'[External Dependency Manager](https://github.com/googlesamples/unity-jar-resolver#getting-started) 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 cible de déploiement iOS doit être 15.0 ou supérieure.** Un nouveau validateur de build dans l'éditeur Unity bloque le build iOS si la cible est inférieure. 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 \{#fetching-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` : ```diff showLineNumbers - 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 : ```diff showLineNumbers - 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` : ```diff showLineNumbers - 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 \{#data-model\} `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](#web-paywall-methods). | | `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](#displaying-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 \{#web-paywall-methods\} `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 : ```diff showLineNumbers - 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 \{#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 modifications du tableau de bord. ```diff showLineNumbers - 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 des flows ou des 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 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` : ```diff showLineNumbers - 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` retourne une erreur si le flow n'a pas de vue configurée — cela remplace la vérification `HasViewConfiguration` de la v3 : ```diff showLineNumbers - 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 */ }); + }); ``` :::note Une vue de flow est à usage unique : après avoir appelé `Dismiss`, la vue est détruite. Appelez donc à nouveau `CreateFlowView` pour afficher le flow une nouvelle fois. ::: ### Marges de zone sécurisée Android \{#android-safe-area-paddings\} `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 : ```csharp showLineNumbers var parameters = new AdaptyUICreateFlowViewParameters() .SetEnableSafeAreaPaddings(false); ``` ## Gestion des événements \{#handling-events\} 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 : ```diff showLineNumbers - 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 : ```diff showLineNumbers - 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](unity-handling-events) pour la liste complète des callbacks. ### Nouvelles API \{#new-apis\} - `Adapty.SetObserverModeResolver(...)` avec un `IAdaptyUIObserverModeResolver` — permet de gérer les achats et restaurations initiés depuis des flows lorsque le SDK fonctionne en [mode Observer](implement-observer-mode-unity). Auparavant, cette fonctionnalité n'était disponible que dans les SDKs natifs iOS et Android. Voir [Présenter des flows en mode Observer](unity-present-flows-in-observer-mode). - `Adapty.SetSystemRequestsHandler(...)` avec un `IAdaptyUISystemRequestsHandler` — réservé aux requêtes système issues d'un flow : demandes d'autorisation OS (`FlowViewDidAskPermission`) et demandes d'avis sur l'application (`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`) — affiche un flow ou un paywall avec une [localisation Builder](add-paywall-locale-in-adapty-paywall-builder) spécifique au lieu de celle qu'Adapty déduit de l'appareil. Un flow est localisé au moment de la création de sa vue, c'est donc le seul endroit où choisir sa localisation ; la vue créée indique la localisation avec laquelle elle a été construite dans `view.Locale`. Voir [Utiliser les localisations et les codes de locale](unity-localizations-and-locale-codes). - Le nouveau callback `FlowViewDidReceiveAnalyticEvent` sur `IAdaptyFlowsEventsListener` est réservé aux événements analytiques personnalisés provenant d'un flow. Les flows n'émettent pas encore ces événements vers votre code, implémentez-le donc avec un corps vide. - `AdaptyUI.OpenUrl(url, openIn, ...)` et `AdaptyUI.RequestAppReview(...)` — la gestion native derrière les actions `open_url` et les demandes d'avis sur l'application. Appelez `OpenUrl` depuis `FlowViewDidPerformAction` pour conserver le comportement URL par défaut ; `RequestAppReview` prend en charge la demande d'avis intégrée, que les flows ne déclenchent pas encore. ## Changements de comportement par défaut \{#default-behavior-changes\} 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 \{#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 prochaine version. Prévoyez donc la migration de vos onboardings vers le Flow Builder. Symboles dépréciés : `GetOnboarding`, `GetOnboardingForDefaultAudience`, `AdaptyUI.CreateOnboardingView`, `AdaptyUI.PresentOnboardingView`, `AdaptyUI.DismissOnboardingView` et `Adapty.SetOnboardingsEventsListener`.