Flutter - Gérer les événements de flow et de paywall

Les flows et paywalls configurés avec le builder n’ont pas besoin de code supplémentaire pour effectuer et restaurer des achats. Cependant, ils génèrent certains événements auxquels votre application peut réagir. Ces événements incluent les appuis sur des boutons (boutons de fermeture, URLs, sélections de produits, etc.) ainsi que des notifications sur les actions liées aux achats effectuées sur le flow ou le paywall. Découvrez comment répondre à ces événements ci-dessous.

Pour contrôler ou surveiller les processus qui se déroulent sur l’écran du flow ou du paywall dans votre application mobile, implémentez les méthodes AdaptyUIFlowsEventsObserver et définissez l’observateur avant d’afficher un écran :

AdaptyUI().setFlowsEventsObserver(this);

Trois méthodes d’observateur sont obligatoires — votre classe ne compilera pas sans elles : flowViewDidFinishPurchase, flowViewDidFinishRestore et flowViewDidReceiveError. Toutes les autres méthodes sont optionnelles. Pour détacher un observateur précédemment défini, passez null à setFlowsEventsObserver.

Les exemples d’événements ci-dessous montrent les propriétés disponibles sur chaque objet, avec des valeurs illustratives dans les commentaires.

Événements générés par l’utilisateur

Vue apparue

Cette méthode est invoquée lorsque la vue du flow ou du paywall est affichée à l’écran.

void flowViewDidAppear(AdaptyUIFlowView view) {
}

Vue disparue

Cette méthode est invoquée lorsque la vue du flow ou du paywall est fermée depuis l’écran.

void flowViewDidDisappear(AdaptyUIFlowView view) {
}

Sélection de produit

Si un produit est sélectionné pour l’achat (par un utilisateur ou par le système), cette méthode sera invoquée :

void flowViewDidSelectProduct(AdaptyUIFlowView view, String productId) {
}

void flowViewDidSelectProduct(AdaptyUIFlowView view, String productId) {
  // productId is a String:
  productId; // 'premium_monthly'
}

Achat démarré

Si un utilisateur lance le processus d’achat, cette méthode sera invoquée :

void flowViewDidStartPurchase(AdaptyUIFlowView view, AdaptyPaywallProduct product) {
}

void flowViewDidStartPurchase(AdaptyUIFlowView view, AdaptyPaywallProduct product) {
  // product — AdaptyPaywallProduct:
  product.vendorProductId;        // 'premium_monthly'
  product.localizedTitle;         // 'Premium Monthly'
  product.localizedDescription;   // 'Premium subscription for 1 month'
  product.price.amount;           // 9.99            (double)
  product.price.currencyCode;     // 'USD'
  product.price.localizedString;  // '$9.99'
}

Achat terminé

Cette méthode est obligatoire. Elle est invoquée lorsqu’un achat réussit, que l’utilisateur annule son achat, ou que l’achat semble en attente :

void flowViewDidFinishPurchase(AdaptyUIFlowView view, 
                               AdaptyPaywallProduct product, 
                               AdaptyPurchaseResult purchaseResult) {
    switch (purchaseResult) {
      case AdaptyPurchaseResultSuccess(profile: final profile):
        // successful purchase
        break;
      case AdaptyPurchaseResultPending():
        // purchase is pending
        break;
      case AdaptyPurchaseResultUserCancelled():
        // user cancelled the purchase
        break;
      default:
        break;
    }
}

void flowViewDidFinishPurchase(AdaptyUIFlowView view,
                               AdaptyPaywallProduct product,
                               AdaptyPurchaseResult purchaseResult) {
  // product — AdaptyPaywallProduct:
  product.vendorProductId; // 'premium_monthly'

  switch (purchaseResult) {
    case AdaptyPurchaseResultSuccess(profile: final profile):
      // profile — AdaptyProfile:
      profile.accessLevels['premium']?.isActive;  // true
      profile.accessLevels['premium']?.expiresAt; // DateTime(2027, 2, 15, 10, 30)
      break;
    case AdaptyPurchaseResultPending():
      // no additional data
      break;
    case AdaptyPurchaseResultUserCancelled():
      // no additional data
      break;
  }
}

Navigation de paiement web terminée

Cette méthode est invoquée après une tentative d’ouverture d’un paywall web pour un produit spécifique. Cela inclut les tentatives de navigation réussies et échouées :

void flowViewDidFinishWebPaymentNavigation(AdaptyUIFlowView view, 
                                           AdaptyPaywallProduct? product, 
                                           AdaptyError? error) {
}

Paramètres :

Achat échoué

Cette méthode est invoquée lorsqu’un achat échoue (par exemple, en raison de problèmes de paiement ou d’erreurs réseau). Elle ne se déclenche pas pour les annulations initiées par l’utilisateur ou les transactions en attente — celles-ci sont gérées par flowViewDidFinishPurchase :

void flowViewDidFailPurchase(AdaptyUIFlowView view, 
                             AdaptyPaywallProduct product, 
                             AdaptyError error) {
}

Restauration démarrée

Si un utilisateur lance le processus de restauration, cette méthode sera invoquée :

void flowViewDidStartRestore(AdaptyUIFlowView view) {
}

Restauration réussie

Cette méthode est obligatoire. Si la restauration d’un achat réussit, elle sera invoquée :

void flowViewDidFinishRestore(AdaptyUIFlowView view, AdaptyProfile profile) {
}

void flowViewDidFinishRestore(AdaptyUIFlowView view, AdaptyProfile profile) {
  // profile — AdaptyProfile:
  profile.accessLevels['premium']?.isActive;            // true
  profile.accessLevels['premium']?.expiresAt;           // DateTime(2027, 2, 15, 10, 30)
  profile.subscriptions['premium_monthly']?.isActive;   // true
  profile.subscriptions['premium_monthly']?.expiresAt;  // DateTime(2027, 2, 15, 10, 30)
}

Nous recommandons de fermer l’écran si l’utilisateur possède le accessLevel requis. Consultez le sujet Statut d’abonnement pour savoir comment le vérifier et le sujet Répondre aux actions de bouton pour savoir comment fermer un écran.

Restauration échouée

Si la restauration d’un achat échoue, cette méthode sera invoquée :

void flowViewDidFailRestore(AdaptyUIFlowView view, AdaptyError error) {
}

Récupération des données et rendu

Erreurs de chargement des produits

Si vous ne passez pas le tableau de produits lors de l’initialisation, AdaptyUI récupérera les objets nécessaires depuis le serveur par lui-même. Si cette opération échoue, AdaptyUI signalera l’erreur en invoquant cette méthode :

void flowViewDidFailLoadingProducts(AdaptyUIFlowView view, AdaptyError error) {
}

Erreurs de vue

Cette méthode est obligatoire. Elle remplace la méthode paywallViewDidFailRendering de la v3 : les erreurs qui surviennent pendant le rendu de l’interface, ainsi que les autres erreurs de vue, sont signalées en l’appelant. Une fois que vous l’implémentez, la fermeture est de votre responsabilité — nous recommandons de fermer la vue en cas de telles erreurs, ce qui correspond également au comportement par défaut intégré du SDK lorsqu’aucun observateur n’est défini :

void flowViewDidReceiveError(AdaptyUIFlowView view, AdaptyError error) {
  // log the error and dismiss the broken view
  view.dismiss();
}

Dans une situation normale, les erreurs de rendu ne devraient pas se produire, donc si vous en rencontrez une, veuillez nous le signaler.

Événements analytiques

La méthode optionnelle flowViewDidReceiveAnalyticEvent est réservée aux événements analytiques personnalisés d’un flow. Les flows n’émettent pas encore ces événements vers votre code, vous n’avez donc pas besoin de l’implémenter.

Gérer les achats en mode observateur

Si vous avez activé le SDK en mode observateur et présentez un flow ou un paywall rendu par Adapty, le SDK n’effectue pas les achats à votre place. Lorsqu’un utilisateur appuie sur le bouton d’achat ou de restauration, le SDK appelle votre AdaptyUIObserverModeResolver à la place. Consultez Présenter des flows en mode observateur pour la configuration complète.

Gérer les requêtes système

Le AdaptyUISystemRequestsHandler (enregistré via AdaptyUI().setSystemRequestsHandler(...)) est réservé aux requêtes système d’un flow : les invites de permission du système d’exploitation (comme les notifications push ou l’accès à la caméra) et les demandes d’avis App Store. Les flows ne déclenchent pas encore ces requêtes, vous n’avez donc pas besoin d’enregistrer un handler.

Si vous en enregistrez un, notez que handlePermission est la méthode obligatoire de la classe — demandez la permission avec votre propre code, puis retournez AdaptyUIPermissionResult.granted() ou AdaptyUIPermissionResult.denied() ; handleAppReviewRequest est optionnel.

Les paywalls configurés avec le Paywall Builder n’ont pas besoin de code supplémentaire pour effectuer et restaurer des achats. Cependant, ils génèrent certains événements auxquels votre application peut réagir. Ces événements incluent les appuis sur des boutons (boutons de fermeture, URLs, sélections de produits, etc.) ainsi que des notifications sur les actions liées aux achats effectuées sur le paywall. Découvrez comment répondre à ces événements ci-dessous.

Pour contrôler ou surveiller les processus qui se déroulent sur l’écran du paywall dans votre application mobile, implémentez les méthodes AdaptyUIPaywallsEventsObserver et définissez l’observateur avant d’afficher un écran :

AdaptyUI().setPaywallsEventsObserver(this);

Les exemples d’événements ci-dessous montrent les propriétés disponibles sur chaque objet, avec des valeurs illustratives dans les commentaires.

Événements générés par l’utilisateur

Paywall apparu

Cette méthode est invoquée lorsque la vue du paywall est affichée à l’écran.

void paywallViewDidAppear(AdaptyUIPaywallView view) {
}

Paywall disparu

Cette méthode est invoquée lorsque la vue du paywall est fermée depuis l’écran.

void paywallViewDidDisappear(AdaptyUIPaywallView view) {
}

Sélection de produit

Si un produit est sélectionné pour l’achat (par un utilisateur ou par le système), cette méthode sera invoquée :

void paywallViewDidSelectProduct(AdaptyUIPaywallView view, String productId) {
}

void paywallViewDidSelectProduct(AdaptyUIPaywallView view, String productId) {
  // productId is a String:
  productId; // 'premium_monthly'
}

Achat démarré

Si un utilisateur lance le processus d’achat, cette méthode sera invoquée :

void paywallViewDidStartPurchase(AdaptyUIPaywallView view, AdaptyPaywallProduct product) {
}

void paywallViewDidStartPurchase(AdaptyUIPaywallView view, AdaptyPaywallProduct product) {
  // product — AdaptyPaywallProduct:
  product.vendorProductId;        // 'premium_monthly'
  product.localizedTitle;         // 'Premium Monthly'
  product.localizedDescription;   // 'Premium subscription for 1 month'
  product.price.amount;           // 9.99            (double)
  product.price.currencyCode;     // 'USD'
  product.price.localizedString;  // '$9.99'
}

Achat terminé

Cette méthode est invoquée lorsqu’un achat réussit, que l’utilisateur annule son achat, ou que l’achat semble en attente :

void paywallViewDidFinishPurchase(AdaptyUIPaywallView view, 
                                  AdaptyPaywallProduct product, 
                                  AdaptyPurchaseResult purchaseResult) {
    switch (purchaseResult) {
      case AdaptyPurchaseResultSuccess(profile: final profile):
        // successful purchase
        break;
      case AdaptyPurchaseResultPending():
        // purchase is pending
        break;
      case AdaptyPurchaseResultUserCancelled():
        // user cancelled the purchase
        break;
      default:
        break;
    }
}

void paywallViewDidFinishPurchase(AdaptyUIPaywallView view,
                                  AdaptyPaywallProduct product,
                                  AdaptyPurchaseResult purchaseResult) {
  // product — AdaptyPaywallProduct:
  product.vendorProductId; // 'premium_monthly'

  switch (purchaseResult) {
    case AdaptyPurchaseResultSuccess(profile: final profile):
      // profile — AdaptyProfile:
      profile.accessLevels['premium']?.isActive;  // true
      profile.accessLevels['premium']?.expiresAt; // DateTime(2027, 2, 15, 10, 30)
      break;
    case AdaptyPurchaseResultPending():
      // no additional data
      break;
    case AdaptyPurchaseResultUserCancelled():
      // no additional data
      break;
  }
}

Nous recommandons de fermer l’écran dans ce cas. Consultez Répondre aux actions de bouton pour plus de détails sur la fermeture d’un écran de paywall.

Navigation de paiement web terminée

Cette méthode est invoquée après une tentative d’ouverture d’un paywall web pour un produit spécifique. Cela inclut les tentatives de navigation réussies et échouées :

void paywallViewDidFinishWebPaymentNavigation(AdaptyUIPaywallView view, 
                                               AdaptyPaywallProduct? product, 
                                               AdaptyError? error) {
}

Paramètres :

void paywallViewDidFinishWebPaymentNavigation(AdaptyUIPaywallView view,
                                               AdaptyPaywallProduct? product,
                                               AdaptyError? error) {
  // product — AdaptyPaywallProduct?:
  product?.vendorProductId; // 'premium_monthly'

  if (error == null) {
    // navigation succeeded
  } else {
    // error — AdaptyError:
    error.code;    // AdaptyErrorCode.networkFailed (2005)
    error.message; // 'Network request failed'
    error.detail;  // platform-specific underlying error, or null
  }
}

Achat échoué

Cette méthode est invoquée lorsqu’un achat échoue (par exemple, en raison de problèmes de paiement ou d’erreurs réseau). Elle ne se déclenche pas pour les annulations initiées par l’utilisateur ou les transactions en attente — celles-ci sont gérées par paywallViewDidFinishPurchase :

void paywallViewDidFailPurchase(AdaptyUIPaywallView view, 
                                AdaptyPaywallProduct product, 
                                AdaptyError error) {
}

void paywallViewDidFailPurchase(AdaptyUIPaywallView view,
                                AdaptyPaywallProduct product,
                                AdaptyError error) {
  // product — AdaptyPaywallProduct:
  product.vendorProductId; // 'premium_monthly'

  // error — AdaptyError:
  error.code;    // AdaptyErrorCode.productPurchaseFailed (1006)
  error.message; // 'Product purchase failed.'
  error.detail;  // platform-specific underlying error, or null
}

Restauration démarrée

Si un utilisateur lance le processus de restauration, cette méthode sera invoquée :

void paywallViewDidStartRestore(AdaptyUIPaywallView view) {
}

Restauration réussie

Si la restauration d’un achat réussit, cette méthode sera invoquée :

void paywallViewDidFinishRestore(AdaptyUIPaywallView view, AdaptyProfile profile) {
}

void paywallViewDidFinishRestore(AdaptyUIPaywallView view, AdaptyProfile profile) {
  // profile — AdaptyProfile:
  profile.accessLevels['premium']?.isActive;            // true
  profile.accessLevels['premium']?.expiresAt;           // DateTime(2027, 2, 15, 10, 30)
  profile.subscriptions['premium_monthly']?.isActive;   // true
  profile.subscriptions['premium_monthly']?.expiresAt;  // DateTime(2027, 2, 15, 10, 30)
}

Nous recommandons de fermer l’écran si l’utilisateur possède le accessLevel requis. Consultez le sujet Statut d’abonnement pour savoir comment le vérifier et le sujet Répondre aux actions de bouton pour savoir comment fermer un écran de paywall.

Restauration échouée

Si la restauration d’un achat échoue, cette méthode sera invoquée :

void paywallViewDidFailRestore(AdaptyUIPaywallView view, AdaptyError error) {
}

void paywallViewDidFailRestore(AdaptyUIPaywallView view, AdaptyError error) {
  // error — AdaptyError:
  error.code;    // AdaptyErrorCode.receiveRestoredTransactionsFailed (1011)
  error.message; // 'Error occurred in the process of restoring purchases.'
  error.detail;  // platform-specific underlying error, or null
}

Récupération des données et rendu

Erreurs de chargement des produits

Si vous ne passez pas le tableau de produits lors de l’initialisation, AdaptyUI récupérera les objets nécessaires depuis le serveur par lui-même. Si cette opération échoue, AdaptyUI signalera l’erreur en invoquant cette méthode :

void paywallViewDidFailLoadingProducts(AdaptyUIPaywallView view, AdaptyError error) {
}

void paywallViewDidFailLoadingProducts(AdaptyUIPaywallView view, AdaptyError error) {
  // error — AdaptyError:
  error.code;    // AdaptyErrorCode.productRequestFailed (1002)
  error.message; // 'Unable to fetch available In-App Purchase products at the moment.'
  error.detail;  // platform-specific underlying error, or null
}

Erreurs de rendu

Si une erreur survient pendant le rendu de l’interface, elle sera signalée en appelant cette méthode. Par défaut (depuis la v3.15.2), le paywall est automatiquement fermé lorsqu’une erreur de rendu se produit, mais vous pouvez modifier ce comportement si nécessaire.

void paywallViewDidFailRendering(AdaptyUIPaywallView view, AdaptyError error) {
  // Default behavior: view.dismiss()
  // Override with custom logic if needed, for example:
  // - Log the error
  // - Show an error message to the user
}

void paywallViewDidFailRendering(AdaptyUIPaywallView view, AdaptyError error) {
  // error — AdaptyError:
  error.code;    // AdaptyErrorCode.jsException (4105)
  error.message; // 'An exception was thrown from JS during AdaptyUI flow execution.'
  error.detail;  // platform-specific underlying error, or null

  // Default behavior: view.dismiss()
}

Dans une situation normale, de telles erreurs ne devraient pas se produire, donc si vous en rencontrez une, veuillez nous le signaler.