将 Adapty 流程与您自己的支付系统配合使用

您无需将支付逻辑迁移到 Adapty 即可使用其流程。在 Observer 模式下,所有购买操作仍由您的代码完成,而 Adapty 负责渲染付费墙或用户引导、决定用户看到的内容、进行 A/B 测试并报告结果。

本指南介绍哪些内容会发生变化、哪些不会,以及配置所需的步骤。

Tip

刚接触流程?流程与付费墙编辑工具 介绍了在接入这些内容之前你可以搭建哪些内容。

哪些由你负责,哪些由 Adapty 接管

你的代码负责:

  • 发起购买调用
  • 完成并确认交易
  • 授予和撤销访问权限
  • 续订和账单重试

Adapty 接管:

你的计费逻辑不会有任何改变。Adapty 负责渲染流程,并将购买点击事件交还给你的代码来完成扣费。

在 Adapty 中创建产品

如果你的流程中没有任何屏幕展示价格或触发购买操作,可以跳过本节——纯用户引导屏幕的流程无需在 Adapty 中创建产品。

一旦某个屏幕需要展示产品,请在 Adapty 中为每个订阅或一次性购买创建对应的产品。流程会从产品中读取卡片上显示的价格,因此卡片始终展示当前商店的实时价格,你也可以对该价格进行 A/B 测试,Adapty 还会在分析报告中按产品对收入进行分类统计。

Adapty 中的产品指向您已在商店中销售的商品,因此创建产品不会触发任何扣费操作:每笔收费仍由您的代码发起。每个产品需要关联一个访问等级;在 Observer 模式下,Adapty 不会授予该访问等级——访问权限仍由您的代码控制——但产品必须指定一个。

Adapty CLI 可以让您无需打开看板即可创建产品。安装 CLI(需要 Node.js 18 或更高版本)并登录:

npm install -g adapty
adapty auth login

获取您的应用 ID,以及需要关联的访问等级——每个新应用默认会创建一个 premium 访问等级:

adapty apps list
adapty access-levels list --app <app-id>

然后为你销售的每个应用内商品创建一个 Adapty 产品,使用来自 App Store Connect 和 Google Play Console 的产品 ID:

adapty products create --app <app-id> --title "Monthly" --access-level-id <access-level-id> --period monthly --ios-product-id com.example.monthly --android-product-id com.example.monthly --android-base-plan-id monthly

对于一次性购买,请传入 --period lifetime;如果是在网页端销售的商品,请同时传入 --stripe-product-id 与 --stripe-price-id(或对应的 Paddle 参数)。products create 列出了所有可用标志。商店产品 ID 创建后无法修改,因此如需将产品指向不同的商店产品,必须重新创建一个新产品。

Warning

产品元素未分配任何内容会阻止保存和发布,因此你会在编辑工具中发现这个问题。而购买操作未设置产品时可以正常保存,但在设备上会失效——按钮点击后没有任何反应。请为每个购买操作设置产品。

或者跳过产品,将价格写成静态文本

没有产品元素的流程可以保存和发布,因此你可以直接在文本中输入价格,让自己的代码决定点击后购买什么。这样做的代价是:

  • 价格需要在两个地方维护——应用商店和流程文本——一旦修改其中一处就会出现不一致。
  • 无法进行价格 A/B 测试,而这恰恰是流程的核心用途之一。
  • 数据图表和集成对收入的分组不够清晰,因为 Adapty 只能从你上报的交易中获取产品信息。
  • 你的代码需要将每个点击元素映射到对应的产品,而不是直接从流程中接收产品信息。

配置步骤

  1. 以 Observer 模式激活 SDK。 配置 SDK 时开启 observerMode:iOS、Android、React Native、Flutter、Unity、Kotlin Multiplatform、Capacitor。
  2. 在 Adapty 中创建产品(除非整个流程中没有任何价格展示)。每个产品执行一条 CLI 命令——详见在 Adapty 中创建产品。
  3. 构建流程。 参考流程与付费墙编辑工具了解各屏幕设置,参考设置购买为付费墙屏幕配置产品,并创建版位决定流程在应用中的展示位置。
  4. 在自己的代码中展示流程并完成购买。 Adapty 会将购买点击事件交由你注册的处理函数来处理。
  5. 上报交易,并附上所购产品的付费墙实验变体 ID,确保购买数据能归因到对应的付费墙,并正确反映在分析中。

第 4 步和第 5 步因平台而异。在所有代码片段中,flow 是你为版位获取的 AdaptyFlow,product 是用户点击的 AdaptyPaywallProduct,myPurchaseApi 或 yourBillingClient 代表你已有的购买代码。

观察者模式的限制

  • Adapty 不授予访问权限:它不会响应购买事件来开放或限制付费功能,也不处理续订或账单重试。访问等级完全由你自己的代码管理。
  • 你的代码负责完成自己的交易:Adapty 不会完成或确认你的代码发起的购买,因此关闭每笔交易仍然是你的责任。
  • 上报是必须的:你在上报时传入的 variationId 是连接购买行为与产生该购买的流程的唯一纽带。每笔交易都必须上报,否则你的流程数据指标和 A/B 测试结果将出现偏差。

如果你已在使用其他第三方服务

Observer 模式只要求你的代码完成购买操作——而不限定调用哪家 SDK。无论底层是 RevenueCat、Superwall、Qonversion,还是你自己的 StoreKit 或 Billing Library 代码,流程的运行方式都完全一致。

在上线前需要做三个决策:

  • 一个系统完成每笔交易:两个 SDK 同时完成同一笔购买是这里最常见的问题。
  • 一个系统管理访问等级:Adapty 在 Observer 模式下不授予任何权限,因此保持访问等级不变。
  • 每笔购买只上报一次:从两个地方上报同一笔交易会导致分析数据失真。

如果要完全迁移,不再使用其他供应商,请参阅从 RevenueCat 迁移或从 Superwall 迁移。

让 Adapty 代替您完成购买

Tip

您的应用通过 Adapty 完成购买,代码层面是标准的 Adapty 集成。请参阅快速入门或从 RevenueCat 迁移,或者将其交给 SDK 集成技能处理。

观察者模式是最快的接入方式。如果你希望保留 RevenueCat 的分析功能,同时避开观察者模式的限制,可以反转两者的角色:Adapty 以完整模式运行并完成每笔购买,而 RevenueCat 以其自身的观察者模式运行,记录 Adapty 发起的购买。

这样,Adapty 就能知道每笔费用是由哪个流程、版位和 A/B 测试变体产生的,并负责授予访问等级以及处理续订、账单重试和退款。

在 RevenueCat 一侧,配置其 SDK 时将 purchasesAreCompletedBy 设置为你的应用——iOS 上设为 .myApp,Android 上设为 MY_APP。RevenueCat 的 Using the SDK with your own IAP code 中包含各平台的配置说明、iOS 所需的 StoreKit 版本,以及用于同步用户已有购买记录的 syncPurchases() 调用。请确保两个 SDK 使用相同的用户 ID——Adapty 的 customer user ID 与 RevenueCat 的 appUserID 保持一致,否则两个看板描述的将是不同的用户。

Warning

此安排将终止以 RevenueCat 权益作为可信来源的机制,转由 Adapty 访问等级承担该角色。RevenueCat 仍会继续监听,其看板也会继续上报数据,但它现在是通过间接方式获知每笔购买,且受限于其官方文档所列的覆盖范围。任何当前读取 RevenueCat 权益的地方——无论是你的应用、后端、Web 端还是桌面端——都需要切换到 Adapty,或读取一份数据副本。在上线之前务必明确这一点。其他内容无需变动:RevenueCat 账户、其历史记录以及相关集成均保持不变。