Skip to main content

介绍

Dub 是一个链接归因平台,用于短链接、转化跟踪和联盟计划。通过此集成,每当客户通过 Dodo Payments 付款时,Dub 都会记录一次销售转化事件,因此您可以衡量营销活动和推荐计划的投资回报。 当客户执行以下操作时,Dub 会记录一次销售:
  • 完成一次性付款
  • 订阅付费计划
  • 进行周期性订阅付款
此集成要求您拥有一个 Dub 账户,并且已为链接启用转化跟踪。Dub 的转化跟踪要求使用 Business 计划或更高版本。
联盟计划集成:此集成也适用于 Dub Partners,即 Dub 的联盟计划产品。Dub 会将销售归因到合作伙伴的联盟链接,因此您可以跟踪推荐、佣金和每个合作伙伴的表现。要设置联盟计划,请参阅联盟功能指南。

工作原理

当访客点击您的某个 Dub 短链接时,Dub 会在 dub_id cookie 中存储唯一的点击 ID。要将销售归因到您的链接:
  1. 捕获 Dub 的点击 ID:创建 checkout 时,从 dub_id cookie 中读取 Dub 的点击 ID。
  2. 存储点击 ID:将点击 ID 存储在付款的 metadata 中,同时在您的系统中存储客户 ID(即 external ID)。
  3. 将销售发送到 Dub:付款成功后,通过其 Track API 将销售发送到 Dub。
Dub 会将每笔成功的销售与最初的链接点击进行匹配,从而将转化归因到该链接。

先决条件

在设置此集成之前,您需要准备:
  1. 一个拥有工作区的 Dub 账户。
  2. 为您的链接启用转化跟踪。
  3. 一个 Dub API key,您可以在 Dub 控制面板的 Settings → API Keys 中创建。

开始使用

1

Enable Conversion Tracking in Dub

在 Dub 控制面板中,为您要跟踪销售的链接启用转化跟踪。随后,Dub 会为通过这些链接访问的客户记录销售事件。
要启用转化跟踪,请参阅 Dub 文档。
2

Get Your Dub API Key

在您的 Dub 控制面板 中,转到 Settings → API Keys,并创建一个具有 conversions.write 权限范围的 API key。
请妥善保护您的 API key。切勿将其暴露在客户端代码中。
3

Capture Click ID in Checkout

创建 checkout 时,从 cookie 中读取 Dub 点击 ID,并将其添加到付款的 metadata 中。请参阅步骤 1。
4

Send Sale Data via Webhook

创建一个 webhook endpoint,在付款成功后将每笔销售发送到 Dub 的 Track API。请参阅步骤 2。
5

Done

销售转化事件会显示在 Dub analytics 控制面板中,并归因到您的链接。

实施指南

第 1 步:将点击 ID 和客户 ID 添加到结账元数据

创建 checkout 时,从 cookie 中读取 Dub 点击 ID,并将其与客户的 external ID 一起添加到付款的 metadata 中。
以下示例使用已弃用的 POST /payments。它仍适用于现有集成,但新集成应使用 Checkout Sessions(POST /checkouts),后者以相同方式接受 metadata。

步骤 2:向 Dub 发送销售数据

创建一个 webhook endpoint,在付款成功后将销售数据发送到 Dub 的 Track API。
1

Open the Webhook Section

在 Dodo Payments 仪表板中,前往 Developer → Webhooks,然后点击 Add endpoint。
已在 Integration 下拉菜单中选择 Dub.co 的 Add endpoint 对话框
2

Select Dub

在 Integration 中选择 Dub.co。
3

Enter API Key

在 API key 中粘贴你的 Dub API key。Dodo Payments 会在每次传送的 Authorization header 中发送该密钥。
Dub integration 的 API key 字段
4

Check the URL and Events

如果 Endpoint URL 为空,请输入 https://api.dub.co/track/sale。在 Subscribed events 中选择你的转换处理的事件,例如 payment.succeeded。
5

Configure Transformation

在 Transformation code 下编辑处理程序,以便为 Dub 的 Track Sale API 格式化支付数据。请从示例开始。
6

Test & Create

在 Test this code 下点击 Simulate,使用示例 payload 运行处理程序。然后点击 Create endpoint。

Transformation Code Examples

每个处理程序仅在 metadata 具有 click ID 时才会向 Dub 发送销售记录。对于没有 click ID 的自然流量,处理程序会设置 webhook.cancel = true,因此不会向 Dub 发送请求;已取消的传送仍会在 webhook 日志中显示为成功。 请求正文遵循 Dub 的 Track Sale API:customerExternalId 和 amount 是必需字段,而 paymentProcessor 为 custom,因为 Dub 的支付处理器列表中没有 Dodo Payments。Dub 使用与 Dodo Payments 金额相同的单位接收 amount:两位小数货币使用分,零位小数货币(例如 JPY)使用完整整数。示例会原样传递金额。

Basic Sale Tracking

在支付成功时跟踪销售:
basic_sale.js

Track Subscription Sales

跟踪初始订阅和周期性付款。对于订阅,请使用此处理程序,而不要使用 payment.succeeded 处理程序,也不要与其同时使用:每笔订阅付款也会触发 payment.succeeded,因此同时处理这两个事件会导致每笔销售被记录两次。请参阅订阅集成指南。 该处理程序从订阅的 metadata 中读取 click ID,因此创建订阅时请传递相同的 metadata。对于续订,invoiceId 会将订阅 ID 与当前计费周期的起始时间 previous_billing_date 组合起来,因此重试的传送会复用相同的 invoiceId。
subscription_sale.js

Track Sales with Tax Exclusion

仅向 Dub 发送税前金额,使 Dub 中的收入不包含税费:
sale_without_tax.js

Track Sales with Custom Event Names

使用自定义事件名称对不同类型的销售进行分类。示例会读取你在支付的 metadata 中设置的 is_upgrade 标志:
custom_events.js

Alternative: Client-Side Implementation

如果不想通过 webhook transformation,而是想从自己的服务器跟踪销售,请在支付成功后直接调用 Dub 的 Track API,例如从 payment.succeeded webhook 处理程序中调用。代码使用你的 Dub API key,因此请在服务器上运行,绝不要在浏览器中运行。

Best Practices

尽早捕获 click ID:尽可能在结账流程的早期存储 Dub click ID,这样即使客户离开后稍后返回,归因仍能保持准确。
  • 在 metadata 中包含 click ID:没有 click ID,Dub 就无法将收入归因到你的链接。
  • 始终一致地使用 external ID:每次都将系统中的同一客户 ID 作为 customerExternalId 传递,以获得准确的客户级分析。
  • 处理自然流量:没有 click ID 时设置 webhook.cancel = true,以避免不必要的 API 调用。
  • 使用示例支付进行测试:通过 Test this code 运行处理程序,并在正式上线前确认集成正常运行。
  • 监控你的 Dub 仪表板:检查销售是否显示了预期的归因。

Important Notes

  • 金额格式:对于两位小数货币,Dub 要求金额以分为单位(例如,$10.00 是 1000);对于 JPY 等零位小数货币,则使用完整整数。
  • 货币:使用 ISO 4217 货币代码,例如 USD、EUR 和 GBP。Dub 会按照最新汇率将每笔销售转换为 USD。
  • 免费试用:Dub 的 Track Sale API 接受 amount 为 0 的情况,并且示例不会跳过 $0 支付,因此每笔 $0 支付都会作为销售记录发送到 Dub。若要跳过 $0 支付,请在 total_amount 为 0 时设置 webhook.cancel = true。
  • 退款:如果需要准确的收入报告,请单独跟踪退款。

Troubleshooting

  • 确认你的 Dub API key 正确,并具有 conversions.write scope。
  • 检查是否已捕获并存储 dub_click_id 到支付 metadata 中。
  • 检查 webhook transformation 是否正确格式化了 payload。
  • 确认 endpoint 已订阅 payment.succeeded。
  • 确认你的 Dub 链接已启用 conversion tracking。
  • 打开 Developer → Webhooks 的 Logs 选项卡中的 endpoint 传送尝试,查看 Dub 的响应。没有 click ID 的支付会被取消,但会显示为成功。
  • 确认客户在结账前点击了你的 Dub 短链接。
  • 确认 dub_id cookie 已在你的域名上设置。
  • 检查支付 metadata 中的 click ID 是否与客户点击的链接相匹配。
  • 在创建 checkout 前捕获 click ID。
  • 检查 payload 是否符合 Dub 的 Track Sale API 格式。
  • 检查必需字段 customerExternalId 和 amount 是否存在,并确认已设置 clickId 以进行归因。
  • 检查金额是否为最小货币单位中的整数,而不是小数。
  • 确认 endpoint URL 为 https://api.dub.co/track/sale。
  • 使用示例 webhook payload 测试 transformation。
  • 仅在 payment.succeeded 事件上跟踪销售,不要在 payment.processing 上跟踪。
  • 为每笔销售使用唯一的 invoiceId。Dub 对每个 invoiceId 只记录一笔销售。
  • 对于续订,请根据订阅 ID 和计费周期构建 invoiceId,如跟踪订阅销售中所示。每次传送都会变化的值(例如当前时间)会在传送重试时记录重复销售。

Additional Resources

Dub Conversions Documentation

了解 Dub 的 conversion tracking 和 analytics 功能。

Dub Track Sale API

查看 Dub Track Sale endpoint 的完整 API reference。

Dub Dashboard

在你的 Dub 仪表板中查看 conversion analytics 和 attribution data。

Webhook Events Guide

浏览所有 Dodo Payments webhook 事件。
如需此集成的帮助,请通过 support@dodopayments.com 联系 Dodo Payments 支持团队。
最后修改于 2026年9月26日