如何不用 SDK 直接调用 Dub REST API 手动上报 lead 与 sale 事件【免费下载链接】dubThe modern link attribution platform. Loved by world-class marketing teams like Framer, Perplexity, Superhuman, Twilio, Buffer and more.项目地址: https://gitcode.com/GitHub_Trending/du/dub如果你的服务侧需要在注册lead或付款成功sale发生时把事件回传给 Dub 做归因又不想安装dub这个 npm 包可以直接调用 Dub 的 REST API向https://api.dub.co/track/lead和https://api.dub.co/track/sale各发一个带 Bearer Token 的 POST 请求即可。本文基于仓库内的 rest-api.md、manual-track-lead.md 和 manual-track-sale.md 给出完整请求示例并结合 OpenAPI 路由定义 与 请求参数 schema 说明字段、默认值和成功判定。准备条件一个 Dub API key。所有请求都要带认证头格式为Authorization: Bearer dub_xxxxxx其中dub_xxxxxx替换为你自己的 API key示例中的dub_xxxxxx是文档占位值不能直接使用。只使用 HTTPS。Dub 的 API 基于 REST、通过 HTTPS 提供服务出于数据隐私考虑不支持未加密的 HTTP因此两个上报端点都必须用https://地址。如果 lead 事件要归因到某次短链点击你需要拿到该点击的clickId。文档说明这个值可以从dub_idcookie 中读取。示例使用 Node.js 内置的fetch即 Node 环境无需额外依赖。上报 lead 事件对https://api.dub.co/track/lead发送 POST 请求认证头携带 API key请求体是 JSONconst response await fetch(https://api.dub.co/track/lead, { method: POST, headers: { Authorization: Bearer dub_xxxxxx, Content-Type: application/json, }, body: JSON.stringify({ clickId: rLnWe1uz9t282v7g, eventName: Sign up, customerExternalId: cus_oFUYbZYqHFR0knk0MjsMC6b0, customerName: John Doe, customerEmail: john.doeexample.com, customerAvatar: https://example.com/avatar.png, }), }); const data await response.json();上面clickId、customerExternalId、姓名、邮箱都是文档示例值替换为你自己的数据。按 track lead 请求 schema必填与可选字段的划分如下字段是否必填说明以 schema 为准clickId必填该 lead 归因到的点击 ID从dub_idcookie 读取。文档注明若做 deferred lead tracking可以传空字符串Dub 会尝试用customerExternalId找到已有客户并使用该客户的clickIdeventName必填lead 事件名1–255 字符例如Sign up。它也后续可作为唯一标识在/track/sale中通过leadEventName字段把 sale 关联到这个 leadcustomerExternalId必填客户在你系统中的唯一 ID1–100 字符Dub 用它识别并归因该客户的后续所有事件customerName可选不传时 Dub 会生成一个随机名字文档示例Big Red CariboucustomerEmail可选客户邮箱customerAvatar可选头像 URLmode可选默认asyncasync不阻塞请求wait阻塞直到事件在 Dub 中完整记录deferred把 lead 事件创建推迟到后续请求eventQuantity可选正整数、最大 100表示该 lead 事件被追踪 N 次例如试用开通的席位数metadata可选附加元数据stringify 后最大 10,000 字符上报 sale 事件对https://api.dub.co/track/sale发送 POST 请求示例同样来自文档const response await fetch(https://api.dub.co/track/sale, { method: POST, headers: { Authorization: Bearer dub_xxxxxx, Content-Type: application/json, }, body: JSON.stringify({ customerExternalId: cus_oFUYbZYqHFR0knk0MjsMC6b0, amount: 3000, // sale amount in cents paymentProcessor: stripe, eventName: Invoice paid, invoiceId: INV_1234567890, currency: usd, }), }); const data await response.json();sale 事件与 lead 事件的关键区别在字段上参见 track sale 请求 schemacustomerExternalId必填规则同 lead。sale 通过它找到客户默认关联该客户在该短链上最近一次 lead 事件如果要用leadEventName精确指定关联哪一个 lead 事件先报 lead 时用的eventName必须与之大小写一致。amount必填是非负整数。对两位小数币种按分传3000表示 30.00 美元零小数币种传完整整数值文档给出的例子是1580JPY。currency可选默认usd接受 ISO 4217 货币代码非美元 sale 会按最新汇率自动换算并以 USD 存储。paymentProcessor可选默认custom只接受 schema 中枚举的取值stripe、shopify、polar、paddle、apple、revenuecat、lemonsqueezy、dub、custom。eventName可选默认Purchase文档推荐格式如Invoice paid或Subscription created。invoiceId可选可作为幂等键使用同一个 invoice ID 只会记录一条 sale 事件。如果你的场景是没有 lead 事件、直接上报 saledirect sale tracking则传clickId以及customerName、customerEmail、customerAvatar这几个字段schema 中对它们标注了[For direct sale tracking]。结果验证两个端点的成功判定都以 HTTP 200 为准OpenAPI 定义中 200 的 description 分别是 A lead was tracked. 和 A sale was tracked.见 lead 操作定义 和 sale 操作定义。响应体结构在 schema 中有明确定义lead 的 200 响应trackLeadResponseSchema{ click: { id: ... }, link: { id: ..., domain: ..., key: ..., shortLink: ..., url: ..., partnerId: ..., programId: ..., tenantId: ..., externalId: ... }, customer: { name: ..., email: ..., avatar: ..., externalId: ... } }sale 的 200 响应trackSaleResponseSchema{ eventName: Invoice paid, customer: { id: ..., name: ..., email: ..., avatar: ..., externalId: ... }, sale: { amount: 3000, currency: usd, paymentProcessor: stripe, invoiceId: INV_1234567890, metadata: null } }两个响应中的link/customer字段按 schema 可为null。请求发出后await response.json()得到上述结构、且customer中的externalId与你传入的customerExternalId一致即可确认事件已归因到正确的客户sale 响应中的sale对象会回显 amount、currency、paymentProcessor 与 invoiceId可用于核对金额和幂等 ID。限制与注意事项两个端点都要求 JSON 请求体和Authorization: Bearer认证缺少 API key 或字段不符合 schema如amount为负数、eventName为空时请求不会按 200 成功处理OpenAPI 中同时定义了通用错误响应openApiErrorResponses。lead 的clickId必填唯一的例外是 deferred 模式下允许空字符串依赖 Dub 按customerExternalId回填已有客户的clickId普通异步/同步上报不要依赖这个行为。metadata在两个端点的上限都是 stringify 后 10,000 字符。sale 的幂等只由invoiceId保证不传invoiceId时重复上报同一笔订单会产生多条记录。更多可选参数与完整的响应格式仓库内 guides 下的两篇文档指向了 Dub 官方 API referencetrack-lead、track-saleendpoint 页面可按字段名对照查询。完成上面两个请求后lead 与 sale 事件就分别进入 Dub 的归因数据如果你之后需要调整 lead 与 sale 的关联方式改动点只有一个sale 请求里的leadEventName字段。【免费下载链接】dubThe modern link attribution platform. Loved by world-class marketing teams like Framer, Perplexity, Superhuman, Twilio, Buffer and more.项目地址: https://gitcode.com/GitHub_Trending/du/dub创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考