使用 Google Tag Manager 在 Dub 中配置 Sale 转化追踪从 dub_id Cookie 到订单成功页的完整实践【免费下载链接】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导读本文基于 Dub 官方指南apps/web/guides/gtm-track-sale.md系统讲解如何通过 Google Tag ManagerGTM实现销售Sale转化事件追踪先读取 Dub Analytics 写入的dub_idCookie再通过订单确认页或结账表单两种方式上报dubAnalytics.trackSale()。读完本文你将掌握 GTM 变量/触发器/标签的完整配置步骤、trackSale各参数字段的精确语义含金额单位、币种换算、幂等去重并能结合仓库源码理解从浏览器上报到 Dub 服务端归因的完整链路。前置条件先通过 GTM 安装 Dub Analytics 脚本本指南假设你已在 GTM 中完成 Dub Analytics 客户端脚本的安装。若尚未安装可参考 gtm-client-sdk.md新建Custom HTML标签粘贴如下脚本注意其中为dubAnalytics注入了trackClick、trackLead、trackSale三个方法触发条件设为All Pages保存并发布script (function (c, n) { c[n] c[n] || function () { (c[n].q c[n].q || []).push(arguments); }; var methods [trackClick, trackLead, trackSale]; for (var i 0; i methods.length; i) { (function (method) { c[n][method] function () { var args Array.prototype.slice.call(arguments); args.unshift(method); c[n].apply(null, args); }; })(methods[i]); } var s document.createElement(script); s.defer 1; s.src https://www.dubcdn.com/analytics/script.js; document.head.appendChild(s); })(window, dubAnalytics); /scriptDub Analytics 脚本加载后会在用户点击 Dub 短链时写入dub_idCookie——这是后续所有转化归因的基础。从源码看Dub 自身也依赖该 Cookie 做归因例如apps/web/lib/auth/track-dub-lead.ts通过cookies().get(dub_id)读取点击 ID 并上报 lead 事件随后主动删除dub_id与dub_partner_data说明该 Cookie 是 Dub 侧链接点击与客户会话关联的关键凭据。Step 1创建 GTM 变量读取 dub_id Cookie在 GTM 工作区中依次操作进入Variables变量板块点击New新建将Variable Type变量类型选为1st Party Cookie第一方 CookieCookie Name填写dub_idVariable Name变量名称命名为Dub ID Cookie便于后续在自定义 HTML 中引用点击Save保存。配置完成后在任意自定义 HTML 标签中即可通过{{Dub ID Cookie}}引用该变量的值。它对应dub_idCookie 中存放的点击 ID即 Dub 短链点击事件的唯一标识服务端对应字段为clickId参见 sales.ts 中clickId的描述“You can read this value fromdub_idcookie”。Step 2两种 Sale 事件追踪方式追踪销售事件有两种实现路径指南推荐第一种方式触发时机可靠性适用场景订单确认页追踪推荐用户到达订单确认/成功页更高不易被广告拦截器影响数据准确度更好支付后跳转到独立成功页的站点结账表单追踪用户提交结账表单瞬间较低受广告拦截与时机影响无独立成功页、依赖前端表单的场景Option 1订单确认页追踪推荐当用户完成购买后到达订单确认页order confirmation / success page时上报销售事件。创建Custom HTML标签填入以下代码script (function () { // Get query parameters from URL var params new URLSearchParams(window.location.search); var customerId params.get(customer_id); var amount params.get(amount); var invoiceId params.get(invoice_id); // Get dub_id from cookie using GTM variable var clickId {{Dub ID Cookie}} || ; // Only track the sale event if customer ID, amount, and clickId are present if (customerId amount clickId) { dubAnalytics.trackSale({ eventName: Purchase, customerExternalId: customerId, amount: parseInt(amount), // Amount in cents invoiceId: invoiceId || undefined, currency: usd, // Customize as needed paymentProcessor: stripe, // Customize as needed clickId: clickId, }); } })(); /scriptImportant: 请务必在跳转到订单确认页时携带customer_id与amount查询参数否则销售事件无法正确归因到对应的客户与订单。触发条件配置为该标签创建Page View触发器Trigger Type触发器类型Page ViewThis trigger fires on触发时机Some Page Views添加条件例如Page URLcontains/order-confirmation或Page Pathequals/checkout/success或与你的订单确认页 URL 规则匹配的其他模式将该标签命名为Dub Sales Tracking - Order Confirmation并保存。Option 2结账表单追踪当用户提交结账表单的瞬间上报销售事件。创建Custom HTML标签填入以下代码script (function () { // Get checkout data - customize these selectors based on your form var customerId document.getElementById(customer_id) ? document.getElementById(customer_id).value : ; var amount document.getElementById(amount) ? document.getElementById(amount).value : ; var invoiceId document.getElementById(invoice_id) ? document.getElementById(invoice_id).value : ; // Get dub_id from cookie using GTM variable var clickId {{Dub ID Cookie}} || ; // Only track the sale event if customer ID, amount, and clickId are present if (customerId amount clickId) { dubAnalytics.trackSale({ eventName: Purchase, customerExternalId: customerId, amount: parseInt(amount), // Amount in cents invoiceId: invoiceId || undefined, currency: usd, // Customize as needed paymentProcessor: stripe, // Customize as needed clickId: clickId, }); } })(); /scriptImportant: 你需要根据实际站点结构调整 DOM 选择器——getElementById(customer_id)、getElementById(amount)等 ID 必须与表单真实字段 ID 一致也可改用其他方式捕获结账数据。触发条件配置为该标签创建Form Submission触发器Trigger Type触发器类型Form SubmissionThis trigger fires on触发时机Some Forms若希望追踪所有表单提交可选All Forms添加条件限定触发范围例如仅结账表单将该标签命名为Dub Sales Tracking - Checkout Form并保存。Step 3测试与验证配置使用 GTM Preview 模式测试在 GTM 工作区右上角点击Preview预览按钮输入你的网站 URL 并点击Connect连接按所选方式测试Option 1订单确认页携带查询参数访问订单确认页例如?customer_id123amount5000invoice_idinv_123Option 2结账表单访问包含结账表单的页面并完成一次测试购买在 GTM 调试器中确认标签是否正确触发。验证销售追踪是否生效打开浏览器开发者控制台Console检查是否有 JavaScript 报错使用 Network网络面板确认是否有请求发送到 Dub 的分析端点登录 Dub Dashboard确认分析数据中已出现 sale 事件。常见问题排查症状检查项标签未触发触发器条件是否与页面结构匹配缺少 publishable key是否已将占位符替换为真实的可发布密钥缺少查询参数Option 1结账流程是否将所需查询参数透传到订单确认页表单数据未捕获Option 2DOM 选择器是否与实际表单字段 ID/name 一致深入理解trackSale 参数与服务端处理链路字段语义来自服务端请求 SchemadubAnalytics.trackSale()最终会命中 Dub 服务端的POST /api/track/sale/client接口见 route.ts/api/track/sale/client/route.ts)其请求体由 sales.ts 中的trackSaleRequestSchema严格校验。各字段要点customerExternalId必填客户在你系统中的唯一 ID服务端会据此创建或关联Customer记录最长 100 字符若不传将直接报bad_requestamount必填以「分」为单位的整数金额适用于所有两位小数币种若为零小数币种则传完整整数值如1580JPY金额为 0 或负数时服务端会直接跳过不产生 sale 记录currency默认usdISO 4217 币种代码。从 track-sale.ts 的实现看非 USD 币种会调用convertCurrency按实时汇率换算后统一以 USD 存储因此上报前无需自行换算eventName默认Purchase事件名称推荐如Invoice paid或Subscription created最长 255 字符invoiceId可选发票 ID。同时作为幂等键——同一个 invoiceId 只会记录一次 sale 事件服务端以trackSale:{workspaceId}:invoiceId:{invoiceId}为键在 Redis 缓存响应缓存期一周适合在 GTM 标签可能重复触发时防止重复记账paymentProcessor默认custom支付处理器枚举值包括stripe、shopify、polar、paddle、apple、revenuecat、lemonsqueezy、dub、customclickId从dub_idCookie 读到的点击 ID用于直接销售归因customerName / customerEmail / customerAvatar客户信息不传时服务端会生成随机名称如 Big Red Caribou。服务端归因与事件分发浏览器端的trackSale调用走客户端接口POST /api/track/sale/client该接口使用publishable key鉴权withPublishableKey并要求业务版及以上套餐requiredPlan: [business, advanced, enterprise]。请求会先经 verify-analytics-allowed-hostnames.ts 校验来源域名是否在工作区的Allowed Hostnames白名单中支持精确域名与*.domain.com通配子域名未配置白名单时放行校验失败返回forbidden。随后进入 track-sale.ts 的核心逻辑trackSale()其关键链路为幂等检查若携带invoiceId先查 Redis 缓存命中则直接返回历史响应客户匹配按projectId_externalId查找已有客户若客户已存在校验其关联链接归属与启用状态并读取对应 lead 事件直接销售追踪若没有已有客户但携带clickId则通过getClickEvent读取该点击事件校验链接归属后用createId({ prefix: cus_ })创建客户linkId、clickId、country、clickedAt均取自点击事件并自动补记一条 lead 事件默认名称 Direct sale tracking lead event可用leadEventName覆盖同时用 30 秒 TTL 的 Redis 锁对并发请求去重记录 sale 事件经recordSale写入 Tinybird 事件表更新链接的sales、saleAmount、首次转化时的conversions统计更新客户sales、saleAmount、firstSaleAt若链接挂接在 Partner Program 上还会排队创建合作伙伴佣金queuePartnerCommissionCreation、触发工作流executeWorkflows与合作伙伴回传sendPartnerPostbackWebhook 与集成触发sale.createdWebhook并向上报stripe/shopify等支付处理器时同步 Google Ads 转化上传queueGoogleAdsConversionUpload。整体来看GTM 侧脚本只是「入口」真正完成点击归因、客户建档、佣金结算与数据分析的是apps/web/app/(ee)/api/track/sale/client/route.ts→apps/web/lib/api/conversions/track-sale.ts→ Tinybird 事件表这条服务端链路。进一步阅读gtm-client-sdk.md通过 GTM 安装 Dub Analytics 客户端脚本的完整步骤gtm-track-lead.md同思路的 Lead 转化追踪配置Thank You Page 与表单提交两种方式可作为本指南的姊妹篇manual-client-sdk.md不使用 GTM、直接在head引入 Dub 客户端脚本的方式track-sale.ts服务端销售归因与事件分发的核心实现sales.tstrackSale请求/响应与 sale 事件字段的完整 Schema 定义。【免费下载链接】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），仅供参考