---
title: "React Native - 处理付费墙事件"
description: "使用 Adapty SDK 在 React Native 中处理订阅事件。"
---

:::important
本指南涵盖购买、恢复、产品选择和付费墙渲染的事件处理。您还必须实现按钮处理（关闭付费墙、打开链接等）。详情请参阅我们的[按钮操作处理指南](react-native-handle-paywall-actions)。
:::

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

:::warning
本指南仅适用于**新版付费墙编辑工具付费墙**，需要 Adapty SDK v3.0 或更高版本。如需了解在 Adapty SDK v2 中展示使用旧版付费墙编辑工具设计的付费墙，请参阅[处理使用旧版付费墙编辑工具设计的付费墙事件](react-native-handling-events-legacy)。
:::

要控制或监控移动应用中付费墙屏幕上发生的流程，请实现事件处理程序：

<Tabs groupId="version" queryString>
<TabItem value="new" label="SDK version 3.14 or later" default>

<Tabs groupId="presentation-method" queryString>
<TabItem value="platform" label="React component" default>

对于 React 组件，您可以通过 `AdaptyPaywallView` 组件中的各个事件处理程序 prop 来处理事件：

```typescript showLineNumbers title="React Native (TSX)"

function MyPaywall({ paywall }) {
  const onCloseButtonPress = useCallback<EventHandlers['onCloseButtonPress']>(() => {}, []);
  const onProductSelected = useCallback<EventHandlers['onProductSelected']>((productId) => {}, []);
  const onPurchaseStarted = useCallback<EventHandlers['onPurchaseStarted']>((product) => {}, []);
  const onPurchaseCompleted = useCallback<EventHandlers['onPurchaseCompleted']>((purchaseResult, product) => {}, []);
  const onPurchaseFailed = useCallback<EventHandlers['onPurchaseFailed']>((error, product) => {}, []);
  const onRestoreStarted = useCallback<EventHandlers['onRestoreStarted']>(() => {}, []);
  const onRestoreCompleted = useCallback<EventHandlers['onRestoreCompleted']>((profile) => {}, []);
  const onRestoreFailed = useCallback<EventHandlers['onRestoreFailed']>((error) => {}, []);
  const onPaywallShown = useCallback<EventHandlers['onPaywallShown']>(() => {}, []);
  const onRenderingFailed = useCallback<EventHandlers['onRenderingFailed']>((error) => {}, []);
  const onLoadingProductsFailed = useCallback<EventHandlers['onLoadingProductsFailed']>((error) => {}, []);
  const onUrlPress = useCallback<EventHandlers['onUrlPress']>((url) => {
    Linking.openURL(url);
  }, []);
  const onCustomAction = useCallback<EventHandlers['onCustomAction']>((actionId) => {}, []);
  const onWebPaymentNavigationFinished = useCallback<EventHandlers['onWebPaymentNavigationFinished']>(() => {}, []);

  return (
    <AdaptyPaywallView
      paywall={paywall}
      style={styles.container}
      onCloseButtonPress={onCloseButtonPress}
      onProductSelected={onProductSelected}
      onPurchaseStarted={onPurchaseStarted}
      onPurchaseCompleted={onPurchaseCompleted}
      onPurchaseFailed={onPurchaseFailed}
      onRestoreStarted={onRestoreStarted}
      onRestoreCompleted={onRestoreCompleted}
      onRestoreFailed={onRestoreFailed}
      onPaywallShown={onPaywallShown}
      onRenderingFailed={onRenderingFailed}
      onLoadingProductsFailed={onLoadingProductsFailed}
      onUrlPress={onUrlPress}
      onCustomAction={onCustomAction}
      onWebPaymentNavigationFinished={onWebPaymentNavigationFinished}
    />
  );
}
```

</TabItem>
<TabItem value="standalone" label="Modal presentation">

对于模态展示，请实现事件处理程序方法。

:::important
多次调用 `setEventHandlers` 将覆盖您提供的处理程序，替换这些特定事件的默认处理程序和之前设置的处理程序。
:::

```javascript showLineNumbers title="React Native (TSX)"

const view = await createPaywallView(paywall);

const unsubscribe = view.setEventHandlers({
  onCloseButtonPress() {
    return true;
  },
  onAndroidSystemBack() {
    return true;
  },
  onPurchaseCompleted(purchaseResult, product) {
    return purchaseResult.type !== 'user_cancelled';
  },
  onPurchaseStarted(product) { /***/},
  onPurchaseFailed(error) { /***/ },
  onRestoreCompleted(profile) { /***/ },
  onRestoreFailed(error, product) { /***/ },
  onProductSelected(productId) { /***/},
  onRenderingFailed(error) { /***/ },
  onLoadingProductsFailed(error) { /***/ },
  onUrlPress(url) {
      Linking.openURL(url);
      return false; // Keep paywall open
  },
  onPaywallShown() { /***/ },
  onPaywallClosed() { /***/ },
  onWebPaymentNavigationFinished() { /***/ },  
});
```

</TabItem>
</Tabs>

</TabItem>

<TabItem value="old" label="SDK version < 3.14" default>

对于 SDK 版本 < 3.14，仅支持模态展示：

```javascript showLineNumbers title="React Native (TSX)"

const view = await createPaywallView(paywall);

const unsubscribe = view.registerEventHandlers({
  onCloseButtonPress() {
    return true;
  },
  onAndroidSystemBack() {
    return true;
  },
  onPurchaseCompleted(purchaseResult, product) {
    return purchaseResult.type !== 'user_cancelled';
  },
  onPurchaseStarted(product) { /***/},
  onPurchaseFailed(error, product) { /***/ },
  onRestoreCompleted(profile) { /***/ },
  onRestoreFailed(error) { /***/ },
  onProductSelected(productId) { /***/},
  onRenderingFailed(error) { /***/ },
  onLoadingProductsFailed(error) { /***/ },
  onUrlPress(url) {
      Linking.openURL(url);
      return false; // Keep paywall open
  },
  onPaywallShown() { /***/ },
  onPaywallClosed() { /***/ },
  onWebPaymentNavigationFinished() { /***/ },
});
```

</TabItem>
</Tabs>

<Details>
<summary>事件示例（点击展开）</summary>

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

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

// 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"
    },
    "product": {
        "vendorProductId": "premium_monthly",
            "localizedTitle": "Premium Monthly",
            "localizedDescription": "Premium subscription for 1 month",
            "localizedPrice": "$9.99",
            "price": 9.99,
            "currencyCode": "USD"
    }
  }
}

// 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"
    }
  }
}

// onPaywallShown
{
  "event": "paywall_shown"
}

// onPaywallClosed
{
  "event": "paywall_closed"
}

// onWebPaymentNavigationFinished
{
  "event": "web_payment_navigation_finished"
}
```
</Details>

您可以注册所需的事件处理程序，忽略不需要的事件处理程序。在这种情况下，不会创建未使用的事件监听器。没有必须实现的事件处理程序。

事件处理程序返回一个布尔值。如果返回 `true`，则认为展示过程已完成，付费墙屏幕将关闭，并移除该视图的事件监听器。

某些事件处理程序具有默认行为，您可以根据需要覆盖：
- `onCloseButtonPress`：按下关闭按钮时关闭付费墙。
- `onUrlPress`：打开点击的 URL 并保持付费墙开启。
- `onAndroidSystemBack`（仅适用于模态展示）：按下 **Back** 按钮时关闭付费墙。
- `onRestoreCompleted`：恢复成功后关闭付费墙。
- `onPurchaseCompleted`：除非用户取消，否则关闭付费墙。
- `onRenderingFailed`：付费墙渲染失败时关闭付费墙。

### 事件处理程序 \{#event-handlers\}

| 事件处理程序                         | 描述                                                                                                                                                                                                                                                                                              |
|:-------------------------------------|:--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| **onCustomAction**                   | 当用户执行自定义操作时触发，例如点击[自定义按钮](paywall-buttons)。                                                                                                                                                                                                                               |
| **onUrlPress**                       | 当用户点击付费墙中的 URL 时触发。                                                                                                                                                                                                                                                                 |
| **onAndroidSystemBack**              | 仅限模态展示：当用户点击 Android 系统 **Back** 按钮时触发。                                                                                                                                                                                                                                       |
| **onCloseButtonPress**               | 当关闭按钮可见且用户点击它时触发。建议在此处理程序中关闭付费墙屏幕。                                                                                                                                                                                                                              |
| **onPurchaseCompleted**              | 当购买完成时触发，无论是成功、用户取消还是待审批。成功购买时，会提供更新后的 `AdaptyProfile`。用户取消和待处理付款（例如，需要家长批准）会触发此事件，而不是 `onPurchaseFailed`。                                                                                                                   |
| **onPurchaseStarted**                | 当用户点击"购买"操作按钮以开始购买流程时触发。                                                                                                                                                                                                                                                    |
| **onPurchaseFailed**                 | 当购买因错误（例如，付款限制、无效产品、网络故障、交易验证失败）而失败时触发。用户取消或待处理付款不会触发此事件，它们会触发 `onPurchaseCompleted`。                                                                                                                                              |
| **onRestoreStarted**                 | 当用户开始购买恢复流程时触发。                                                                                                                                                                                                                                                                    |
| **onRestoreCompleted**               | 当购买恢复成功并提供更新后的 `AdaptyProfile` 时触发。如果用户拥有所需的 `accessLevel`，建议关闭屏幕。请参阅[订阅状态](react-native-listen-subscription-changes)主题了解如何检查。                                                                                                                  |
| **onRestoreFailed**                  | 当恢复流程失败并提供 `AdaptyError` 时触发。                                                                                                                                                                                                                                                       |
| **onProductSelected**                | 当付费墙视图中的任何产品被选中时触发，允许您监控用户在购买前选择的内容。                                                                                                                                                                                                                          |
| **onRenderingFailed**                | 当视图渲染过程中发生错误并提供 `AdaptyError` 时触发。此类错误不应发生，如果遇到，请告知我们。                                                                                                                                                                                                     |
| **onLoadingProductsFailed**          | 当产品加载失败并提供 `AdaptyError` 时触发。如果您在创建视图时未设置 `prefetchProducts: true`，AdaptyUI 将自行从服务器检索必要的对象。                                                                                                                                                              |
| **onPaywallShown**                   | 当付费墙显示给用户时触发。在 iOS 上，当用户点击付费墙内的[网页付费墙按钮](web-paywall#step-2a-add-a-web-purchase-button)并在应用内浏览器中打开网页付费墙时也会触发。                                                                                                                              |
| **onPaywallClosed**                  | 仅限模态展示：当付费墙被用户关闭时触发。在 iOS 上，当从付费墙在应用内浏览器中打开的[网页付费墙](web-paywall#step-2a-add-a-web-purchase-button)从屏幕消失时也会触发。                                                                                                                              |
| **onWebPaymentNavigationFinished**   | 尝试打开[网页付费墙](web-paywall)进行购买后触发，无论成功还是失败。                                                                                                                                                                                                                               |