与 Stripe 的初始集成
Adapty 通过追踪通过 Stripe 完成的网页支付和订阅，支持 web2app 订阅流程。
该集成涵盖网页端发起的购买（Stripe Checkout、托管支付页面或自定义网页流程），并将其与移动应用访问权限及分析数据同步。
以下场景中该集成非常有用：
- 自动为在网页端购买、随后安装应用并登录账户的用户提供付费功能访问权限
- 在单一 Adapty 看板中汇总所有订阅分析数据（包括同期群、趋势预测及其他分析工具）
尽管网页端购买对于应用程序越来越普遍，但 Apple App Store 仅允许在美国对数字商品使用不同于应用内购买的系统。请确保不要在其他国家/地区的应用内宣传您的网页订阅，否则您的应用可能会被拒绝或封禁。
以下步骤概述了如何配置 Stripe 集成。
本集成专注于追踪和同步 Stripe 网页端购买。如果您需要将用户从应用引导至网页结账页面，请参阅 Web 付费墙。
1. 将 Stripe 连接到 Adapty
该集成主要依赖 Adapty 通过 webhook 从 Stripe 拉取订阅数据。因此，您需要通过提供 API 密钥并在 Stripe 中使用 Adapty 的 webhook URL，将您的 Adapty 账户连接到 Stripe 账户。为了自动完成 webhook 配置，请在 Stripe 中安装 Adapty 应用：
以下步骤对 Stripe 的生产模式和测试模式是相同的，但每种模式需要使用不同的 API 密钥。
-
确定您是以测试模式还是正式模式连接 Stripe。如果您最初在测试模式下执行此操作，则需要再次为正式模式重复以下步骤。
-
前往 Stripe App Marketplace 并安装 Adapty 应用。请注意，沙盒模式不支持安装应用，您只能在生产模式或测试模式下执行此操作。
- 授予应用所需权限。这将允许 Adapty 访问订阅数据和历史记录。然后，点击 Continue to app settings 继续。
在权限弹窗底部，您可以选择以正式模式还是测试模式安装应用。
- 在弹窗中，生成一个新的受限密钥。您需要通过电子邮件、Touch ID 或安全密钥验证身份。密钥生成后将无法再次查看，请将其安全存储在密码管理器或密钥存储库中。
- 从弹窗中复制生成的密钥，然后前往 Adapty 的 App Settings → Stripe。根据您的模式，将密钥粘贴到 Stripe App Restricted API Key 部分。请注意，测试模式和正式模式必须生成不同的密钥。
全部完成！接下来，在 Stripe 上创建您的产品并将其添加到 Adapty。
已弃用的安装流程
- 在 Stripe 中前往 Developers → API Keys：
- 点击 Secret key 标题旁边的 Reveal live (test) key button，复制后前往 Adapty 的 App Settings → Stripe，将密钥粘贴到此处：
- 接下来，从 Adapty 同一页面底部复制 Webhook URL。在 Stripe 中前往 Developers → Webhooks，点击 Add endpoint 按钮：
-
将 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
- 点击”Add endpoint”，然后点击”Signing secret”下方的”Reveal”。这是用于在 Adapty 端解码 webhook 数据的密钥，显示后请复制：
- 最后，将此密钥粘贴到 Adapty 的 App Settings → Stripe 中的”Stripe Webhook Secret”字段：
2. 在 Stripe 上创建产品
如果您在测试模式下进行此配置，请确保在继续此步骤之前将 Stripe 切换到测试模式。
前往 Stripe 的产品目录，创建您希望销售的产品及其定价方案。请注意，Stripe 允许每个产品拥有多个定价方案，这有助于在无需创建额外产品的情况下灵活定制您的产品组合。
目前 Adapty 仅支持固定费率（$9.99/月）或套餐定价（$9.99/10 个单位），因为这些方式与应用商店的行为类似。阶梯定价、基于用量的费用和客户自定价选项暂不支持。
3. 将 Stripe 产品添加到 Adapty
产品是必填项！请务必在 Adapty 看板中创建您的 Stripe 产品。Adapty 仅追踪与这些产品关联的交易事件，请勿跳过此步骤——否则将无法创建交易事件。
我们以与 App Store 和 Google Play 相同的方式处理 Stripe：它只是您销售数字产品的另一个商店。因此配置方式类似：只需将 Stripe 产品（即其 product_id 和 price_id）添加到 Adapty 的产品部分：
Stripe 中的产品 ID 格式为 prod_...，价格 ID 格式为 price_...。在 Stripe 的产品目录中打开任意产品即可轻松找到这些信息：
添加完所有必要产品后，下一步是让 Stripe 知道是哪位用户在进行购买，以便 Adapty 能够正确识别！
4. 在网页购买中附加您的用户 ID
Adapty 依赖来自 Stripe 的 webhook 作为唯一信息来源，为用户提供和更新访问等级。但您必须在使用 Stripe 时从您的端提供额外信息，才能使该集成正常工作。
为确保跨平台（网页或移动端）访问等级一致，您需要确保有一个统一的用户 ID，Adapty 可以通过 webhook 识别该 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，并将订阅正确关联到您的客户。
用户 ID 是必填项
否则，我们无法匹配该用户并在移动端为其提供访问等级。
如果您没有在 metadata 中提供 customer_user_id，您可以选择让 Adapty 在其他位置查找 customer_user_id：可以是 Stripe 的 Customer 对象中的 email，或 Stripe 的 Session 中的 client_reference_id。
了解更多关于配置用户画像创建行为的信息，请参阅下方说明。
Stripe 中的 Customer 也是必填项
如果您使用 Checkout Sessions，请通过将 customer_creation 设置为 always 来确保创建 Stripe Customer。
5. 为移动端用户提供访问权限
为确保来自网页端的移动用户能够访问付费功能，只需使用与上一步骤中相同的 customer_user_id 调用 Adapty.activate() 或 Adapty.identify()（详情请参阅 识别用户 iOS、Android、React Native、Flutter 和 Unity ）。
6. 测试您的集成
请确保您已同时为沙盒环境和生产环境完成上述步骤。从 Stripe 测试模式发起的交易在 Adapty 中将被视为沙盒交易。
大功告成！
您的用户现在可以在网页端完成购买，并在您的应用中访问付费功能。您还可以在单一位置查看所有订阅分析数据。
用户画像创建行为
Adapty 必须将购买关联到客户用户画像，以便在移动端可用——因此默认情况下，它会在收到 Stripe 的 webhook 时创建用户画像。您可以选择在 Adapty 中用作客户用户 ID 的内容：
- 默认且推荐： 您在上述第 4 步的 metadata 中提供的
customer_user_id - Stripe 的 Customer 对象中的
email（参见 Stripe 文档） - Stripe 的 Session 对象中的
client_reference_id（参见 Stripe 文档）
您可以在 App Settings → Stripe 中配置您希望使用的 ID。
注意： 如果来自 Stripe 的特定交易不包含指定的 ID，我们将不会创建用户画像。该交易将保持匿名状态，直到被某个用户画像接收（例如，如果您之后使用 S2S validate 并手动告知我们此交易）。
该交易将显示在分析数据中，但不会出现在依赖用户画像计数的部分（LTV、同期群、转化率等），您也无法在事件流中查看它。
您还有第四个选项，即完全不创建用户画像，但由于上述分析数据的限制，不建议这样做。
当前限制
升级、降级与按比例计费
订阅变更（如升级或降级）可能会产生按比例计算的费用。Adapty 不会在收入计算中考虑这些费用。建议通过 Stripe 看板手动禁用这些选项。您也可以通过 Stripe API 将 proration_behaviour 属性值设置为 none 来禁用它们。
取消订阅
Stripe 有两种订阅取消选项：
- 立即取消：订阅立即取消，可选是否按比例退款
- 在周期结束时取消：订阅在当前计费周期结束时取消（类似于应用商店的应用内订阅）
Adapty 支持两种选项，但立即取消的收入计算将忽略按比例退款选项。
账单问题与宽限期
当客户遇到支付问题时，Adapty 将生成账单问题事件并撤销访问权限。我们目前暂不支持 Stripe 的宽限期——这将在未来版本中实现。
退款
Adapty 仅追踪全额退款。目前不支持按比例退款或部分退款。
交易 ID 唯一性
Adapty 使用 store_transaction_id 和 store_original_transaction_id 匹配用户画像和交易。这些 ID 在测试环境和生产环境中必须唯一。
为何重要
如果同一交易 ID 同时存在于两个环境中，Adapty 会将其视为同一笔交易，导致：
- 生产环境购买继承测试环境的访问等级和产品 ID
- API 响应中出现错误的产品 ID 和环境信息
- 用户画像关联和订阅事件受到干扰
如何确保唯一性
Stripe 的发票 ID 在测试环境和正式环境之间可能重叠。为防止跨环境冲突，请选择以下方案之一：
方案一：账户级编号加环境前缀
为每个环境分别配置前缀：
- 在 Stripe 看板中切换到测试模式。
- 前往 Settings → Billing → Invoices。
- 将 Invoice numbering 设置为 Sequentially across your account。
- 将 Invoice prefix 设置为 TEST-（或其他专用于测试环境的前缀）。
- 切换到正式模式，重复步骤 2-4，使用 LIVE-（或其他专用于正式环境的前缀）作为前缀。
方案二：客户级编号
在 Stripe settings -> Billing -> Invoices tab 中将 Invoice numbering 设置为 Sequentially for each customer (customer-level)。
即使进行了上述配置，如果您删除某张发票，Stripe 可能会将该 ID 重新用于同一客户的新发票。因此，请尽量避免删除发票。
充分利用您的 Stripe 数据
完成 Stripe 集成后，Adapty 即可立即提供洞察数据。为充分利用您的 Stripe 数据，您可以设置额外的 Adapty 集成以转发 Stripe 事件——将所有订阅分析数据汇集到单一 Adapty 看板中。
为增强分析能力，您可以在 Stripe 的 metadata 中包含 variation_id，以将购买归因到特定付费墙实例。这在实施自建网页付费墙时特别有用，可以追踪哪个具体的付费墙展示带来了转化。
请注意，variation_id 仅从 Stripe Subscription（sub_...）和 Checkout Session（ses_...）对象的 metadata 中读取：
{
'customer_user_id': "YOUR_USER_ID",
'variation_id': "YOUR_VARIATION_ID"
}可用于转发和分析 Stripe 事件的集成：
支持的 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