Migrer vers le SDK Flutter Adapty v4.1

Le SDK Flutter Adapty 4.1 modifie la façon dont Adapty Attribution est activé, renomme les API d’attribution externe et change le format du fichier de secours. Il transmet également les achats intégrés promus sur l’App Store à votre application, et ajoute un moyen de maintenir une vue de flow active après l’avoir fermée.

Si vous êtes encore sur la version 3.x, commencez par Migrer vers v4.0, puis suivez ce guide.

Référence rapide

Les API d’achat, de profil et de présentation de flow sont par ailleurs inchangées.

Installation

Mettez à jour adapty_flutter vers la v4.1 dans votre pubspec.yaml :

dependencies:
  adapty_flutter: 4.1.0

Si votre application utilise le Mode enfants, spécifiez adapty_flutter_kids à la place :

dependencies:
  adapty_flutter_kids: 4.1.0

Les prérequis sont inchangés par rapport à la v4.0 : Flutter 3.32.0 (Dart 3.8.0) et iOS 15.0. Consultez Installer le SDK Adapty pour la configuration complète.

4.1 fixe le SDK iOS natif à la version 4.1.3 et le SDK Android natif à la version 4.1.1. La version iOS corrige également les paramètres numériques des événements analytiques de flow : auparavant, chaque 0 et 1 arrivait dans flowViewDidReceiveAnalyticEvent sous la forme false et true.

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

Dans la version 4.0 et les versions antérieures, le SDK enregistrait les installations pour Adapty Attribution automatiquement. À partir de la version 4.1, cette fonctionnalité est désactivée par défaut : le SDK n’enregistre pas les installations, onUpdateInstallationDetailsSuccessStream et onUpdateInstallationDetailsFailStream n’émettent jamais, et getCurrentInstallationStatus retourne AdaptyInstallationStatusNotAvailable.

Si vous utilisez Adapty Attribution, activez-le lors de la configuration du SDK :

  await Adapty().activate(
-   configuration: AdaptyConfiguration(apiKey: 'YOUR_PUBLIC_SDK_KEY'),
+   configuration: AdaptyConfiguration(apiKey: 'YOUR_PUBLIC_SDK_KEY')
+     ..withAdaptyAttributionEnabled(true),
  );

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

API d’attribution externe renommées

Les API qui transmettent les données d’attribution depuis un fournisseur externe (Adjust, AppsFlyer, Branch, Tenjin ou un fournisseur personnalisé) ont été renommées pour correspondre aux SDK natifs.

updateAttribution → updateExternalAttribution

La méthode est renommée et son paramètre source est renommé en provider. Le paramètre accepte désormais un AdaptyExternalAttributionProvider au lieu d’une chaîne de caractères, et les données d’attribution restent une map :

- await Adapty().updateAttribution(attribution, source: 'adjust');
+ await Adapty().updateExternalAttribution(attribution, provider: AdaptyExternalAttributionProvider.adjust);

AdaptyAttributionSource → AdaptyExternalAttributionProvider

Le type de fournisseur est renommé. Il reste un wrapper ouvert sur une chaîne — les valeurs prédéfinies sont appleAds, adjust, appsflyer, branch, tenjin, et un nouveau custom pour les fournisseurs qu’Adapty n’intègre pas directement. Vous pouvez en construire un à partir de n’importe quelle autre chaîne, ce qui permet d’utiliser un fournisseur qu’Adapty ajouterait plus tard sans mettre à jour le SDK :

final provider = AdaptyExternalAttributionProvider('my_provider');

AdaptyProfile.appliedAttributionSources → appliedExternalAttributionProviders

La propriété du profil qui liste les fournisseurs d’attribution appliqués au profil est renommée, et le type de ses éléments change en conséquence :

- if (profile.appliedAttributionSources.contains(AdaptyAttributionSource.appleAds)) {
+ if (profile.appliedExternalAttributionProviders.contains(AdaptyExternalAttributionProvider.appleAds)) {
      // Apple Ads attribution has been applied
  }

Le champ sérialisé du profil conserve le nom applied_attribution_sources, donc un backend qui lit le profil brut n’a pas besoin d’être modifié. Le code qui lit la propriété, lui, doit être mis à jour — voir Afficher un paywall ciblé Apple Ads.

Fichiers de secours

Le format du fichier de secours a changé dans le SDK 4.1. Téléchargez à nouveau le fichier depuis Placements > Fallbacks et intégrez-le à votre application, même si vous en aviez déjà téléchargé un pour la version 4.0.

⚠️ Les achats intégrés promus attendent désormais votre app

Avec la version 4.0, Adapty enregistrait un achat promu comme n’importe quelle autre transaction, sans que votre application puisse l’intercepter. La version 4.1 vous donne ce contrôle, et avec lui la responsabilité de finaliser l’achat.

Abonnez-vous à didReceivePromotedPurchaseStream et transmettez le produit à makePromotedPurchase :

Adapty().didReceivePromotedPurchaseStream.listen((product) async {
  try {
    final result = await Adapty().makePromotedPurchase(product: product);
    // process the purchase result
  } on AdaptyError catch (e) {
    // handle the error
  }
});

Abonnez-vous avant qu’un achat promu puisse arriver — au démarrage de l’application, juste après activate. Le stream est un broadcast stream qui ne rejoue pas : un produit livré alors que rien n’écoute est ignoré, et l’achat est perdu.

makePromotedPurchase ne prend aucun paramètre d’achat, car un produit promu provient de l’App Store plutôt que d’un paywall et ne porte aucun contexte de paywall. Il retourne le même AdaptyPurchaseResult que makePurchase.

Si le produit promu comporte une offre d’abonnement, le SDK l’applique automatiquement lors de l’achat. L’offre est lue depuis l’intention d’achat de l’App Store, qui l’expose sur iOS 18.0 et versions ultérieures. Sur iOS 16.4–17.x, l’achat se fait au prix de base.

Conserver une vue de flow active après l’avoir fermée

AdaptyUI().dismissFlowView et AdaptyUIFlowView.dismiss acceptent un paramètre destroy :

await AdaptyUI().dismissFlowView(view, destroy: false);

Par défaut, sa valeur est true, ce qui libère la vue comme avant. Avec destroy: false, la vue reste active : vous pouvez la réafficher et l’utilisateur retrouve l’écran où il s’était arrêté, avec l’état que le flow avait construit.

Une vue conservée de cette façon est maintenue en mémoire jusqu’à ce que vous la fermiez avec destroy: true. Présenter une vue libérée échoue, donc appelez à nouveau createFlowView pour afficher ce flow une nouvelle fois.

hasViewConfiguration

AdaptyFlow.hasViewConfiguration exige désormais aussi que le flow contienne un schéma UI, il ne renvoie donc true que pour un flow qu’AdaptyUI est capable d’afficher. Un flow qui arrive dans votre application sans son schéma renvoie maintenant false, là où la version 4.0 renvoyait true. Voir Récupérer la configuration de vue.