处理 flow 与付费墙事件 - Capacitor

流程编辑工具构建的流程和付费墙无需额外代码即可完成购买和恢复购买。但它们会生成一些你的应用可以响应的事件，包括按钮点击（关闭按钮、URL、产品选择等）以及与流程中购买相关操作的通知。请参阅下文了解如何响应这些事件。

要在移动应用中控制或监听流程界面上发生的事件，请实现 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'

您可以只注册需要的事件处理程序，忽略不需要的。这样就不会创建多余的事件监听器。所有事件处理程序均为可选。

事件处理程序返回一个布尔值。如果返回 true，则认为展示流程已完成，流程屏幕随即关闭，并移除该视图的所有事件监听器。 某些事件处理器具有默认行为，您可以根据需要进行覆盖：

• onCloseButtonPress：当用户按下关闭按钮时，关闭流程。
• onUrlPress：通过 adapty.openWebUrl 在原生浏览器中打开被点击的 URL，遵循编辑工具中设置的 Open in 选项，并保持流程开启。
• onAndroidSystemBack：当用户按下 Back 按钮时，保持流程开启。返回 true 可关闭流程。
• onPurchaseCompleted：购买完成后保持流程开启。返回 true 可关闭流程。
• onRestoreCompleted：成功恢复购买后保持流程开启。返回 true 可关闭流程。
• onError：如果流程渲染失败，则关闭流程。

事件处理程序

view 参数

view 参数需要 Capacitor SDK 4.0.2-beta.1 或更高版本。在所有流程处理器中，只有 onAppeared 会接收视图本身的描述——一个包含以下字段的 FlowEventView 对象：

分析事件

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

每当用户打开某个流程中的屏幕时，该流程就会上报 flow_screen_showed 事件。Adapty 会在其自身的流程分析中统计这些事件，同时也会将其传递给您的应用，以便您在自己的分析系统中构建相同的漏斗。

此事件的 isBackendEvent 和 isCustomerEvent 均为 true：Adapty 会持续统计该事件，同时您的应用也会收到它。

请参阅跟踪流程屏幕浏览，了解如何处理这些事件。

在观察者模式下处理购买

如果你以观察者模式（observerMode: true）激活了 SDK 并展示 Adapty 渲染的流程，SDK 不会为你执行购买操作。当用户点击购买或恢复按钮时，SDK 会调用 onObserverPurchaseInitiated 或 onObserverRestoreInitiated，你可以用自己的代码来处理购买或恢复逻辑。完整设置请参阅在观察者模式下展示流程。

通过付费墙编辑工具配置的付费墙无需额外代码即可完成购买和恢复购买操作。但它们会生成一些事件，供您的应用响应。这些事件包括按钮点击（关闭按钮、URL、产品选择等），以及付费墙上与购买相关操作的通知。请参阅下文了解如何响应这些事件。

如需在移动应用中控制或监控付费墙界面上发生的流程，请实现 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"
    }
  }
}

您可以只注册需要的事件处理器，无需注册的可以忽略。这样就不会创建多余的事件监听器。所有事件处理器均为可选。

事件处理器返回一个布尔值。若返回 true，则视为展示流程已完成，付费墙页面将关闭，该视图的所有事件监听器也会随之移除。 某些事件处理程序具有默认行为，您可以根据需要进行覆盖：

• onCloseButtonPress：点击关闭按钮时关闭付费墙。
• onAndroidSystemBack：按下 Back 按钮时关闭付费墙。
• onRestoreCompleted：恢复成功后关闭付费墙。
• onPurchaseCompleted：除非用户取消，否则关闭付费墙。
• onRenderingFailed：付费墙渲染失败时关闭付费墙。
• onUrlPress：在系统浏览器中打开 URL，并保持付费墙开启。

事件处理器