介绍
Dub 是一个链接归因平台,用于短链接、转化跟踪和联盟计划。通过此集成,每当客户通过 Dodo Payments 付款时,Dub 都会记录一次销售转化事件,因此您可以衡量营销活动和推荐计划的投资回报。 当客户执行以下操作时,Dub 会记录一次销售:- 完成一次性付款
- 订阅付费计划
- 进行周期性订阅付款
此集成要求您拥有一个 Dub 账户,并且已为链接启用转化跟踪。Dub 的转化跟踪要求使用 Business 计划或更高版本。
工作原理
当访客点击您的某个 Dub 短链接时,Dub 会在dub_id cookie 中存储唯一的点击 ID。要将销售归因到您的链接:
- 捕获 Dub 的点击 ID:创建 checkout 时,从
dub_idcookie 中读取 Dub 的点击 ID。 - 存储点击 ID:将点击 ID 存储在付款的
metadata中,同时在您的系统中存储客户 ID(即 external ID)。 - 将销售发送到 Dub:付款成功后,通过其 Track API 将销售发送到 Dub。
先决条件
在设置此集成之前,您需要准备:- 一个拥有工作区的 Dub 账户。
- 为您的链接启用转化跟踪。
- 一个 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。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。

2
Select Dub
在 Integration 中选择 Dub.co。
3
Enter API Key
在 API key 中粘贴你的 Dub API key。Dodo Payments 会在每次传送的 
Authorization header 中发送该密钥。
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
- 在 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
Sales Not Appearing in Dub
Sales Not Appearing in Dub
- 确认你的 Dub API key 正确,并具有
conversions.writescope。 - 检查是否已捕获并存储
dub_click_id到支付 metadata 中。 - 检查 webhook transformation 是否正确格式化了 payload。
- 确认 endpoint 已订阅
payment.succeeded。 - 确认你的 Dub 链接已启用 conversion tracking。
- 打开 Developer → Webhooks 的 Logs 选项卡中的 endpoint 传送尝试,查看 Dub 的响应。没有 click ID 的支付会被取消,但会显示为成功。
Revenue Attribution Not Working
Revenue Attribution Not Working
- 确认客户在结账前点击了你的 Dub 短链接。
- 确认
dub_idcookie 已在你的域名上设置。 - 检查支付 metadata 中的 click ID 是否与客户点击的链接相匹配。
- 在创建 checkout 前捕获 click ID。
Transformation Errors
Transformation Errors
- 检查 payload 是否符合 Dub 的 Track Sale API 格式。
- 检查必需字段
customerExternalId和amount是否存在,并确认已设置clickId以进行归因。 - 检查金额是否为最小货币单位中的整数,而不是小数。
- 确认 endpoint URL 为
https://api.dub.co/track/sale。 - 使用示例 webhook payload 测试 transformation。
Duplicate Sales Being Tracked
Duplicate Sales Being Tracked
- 仅在
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 支持团队。