Adapty 通过追踪通过 Stripe 完成的网页支付和订阅，支持 web2app 订阅流程。 此集成涵盖通过 Web 发起的购买（Stripe Checkout、托管支付页面或自定义 Web 流程），并将其与移动应用的访问权限和数据分析同步。

适用于以下场景：

• 自动为在 Web 端完成购买、随后安装应用并登录账户的用户开放付费功能访问权限
• 将所有订阅数据分析集中在同一个 Adapty 看板中（包括同期群、趋势预测以及其他分析工具） 尽管网页购买在应用中越来越普及，但 Apple App Store 仅在美国允许针对数字商品使用有别于应用内购买的系统。请确保不要在应用内向其他国家的用户推广您的网页订阅，否则您的应用可能面临被拒或被封的风险。

以下步骤介绍了如何配置 Stripe 集成。

1. 将 Stripe 连接到 Adapty

此集成主要依赖 Adapty 通过 webhook 从 Stripe 拉取订阅数据。因此，您需要提供 API 密钥并在 Stripe 中使用 Adapty 的 webhook URL，将您的 Adapty 账户与 Stripe 账户连接起来。为了自动完成 webhook 配置，请在 Stripe 中安装 Adapty 应用：

0. 确定你要以测试模式还是正式模式接入 Stripe。如果初始是在测试模式下操作，后续还需要针对正式模式重复以下步骤。

1. 前往 Stripe 应用市场 安装 Adapty 应用。注意沙盒模式不支持安装应用，只能在正式模式或测试模式下进行安装。

2. 为应用授予所需权限，这将允许 Adapty 访问订阅数据和历史记录。然后点击 Continue to app settings 继续。

在权限弹窗底部，您可以选择以正式模式还是测试模式安装应用。

3. 在弹窗中生成一个新的受限密钥。您需要通过邮箱、Touch ID 或安全密钥验证身份。密钥生成后将无法再次查看，请务必将其安全保存在密码管理器或密钥存储库中。

4. 从弹出窗口中复制生成的密钥，然后前往 Adapty 的 App Settings → Stripe。根据您的模式将密钥粘贴到 Stripe App Restricted API Key 部分。请注意，测试模式和正式模式需要分别生成不同的密钥。

一切就绪！接下来，在 Stripe 上创建您的产品并将其添加到 Adapty。

已弃用的安装流程

1. 前往 Stripe 的 Developers → API Keys：

2. 点击 Secret key 标题旁的 Reveal live (test) key button，复制密钥后前往 Adapty 的 App Settings → Stripe，将密钥粘贴到此处：

3. 接下来，从 Adapty 同一页面底部复制 Webhook URL。前往 Stripe 中的 Developers → Webhooks，点击 Add endpoint 按钮：

4. 将 Adapty 中的 webhook URL 粘贴到 Endpoint URL 字段。然后在 webhook 的 Version 字段中选择 Latest API version，并勾选以下事件：

• charge.refunded
  • customer.subscription.created
  • customer.subscription.deleted
  • customer.subscription.paused
  • customer.subscription.resumed
  • customer.subscription.updated
  • invoice.created
  • invoice.updated
  • payment_intent.succeeded

5. 点击 “Add endpoint”，然后点击 “Signing secret” 下方的 “Reveal”。这是 Adapty 用于解码 webhook 数据的密钥，显示后请复制：

6. 最后，将此密钥粘贴到 Adapty 的 App Settings → Stripe 中的 “Stripe Webhook Secret” 字段：

2. 在 Stripe 上创建产品

前往 Stripe 的产品目录，创建您希望销售的产品及其定价方案。请注意，Stripe 支持为每个产品设置多个定价方案，这样您无需创建额外的产品，就能灵活地调整您的产品组合。

3. 将 Stripe 产品添加到 Adapty

我们对 Stripe 的处理方式与 App Store 和 Google Play 相同：它只是您销售数字产品的另一个渠道。因此配置方式也类似：只需将 Stripe 产品（即其 product_id 和 price_id）添加到 Adapty 的 Products 部分即可：

在 Stripe 中，产品 ID 格式为 prod_...，价格 ID 格式为 price_...。打开 Stripe 产品目录中的任意产品，即可轻松找到对应的 ID：

添加完所有必要产品后，下一步是告知 Stripe 是哪位用户正在进行购买，以便 Adapty 能够识别该购买信息！

4. 使用用户 ID 丰富网页购买信息

Adapty 依赖来自 Stripe 的 Webhook 作为唯一信息来源，为用户提供和更新访问等级。但在使用 Stripe 进行此集成时，你需要从自己这端提供额外信息，才能让集成正常运作。

为了让访问等级在各平台（网页或移动端）之间保持一致，你需要确保存在一个统一的用户 ID，Adapty 可以通过 Webhook 识别该 ID。这个 ID 可以是用户的电子邮件、手机号码，或你所使用的授权系统中的任何其他 ID。 确定您希望用于识别用户的 ID。然后，找到代码中通过 Stripe 初始化支付的部分，将该用户 ID 以 customer_user_id 为键添加到 Stripe Subscription（sub_...）或 Checkout Session 对象（ses_...）的 metadata 中，示例如下：

{'customer_user_id': "YOUR_USER_ID"}

这一处简单的添加是您在代码中唯一需要做的事情。完成之后，Adapty 将自动解析从 Stripe 收到的所有 webhook，提取 metadata 并将订阅正确关联到您的客户。

5. 在移动端为用户开放访问权限

为确保从网页端跳转过来的移动端用户能够访问付费功能，只需在调用 Adapty.activate() 或 Adapty.identify() 时，传入与上一步相同的 customer_user_id（详情请参阅 用户识别 iOS、Android、React Native、Flutter 和 Unity ）。

6. 测试集成

请确保你已在沙盒和生产环境中完成了上述所有步骤。在 Stripe 测试模式下进行的交易，在 Adapty 中将被视为沙盒交易。

用户画像创建行为

Adapty 必须将购买记录与用户画像关联，才能在移动端使用该购买。因此默认情况下，Adapty 会在收到 Stripe 的 webhook 时自动创建用户画像。你可以选择在 Adapty 中使用什么作为客户用户 ID：

1. 默认且推荐： 你在上方第 4 步的元数据中提供的 customer_user_id
2. Stripe Customer 对象中的 email（参见 Stripe 文档）
3. Stripe Session 对象中的 client_reference_id（参见 Stripe 文档）

你可以在 App Settings → Stripe 中配置要使用的 ID。

您还有第四个选项，即完全不创建用户画像，但由于上述在 Analytics 方面的限制，不推荐采用此方式。

当前限制

升级、降级与按比例计费

订阅变更（如升级或降级）可能会产生按比例计算的费用。Adapty 不会在收入计算中考虑这些费用。建议通过 Stripe 看板手动禁用这些选项。您也可以通过 Stripe API 将 proration_behaviour 属性值设置为 none 来禁用它们。

取消订阅

Stripe 有两种订阅取消选项：

1. 立即取消：订阅立即取消，可选是否按比例退款
2. 在周期结束时取消：订阅在当前计费周期结束时取消（类似于应用商店的应用内订阅）

Adapty 支持两种选项，但立即取消的收入计算将忽略按比例退款选项。

账单问题与宽限期

当客户遇到支付问题时，Adapty 将生成账单问题事件并撤销访问权限。我们目前暂不支持 Stripe 的宽限期——这将在未来版本中实现。

退款

Adapty 仅追踪全额退款。目前不支持按比例退款或部分退款。

交易 ID 唯一性

Adapty 使用 store_transaction_id 和 store_original_transaction_id 来匹配用户画像和交易记录，这两个字段在测试环境和生产环境中必须唯一。

为什么这很重要

如果同一个交易 ID 同时存在于两个环境中，Adapty 会将其视为同一笔交易，从而导致：

• 生产环境的购买记录继承测试环境的访问等级和产品 ID
• API 响应中返回错误的产品 ID 和环境信息
• 用户画像关联和订阅事件出现异常

如何确保唯一性

Stripe 发票 ID 在测试环境和正式环境之间可能会重复。为防止跨环境冲突，请选择以下方案之一

方案一：账户级编号加环境前缀

分别为每个环境配置前缀：

1. 在 Stripe 看板中，切换到测试模式。
2. 前往 Settings → Billing → Invoices。
3. 将 Invoice numbering 设置为 Sequentially across your account。
4. 将 Invoice prefix 设置为 TEST-（或其他专用于测试环境的前缀）。
5. 切换到正式模式，重复步骤 2-4，使用 LIVE-（或其他专用于正式环境的前缀）作为前缀。

方案二：按客户编号

在 Stripe settings -> Billing -> Invoices 标签页 中，将 Invoice numbering 设置为 Sequentially for each customer (customer-level)。

即使完成上述配置，如果你删除了某张发票，Stripe 可能会将该 ID 重新分配给同一客户的新发票。因此，请尽量避免删除发票。

充分利用你的 Stripe 数据

完成 Stripe 集成后，Adapty 即可立即提供数据洞察。为了最大化利用你的 Stripe 数据，你可以配置额外的 Adapty 集成来转发 Stripe 事件——将所有订阅分析数据汇集到单一的 Adapty 看板中。

请注意，variation_id 仅从 Stripe Subscription（sub_...）和 Checkout Session（ses_...）对象的元数据中读取：

{
  'customer_user_id': "YOUR_USER_ID",
  'variation_id': "YOUR_VARIATION_ID"
}

:::

可以使用以下集成来转发和分析 Stripe 事件：

• Amplitude
• Webhook
• Firebase
• Mixpanel
• Posthog

支持的 Stripe 事件

Adapty 支持以下 Stripe 事件：

• charge.refunded
• customer.subscription.created
• customer.subscription.deleted
• customer.subscription.paused
• customer.subscription.resumed
• customer.subscription.updated
• invoice.created
• invoice.updated
• payment_intent.succeeded