本指南介绍如何将 Adapty 集成到你的自定义付费墙中。你可以完全掌控付费墙的实现方式，同时由 Adapty SDK 负责获取产品、处理新购买以及恢复历史购买记录。本指南使用 Adapty Capacitor SDK v4 API——如果你使用的是 v3，请参阅迁移指南了解对应的方法名称。

开始之前

设置产品

要启用应用内购买，你需要了解以下三个核心概念：

• 产品 – 用户可以购买的任何内容（订阅、消耗型商品、永久授权）
• 付费墙 – 定义向用户提供哪些产品的配置。在 Adapty 中，付费墙是获取产品的唯一方式，但这种设计让你无需修改应用代码即可调整产品、价格和优惠。在 SDK v4 中，版位的付费墙变体由 flow 对象承载——你获取一个 flow 并从中查询产品。
• 版位 – 应用中展示付费墙的位置和时机（如 main、onboarding、settings）。你在看板中为版位配置付费墙，然后在代码中通过版位 ID 请求它们。这让 A/B 测试和向不同用户展示不同付费墙变得轻而易举。 请务必理解这些概念，即使你使用的是自定义付费墙。简单来说，它们只是你管理应用内销售产品的方式。

要实现自定义付费墙，你需要创建一个付费墙并将其添加到一个版位。这样即可获取你的产品。如需了解在看板中应如何操作，请参阅快速入门指南。

管理用户

您可以选择在后端使用身份验证，也可以不使用。

但是，Adapty SDK 对匿名用户和已识别用户的处理方式不同。请阅读用户身份识别快速入门指南，以了解具体细节并确保您正确处理用户信息。

第一步：获取产品

要为自定义付费墙获取产品，需要执行以下步骤：

1. 通过将版位 ID 传入 getFlow 方法来获取 flow 对象。
2. 使用 getPaywallProducts 方法获取该 flow 的产品数组。

async function loadPaywall() {
  try {
    const flow: AdaptyFlow = await adapty.getFlow({
      placementId: 'YOUR_PLACEMENT_ID'
    });

    const products: AdaptyPaywallProduct[] = await adapty.getPaywallProducts({
      flow
    });

    // Use products to build your custom paywall UI
  } catch (error) {
    // Handle the error
  }
}

步骤 2：处理购买

当用户在自定义付费墙中点击某个产品时，调用 makePurchase 方法并传入所选产品。该方法会处理购买流程并返回更新后的用户画像。

async function purchaseProduct(product: AdaptyPaywallProduct) {
  try {
    const result: AdaptyPurchaseResult = await adapty.makePurchase({ product });

    if (result.type === 'success') {
      // Purchase successful, profile updated
    } else if (result.type === 'user_cancelled') {
      // User canceled the purchase
    } else if (result.type === 'pending') {
      // Purchase is pending (e.g., user will pay offline with cash)
    }
  } catch (error) {
    // Handle the error
  }
}

步骤 3. 恢复购买

应用商店要求所有包含订阅的应用提供让用户恢复购买的方式。

当用户点击恢复按钮时，调用 restorePurchases 方法。这会将用户的购买记录与 Adapty 同步，并返回更新后的用户画像。

async function restorePurchases() {
  try {
    const profile: AdaptyProfile = await adapty.restorePurchases();
    // Restore successful, profile updated
  } catch (error) {
    // Handle the error
  }
}

步骤 4. 检查订阅状态

购买或恢复后，检查用户的访问等级，以决定是否显示付费墙或解锁付费功能。makePurchase 和 restorePurchases 方法已返回更新后的用户画像；如需在应用其他地方获取当前状态，请使用 getProfile 方法：

async function hasPremiumAccess(): Promise<boolean> {
  try {
    const profile = await adapty.getProfile();
    return profile.accessLevels?.['premium']?.isActive ?? false;
  } catch (error) {
    // Handle the error
  }
  return false;
}

如需了解更多检查和监控订阅状态的方式（包括实时更新监听），请参阅检查订阅状态。

后续步骤

您的付费墙已准备好在应用中展示。在 App Store 沙盒 或 Google Play Store 中测试您的购买流程，确保能从付费墙完成测试购买。如需了解生产级实现示例，请参考我们示例应用中的 App.tsx，其中演示了包含完善错误处理、加载状态管理和全面 SDK 集成的购买流程实现。