企业官网建设流程全解析

使用 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 Manager（GTM）实现销售（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"); </script>

Dub 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 工作区中依次操作：

1. 进入Variables（变量）板块，点击New（新建）；
2. 将Variable Type（变量类型）选为1st Party Cookie（第一方 Cookie）；
3. Cookie Name填写dub_id；
4. Variable Name（变量名称）命名为Dub ID Cookie（便于后续在自定义 HTML 中引用）；
5. 点击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, }); } })(); </script>

Important: 请务必在跳转到订单确认页时携带customer_id与amount查询参数，否则销售事件无法正确归因到对应的客户与订单。

触发条件配置：为该标签创建Page View触发器：

• Trigger Type（触发器类型）：Page View
• This 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, }); } })(); </script>

Important: 你需要根据实际站点结构调整 DOM 选择器——getElementById('customer_id')、getElementById('amount')等 ID 必须与表单真实字段 ID 一致，也可改用其他方式捕获结账数据。

触发条件配置：为该标签创建Form Submission触发器：

• Trigger Type（触发器类型）：Form Submission
• This trigger fires on（触发时机）：Some Forms（若希望追踪所有表单提交可选All Forms）
• 添加条件限定触发范围（例如仅结账表单）

将该标签命名为Dub Sales Tracking - Checkout Form并保存。

Step 3：测试与验证配置

使用 GTM Preview 模式测试

1. 在 GTM 工作区右上角点击Preview（预览）按钮；
2. 输入你的网站 URL 并点击Connect（连接）；
3. 按所选方式测试：
   • Option 1（订单确认页）：携带查询参数访问订单确认页，例如?customer_id=123&amount=5000&invoice_id=inv_123；
   • Option 2（结账表单）：访问包含结账表单的页面并完成一次测试购买；
4. 在 GTM 调试器中确认标签是否正确触发。

验证销售追踪是否生效

• 打开浏览器开发者控制台（Console），检查是否有 JavaScript 报错；
• 使用 Network（网络）面板确认是否有请求发送到 Dub 的分析端点；
• 登录 Dub Dashboard，确认分析数据中已出现 sale 事件。

常见问题排查

深入理解：trackSale 参数与服务端处理链路

字段语义（来自服务端请求 Schema）

dubAnalytics.trackSale()最终会命中 Dub 服务端的POST /api/track/sale/client接口（见 route.ts/api/track/sale/client/route.ts)），其请求体由 sales.ts 中的trackSaleRequestSchema严格校验。各字段要点：

• customerExternalId（必填）：客户在你系统中的唯一 ID，服务端会据此创建或关联Customer记录，最长 100 字符；若不传将直接报bad_request；
• amount（必填）：以「分」为单位的整数金额（适用于所有两位小数币种）；若为零小数币种则传完整整数值（如1580JPY）；金额为 0 或负数时服务端会直接跳过，不产生 sale 记录；
• currency（默认usd）：ISO 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、custom；
• clickId：从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()，其关键链路为：

1. 幂等检查：若携带invoiceId，先查 Redis 缓存，命中则直接返回历史响应；
2. 客户匹配：按projectId_externalId查找已有客户；若客户已存在，校验其关联链接归属与启用状态，并读取对应 lead 事件；
3. 直接销售追踪：若没有已有客户但携带clickId，则通过getClickEvent读取该点击事件，校验链接归属后，用createId({ prefix: "cus_" })创建客户（linkId、clickId、country、clickedAt均取自点击事件），并自动补记一条 lead 事件（默认名称 "Direct sale tracking lead event"，可用leadEventName覆盖），同时用 30 秒 TTL 的 Redis 锁对并发请求去重；
4. 记录 sale 事件：经recordSale写入 Tinybird 事件表，更新链接的sales、saleAmount、首次转化时的conversions统计，更新客户sales、saleAmount、firstSaleAt；若链接挂接在 Partner Program 上，还会排队创建合作伙伴佣金（queuePartnerCommissionCreation）、触发工作流（executeWorkflows）与合作伙伴回传（sendPartnerPostback）；
5. Webhook 与集成：触发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.ts：trackSale请求/响应与 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