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

Les flows et les paywalls créés avec le Flow Builder n’ont pas besoin de code supplémentaire pour effectuer et restaurer des achats. En revanche, 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 dans le flow. Découvrez ci-dessous comment répondre à ces événements.

Pour contrôler ou surveiller les processus qui se déroulent sur l’écran du flow dans votre application mobile, implémentez la méthode view.setEventHandlers :

const view = await createFlowView(flow);

const unsubscribe = await view.setEventHandlers({
  onCloseButtonPress() {
    return true; // close the flow (default behavior)
  },
  onAndroidSystemBack() {
    return true; // close the flow; by default, it stays open
  },
  onPurchaseCompleted(purchaseResult, product) {
    return purchaseResult.type === 'success'; // close the flow on a successful purchase, keep it open for cancelled or pending purchases
  },
  onPurchaseStarted(product) { /***/ },
  onPurchaseFailed(error, product) { /***/ },
  onRestoreCompleted(profile) { /***/ },
  onRestoreFailed(error) { /***/ },
  onProductSelected(productId) { /***/ },
  onError(error) { /***/ },
  onLoadingProductsFailed(error) { /***/ },
  onUrlPress(url, openIn) {
    adapty.openWebUrl({ url, openIn }).catch(console.warn); // same as the SDK default
    return false; // keep the flow open
  },
  onAppeared(appearedView) { /***/ },
  onDisappeared() { /***/ },
  onWebPaymentNavigationFinished() { /***/ },
});

// onUrlPress
url;    // 'https://example.com/terms'
openIn; // 'browser_in_app' or 'browser_out_app'

// onCustomAction
actionId; // 'login'

// onProductSelected
productId; // 'premium_monthly'

// onAppeared
appearedView.id;          // '3f8a1c7e-9b24-4d51-8e30-6c5b2a9f1d47'
appearedView.placementId; // 'onboarding_paywall'
appearedView.variationId; // 'd21c4b6a-57e8-4f39-b0a2-8c7e13f5d94b'
appearedView.locale;      // 'es'

// onPurchaseStarted, onPurchaseCompleted, onPurchaseFailed
product.vendorProductId;        // 'premium_monthly'
product.localizedTitle;         // 'Premium Monthly'
product.localizedDescription;   // 'Premium subscription for 1 month'
product.price?.amount;          // 9.99
product.price?.currencyCode;    // 'USD'
product.price?.localizedString; // '$9.99'

// onPurchaseCompleted
purchaseResult.type; // 'success', 'pending', or 'user_cancelled'
if (purchaseResult.type === 'success') {
  purchaseResult.profile.accessLevels['premium']?.isActive; // true
}

// onRestoreCompleted
profile.accessLevels['premium']?.isActive; // true

// onPurchaseFailed, onRestoreFailed, onError, onLoadingProductsFailed
error.message; // 'Purchase failed due to insufficient funds'

Vous pouvez enregistrer uniquement les gestionnaires d’événements dont vous avez besoin, et ignorer ceux qui ne vous sont pas utiles. Ainsi, aucun écouteur d’événements inutile ne sera créé. Aucun gestionnaire d’événements n’est obligatoire.

Les gestionnaires d’événements retournent un booléen. Si true est retourné, le processus d’affichage est considéré comme terminé : l’écran du flow se ferme et les écouteurs d’événements associés à cette vue sont supprimés.

Certains gestionnaires d’événements ont un comportement par défaut que vous pouvez remplacer si nécessaire :

• onCloseButtonPress : ferme le flow lorsque le bouton de fermeture est pressé.
• onUrlPress : ouvre l’URL concernée dans le navigateur natif via adapty.openWebUrl, en respectant l’option Open in définie dans le builder, et laisse le flow ouvert.
• onAndroidSystemBack : laisse le flow ouvert lorsque le bouton Back est pressé. Retournez true pour le fermer.
• onPurchaseCompleted : laisse le flow ouvert après qu’un achat est finalisé. Retournez true pour le fermer.
• onRestoreCompleted : laisse le flow ouvert après une restauration réussie. Retournez true pour le fermer.
• onError : ferme le flow si son rendu échoue.

Gestionnaires d’événements

L’argument view

L’argument view nécessite Capacitor SDK 4.0.2-beta.1 ou une version ultérieure. Parmi tous les gestionnaires de flow, seul onAppeared reçoit une description de la vue elle-même — un objet FlowEventView avec ces champs :

Événements analytiques

view.setEventHandlers({
  onAnalytics(name, params) {
    return false; // keep the flow open
  },
});

Un flow envoie flow_screen_showed chaque fois qu’un utilisateur ouvre l’un de ses écrans. Adapty comptabilise ces événements dans ses propres analytics de flow et les transmet également à votre application, afin que vous puissiez reconstituer le même funnel dans vos propres analytics.

isBackendEvent et isCustomerEvent sont tous les deux true pour cet événement : Adapty continue de le comptabiliser, et votre application le reçoit également.

Consultez Suivre les vues d’écrans de flow pour savoir comment les utiliser.

Gérer les achats en mode observateur

Si vous avez activé le SDK en mode observateur (observerMode: true) et présentez un flow rendu par Adapty, le SDK n’effectue pas les achats à votre place. Quand un utilisateur appuie sur le bouton d’achat ou de restauration, le SDK appelle onObserverPurchaseInitiated ou onObserverRestoreInitiated à la place, afin que vous puissiez réaliser l’achat ou la restauration avec votre propre code. Consultez Présenter des flows en mode observateur pour la configuration complète.

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 des 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 ci-dessous comment réagir à ces événements.

Pour contrôler ou surveiller les processus qui se déroulent sur l’écran du paywall dans votre application mobile, implémentez la méthode view.setEventHandlers :

const view = await createPaywallView(paywall);

const unsubscribe = view.setEventHandlers({
  onCloseButtonPress() {
    console.log('User closed paywall');
    return true; // Allow the paywall to close
  },
  onAndroidSystemBack() {
    console.log('User pressed back button');
    return true; // Allow the paywall to close
  }, 
  onAppeared() {
    console.log('Paywall appeared');
    return false; // Don't close the paywall
  }, 
  onDisappeared() {
    console.log('Paywall disappeared');
  },
  onPurchaseCompleted(purchaseResult, product) {
    console.log('Purchase completed:', purchaseResult);
    return purchaseResult.type !== 'user_cancelled'; // Close if not cancelled
  },
  onPurchaseStarted(product) {
    console.log('Purchase started:', product);
    return false; // Don't close the paywall
  },
  onPurchaseFailed(error, product) {
    console.error('Purchase failed:', error);
    return false; // Don't close the paywall
  },
  onRestoreCompleted(profile) {
    console.log('Restore completed:', profile);
    return true; // Close the paywall after successful restore
  },
  onRestoreFailed(error) {
    console.error('Restore failed:', error);
    return false; // Don't close the paywall
  },
  onProductSelected(productId) {
    console.log('Product selected:', productId);
    return false; // Don't close the paywall
  },
  onRenderingFailed(error) {
    console.error('Rendering failed:', error);
    return false; // Don't close the paywall
  },
  onLoadingProductsFailed(error) {
    console.error('Loading products failed:', error);
    return false; // Don't close the paywall
  },
  onUrlPress(url) {
    window.open(url, '_blank');
    return false; // Don't close the paywall
  },
});

// onCloseButtonPress
{
  "event": "close_button_press"
}

// onAndroidSystemBack
{
  "event": "android_system_back"
}

// onAppeared
{
  "event": "paywall_shown"
}

// onDisappeared
{
  "event": "paywall_closed"
}

// onUrlPress
{
  "event": "url_press",
  "url": "https://example.com/terms"
}

// onCustomAction
{
  "event": "custom_action",
  "actionId": "login"
}

// onProductSelected
{
  "event": "product_selected",
  "productId": "premium_monthly"
}

// onPurchaseStarted
{
  "event": "purchase_started",
  "product": {
    "vendorProductId": "premium_monthly",
    "localizedTitle": "Premium Monthly",
    "localizedDescription": "Premium subscription for 1 month",
    "localizedPrice": "$9.99",
    "price": 9.99,
    "currencyCode": "USD"
  }
}

// onPurchaseCompleted - Success
{
  "event": "purchase_completed",
  "purchaseResult": {
    "type": "success",
    "profile": {
      "accessLevels": {
        "premium": {
          "id": "premium",
          "isActive": true,
          "expiresAt": "2024-02-15T10:30:00Z"
        }
      }
    }
  },
  "product": {
    "vendorProductId": "premium_monthly",
    "localizedTitle": "Premium Monthly",
    "localizedDescription": "Premium subscription for 1 month",
    "localizedPrice": "$9.99",
    "price": 9.99,
    "currencyCode": "USD"
  }
}

// onPurchaseCompleted - Cancelled
{
  "event": "purchase_completed",
  "purchaseResult": {
    "type": "user_cancelled"
  },
  "product": {
    "vendorProductId": "premium_monthly",
    "localizedTitle": "Premium Monthly",
    "localizedDescription": "Premium subscription for 1 month",
    "localizedPrice": "$9.99",
    "price": 9.99,
    "currencyCode": "USD"
  }
}

// onPurchaseFailed
{
  "event": "purchase_failed",
  "error": {
    "code": "purchase_failed",
    "message": "Purchase failed due to insufficient funds",
    "details": {
      "underlyingError": "Insufficient funds in account"
    }
  }
}

// onRestoreCompleted
{
  "event": "restore_completed",
  "profile": {
    "accessLevels": {
      "premium": {
        "id": "premium",
        "isActive": true,
        "expiresAt": "2024-02-15T10:30:00Z"
      }
    },
    "subscriptions": [
      {
        "vendorProductId": "premium_monthly",
        "isActive": true,
        "expiresAt": "2024-02-15T10:30:00Z"
      }
    ]
  }
}

// onRestoreFailed
{
  "event": "restore_failed",
  "error": {
    "code": "restore_failed",
    "message": "Purchase restoration failed",
    "details": {
      "underlyingError": "No previous purchases found"
    }
  }
}

// onRenderingFailed
{
  "event": "rendering_failed",
  "error": {
    "code": "rendering_failed",
    "message": "Failed to render paywall interface",
    "details": {
      "underlyingError": "Invalid paywall configuration"
    }
  }
}

// onLoadingProductsFailed
{
  "event": "loading_products_failed",
  "error": {
    "code": "products_loading_failed",
    "message": "Failed to load products from the server",
    "details": {
      "underlyingError": "Network timeout"
    }
  }
}

Vous pouvez enregistrer uniquement les gestionnaires d’événements dont vous avez besoin, et ignorer ceux qui ne vous sont pas utiles. Les écouteurs d’événements inutilisés ne seront alors pas créés. Aucun gestionnaire d’événements n’est obligatoire.

Les gestionnaires d’événements renvoient un booléen. Si true est renvoyé, le processus d’affichage est considéré comme terminé : l’écran du paywall se ferme et les écouteurs d’événements associés à cette vue sont supprimés.

Certains gestionnaires d’événements ont un comportement par défaut que vous pouvez remplacer si nécessaire :

• onCloseButtonPress : ferme le paywall lorsque le bouton de fermeture est pressé.
• onAndroidSystemBack : ferme le paywall lorsque le bouton Back est pressé.
• onRestoreCompleted : ferme le paywall après une restauration réussie.
• onPurchaseCompleted : ferme le paywall sauf si l’utilisateur a annulé.
• onRenderingFailed : ferme le paywall en cas d’échec de son rendu.
• onUrlPress : ouvre les URLs dans le navigateur système et maintient le paywall ouvert.

Gestionnaires d’événements