与 Paddle 的初始集成

Adapty 通过跟踪通过 Paddle 完成的网页支付和订阅，支持 web2app 订阅流程。

此集成涵盖网页端发起的购买，并将其与移动应用的访问权限和分析数据同步，与应用商店的应用内购买并行运作。 在以下场景中非常实用：

  • 在同一系统中收集应用内购买和网站购买的订阅数据
  • 为在网站上完成购买的用户授予移动应用中付费功能的访问权限
  • 在一个看板中查看所有销售渠道的数据分析和订阅数据

苹果现已允许美国区 App Store 的应用包含跳转至外部支付系统的链接，但应用可能仍需同时提供应用内购买选项。请查阅适用于您所在地区和应用类别的最新 App Store 审核指南。

此集成专注于追踪和同步 Paddle 网页购买记录。如果需要将用户从应用内引导至网页结账页面，请使用 Adapty 网页付费墙。

要设置 Paddle 集成，请按照以下步骤操作：

1. 将 Paddle 连接到 Adapty

该集成通过 Webhook 将订阅数据从 Paddle 发送到 Adapty。要连接您的 Adapty 和 Paddle 账户，您需要：

  1. 提供您的 Paddle API 密钥。
  2. 将 Adapty 的 Webhook URL 添加到 Paddle。

以下步骤同时适用于生产环境和测试环境，你可以同时配置两者。所提供的链接均为生产环境链接——如需获取测试环境链接，只需在每个 URL 开头添加 sandbox- 即可。例如，使用 https://sandbox-vendors.paddle.com/authentication-v2 代替 https://vendors.paddle.com/authentication-v2。

1.1. 获取并添加 Paddle API 密钥

  1. 在 Paddle 中，前往 Developer Tools → Authentication，点击 New API key。
paddle-new-key.webp
  1. 为密钥命名并设置过期日期。要让 API 密钥与 Adapty 配合使用，需要为所有实体授予 Read 权限。点击 Save。
paddle-key.webp
  1. 点击 Copy key。
copy-paddle-key.webp
  1. 在 Adapty 中，前往 App Settings → Paddle，将密钥粘贴到 Paddle API key 部分。

如果你为 Paddle API 密钥设置了过期日期，必须在到期前手动生成新密钥并在 Adapty 中更新。密钥过期后，集成将无任何警告地停止工作，用户将无法完成购买。

paddle-api-keys-adapty.webp

1.2. 添加将发送到 Adapty 的事件

  1. 从 Adapty 中同一个 Paddle 页面复制 Webhook URL。
  2. 在 Paddle 中，前往 Developer Tools → Notifications，然后点击 New destination 添加 webhook。
paddle-webhook.webp

  1. 为该 webhook 输入一个描述性名称。建议在名称中包含”Adapty”，方便日后查找。

  2. 将 Adapty 中的 Webhook URL 粘贴到 URL 字段。请确保使用的是正确环境的 webhook。

  3. 将 Notification type 设置为 Webhook。

paddle-create-webhook.webp
  1. 选择以下事件：

  • subscription.created

    • subscription.updated

    • transaction.created

    • transaction.updated

    • adjustment.created

    • adjustment.updated

paddle_events.png
  1. 点击 Save destination 完成 Webhook 设置。

1.3. 获取并添加 Webhook 密钥

  1. 在 Notifications 窗口中，点击刚刚创建的 Webhook 旁边的三个点，选择 Edit destination。
  2. Edit destination 面板中会出现一个名为 Secret key 的新字段，复制它。
paddle-webhook-secret-key-copy.webp
  1. 在 Adapty 中，前往 App Settings → Paddle，将密钥粘贴到 Notification secret key 字段中。Adapty 将使用该密钥验证 webhook 数据。
paddle-webhook-secret-key.webp

1.4. 将 Paddle 客户与 Adapty 用户画像关联

Adapty 需要将每笔购买与用户画像关联，这样才能在你的应用中使用。默认情况下，当 Adapty 收到 Paddle 的 webhook 时，会自动创建用户画像。你可以选择将哪个值用作 Adapty 中的 customer_user_id：

  1. 默认且推荐： 您在 custom_data 字段中传递的 customer_user_id（参见 Paddle 文档）
  2. Paddle Customer 对象中的 email（参见 Paddle 文档）
  3. ctm-... 格式的 Paddle Customer ID（参见 Paddle 文档）
  4. 不创建用户画像。如果您希望自行管理客户的用户画像，请选择此选项。 您可以在 App Settings → Paddle 的 Profile creation behavior 字段中配置使用哪个值。
paddle-users.webp

2. 将 Paddle 产品添加到 Adapty

请务必将您的 Paddle 产品添加到 Adapty 看板，或将 Paddle 产品 ID 添加到现有产品中。Adapty 仅跟踪与这些产品绑定的交易事件。如果跳过此步骤，将不会创建任何交易事件。

Paddle 在 Adapty 中的使用方式与 App Store 和 Google Play 完全相同——它是您销售数字产品的另一个平台。要完成配置，请在 Adapty 的 Products 页面中，填入相应的 product_id 和 price_id 值。

paddle-create-product.webp

在 Paddle 中，产品 ID 格式为 pro_...，价格 ID 格式为 pri_...。打开某个具体产品后，你可以在 Paddle 产品目录中找到它们：

paddle-product-price.webp

产品添加完成后，下一步是确保 Adapty 能将购买行为关联到正确的用户。

3. 为移动端用户提供访问权限

为确保在网页购买的用户能够在移动端获得访问权限，请使用购买时传入的相同 customer_user_id 调用 Adapty.activate() 或 Adapty.identify()。详情请参见用户识别。

4. 测试您的集成

完成所有设置后，您可以测试您的集成。在 Paddle 测试环境中进行的交易将在 Adapty 中显示为 Test。来自生产环境的交易将显示为 Production。

您的集成现已完成。用户可以在您的网站上购买订阅，并自动在您的移动应用中获得高级功能访问权限，同时您可以在统一的 Adapty 看板中跟踪所有订阅分析数据。

重要注意事项

  • 在 Adapty 的分析中，交易金额包含税费和 Paddle 手续费，这与 Paddle 看板中显示税后及手续费后金额的方式不同。因此，您在 Adapty 中看到的数字会高于 Paddle 看板中的数字。
  • 与其他商店不同，Paddle 中的退款仅影响被退款的特定交易，不会自动取消订阅。除非明确取消，否则订阅将继续保持活跃状态。
  • 您还可以在 custom_data 字段中包含 variation_id，以将购买归因到特定的付费墙实例。Adapty 将从 webhook 中处理这些数据，并将其纳入分析统计。

在 Paddle 中使用付费试用时，需要在 Adapty 中创建两个产品：

  1. 创建一个一次性购买产品，并将其关联到负责收取试用期费用的 Paddle 价格。
  2. 然后创建一个订阅产品（月度/周度等），并将其关联到包含免费试用组件的 Paddle 价格。

从 Paddle 的角度来看，这是一个包含两个价格的单笔交易——一个价格用于收取试用费（例如 $0.99），另一个价格用于免费试用（$0.00）。 从 Adapty 的角度来看，这会产生两个独立的事件：一个是针对试用付款的一次性购买事件，另一个是针对订阅产品的试用开始事件。

例如，当用户以 $0.99 开始付费试用一个 $9.99/月的订阅时，Paddle 会创建一笔包含两个价格的交易，而 Adapty 则将其处理为一笔 $0.99 的一次性购买（即时付款）和一个 $0.00 的试用开始事件（对应未来 $9.99/月的订阅）。

当用户取消付费试用时，你会收到 Trial expired 和 Trial renewal canceled 事件。

充分利用您的 Paddle 数据

要使您的 Paddle 事件能够与集成配合使用，您的用户必须至少使用其 App Store/Google Play 账户登录过一次应用。

完成 Paddle 集成后，Adapty 即可立即提供数据洞察。为了充分利用您的 Paddle 数据，您可以设置额外的 Adapty 集成来转发 Paddle 事件——将所有订阅分析数据汇聚到同一个 Adapty 看板中。

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

当前限制

  • 取消订阅：Paddle 提供两种取消订阅的方式：

    1. 立即取消：订阅立即终止。

    2. 在当前周期结束时取消：订阅在当前计费周期结束后终止（类似于应用商店中的应用内订阅）。

  • 退款：Adapty 支持追踪全额退款和部分退款。

  • 宽限期：默认情况下，Paddle 为账单问题设置固定的 30 天宽限期，在此期间订阅保持有效。你可以自定义宽限期时长及到期后的处理方式（暂停或取消订阅）。 试用期：如果试用期结束后收款失败，订阅状态将变为 past_due。在生产环境中，Paddle 的 Retain 功能会应用催款窗口，在订阅被取消或暂停之前尝试恢复付款。在沙盒环境中，Retain 不可用，因此不会重试付款，订阅将无限期保持 past_due 状态。

另请参阅：