在 Supabase Auth 回调中接入 Dub Lead 转化跟踪从dub_idCookie 归因到 Sign Up 事件上报【免费下载链接】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 开源仓库中的官方集成指南完整讲解如何在基于 Supabase 的 Next.js 应用里通过在/api/auth/callback回调路由中上报 Lead 转化事件把点击 Dub 短链 → 注册成为新用户这一链路以可归因的方式接入 Dub 的分析与归因体系。读完本文你将掌握dub.track.lead的完整调用方式、dub_idCookie 的来源与生命周期以及如何用 10 分钟新用户窗口精确区分新注册与老用户登录避免重复上报与归因污染。一、背景Dub 的转化归因模型为什么依赖dub_idDub 的转化归因Lead / Sale 归因核心思路是一次点击对应一个全局唯一的点击 IDclickId后续发生的转化事件必须携带该 ID 才能回溯到来源链接。在 Dub 的短链跳转链路中当用户点击一个启用了转化跟踪trackConversion的短链时服务端会为该次点击生成一个 16 位随机 IDnanoid(16)并以 Cookie 形式种在浏览器里。从仓库源码 lib/middleware/link.ts 可以看到这一机制的实现细节Cookie 的命名格式为dub_id_{domain}_{key}例如访问dub.sh/launch后浏览器会持有名为dub_id_dub.sh_launch的 Cookie只有当链接满足启用转化跟踪 / 合作伙伴链接 / Singular、AppsFlyer 跟踪 URL等条件时点击 ID 才会被缓存shouldCacheClickId从而支撑后续的/track/lead请求归因若命中 Redis 中缓存的点击记录会复用原 clickId否则新生成一个。而 Dub 的客户端分析脚本gtm-client-sdk.md 中提到的dubcdn.com/analytics/script.js与各类 SDK 在对外接口上统一将归因标识暴露为dub_idCookie。因此在应用服务端读取dub_idCookie就等价于拿到用户是经由哪一次 Dub 点击进入本站这一归因信息。二、集成前提准备好 Supabase 客户端与 Dub SDK在编写回调路由之前你的应用需要具备以下基础能力Supabase 服务端客户端用于在回调中通过exchangeCodeForSession完成 OAuth Code 换取会话。指南中的示例引用了/lib/supabase/server即应用内对 Supabase SSR 客户端的封装通常基于supabase/ssr的createServerClient实现并接收cookies()作为存储。Dub SDK 客户端指南中的import { dub } from /lib/dub对应应用内对 Dub TypeScript SDK 的实例化。仓库自身就是这么做的见 apps/web/lib/dub.tsimport { Dub } from dub; export const dub new Dub();new Dub()默认读取DUB_API_KEY环境变量作为鉴权凭据。因此请确保在部署环境中配置了DUB_API_KEY可在 Dub 后台的 Tokens 页面生成否则dub.track.lead会因缺少凭证而失败。三、核心工作流三步完成 Lead 事件上报指南给出的整体思路可以浓缩为以下三步检查dub_idCookie 是否存在存在说明该用户确实是通过 Dub 短链点击进入的具有归因价值判断是否为新注册用户通过user.created_at是否落在最近 10 分钟窗口内来判定避免老用户每次登录都重复上报上报 Lead 事件并清理 Cookie调用dub.track.lead把点击 ID 与用户身份绑定随后删除dub_idCookie。三步全部发生在 Supabase 的 Auth 回调中因为这是服务端唯一能同时拿到OAuth 用户信息 请求 Cookie的位置。四、完整实现在/api/auth/callback中上报 Lead以下为指南提供的完整代码并补充了关键注释说明// app/api/auth/callback/route.ts import { dub } from /lib/dub; import { createClient } from /lib/supabase/server; import { waitUntil } from vercel/functions; import { cookies } from next/headers; import { NextResponse } from next/server; export async function GET(request: Request) { const { searchParams, origin } new URL(request.url); const code searchParams.get(code); // if next is in param, use it as the redirect URL const next searchParams.get(next) ?? /; if (code) { const supabase createClient(cookies()); const { data, error } await supabase.auth.exchangeCodeForSession(code); if (!error) { const { user } data; const dub_id cookies().get(dub_id)?.value; // if the user is created in the last 10 minutes, consider them new const isNewUser new Date(user.created_at) new Date(Date.now() - 10 * 60 * 1000); // if the user is new and has a dub_id cookie, track the lead if (dub_id isNewUser) { waitUntil( dub.track.lead({ clickId: dub_id, eventName: Sign Up, customerExternalId: user.id, customerName: user.user_metadata.name, customerEmail: user.email, customerAvatar: user.user_metadata.avatar_url, }), ); // delete the clickId cookie cookies().delete(dub_id); } return NextResponse.redirect(${origin}${next}); } } // return the user to an error page with instructions return NextResponse.redirect(${origin}/auth/auth-code-error); }实现要点逐条拆解exchangeCodeForSession(code)Supabase Auth 的标准授权码交换流程。这里必须先于 Lead 上报完成因为只有拿到data.user才能获得created_at、user_metadata等判断与上报所需的用户信息。dub_id的读取时机务必在next/headers的cookies()上下文中读取且 Cookie 名保持与 Dub 客户端脚本写入的一致。isNewUser的 10 分钟窗口Date.now() - 10 * 60 * 1000是一个经验阈值用于容忍注册流程中可能存在的网络延迟与重定向耗时超过该窗口的用户会被视为老用户不会重复上报。waitUntil包裹上报来自vercel/functions它允许异步任务在响应返回后继续执行从而不阻塞注册回调的重定向把dub.track.lead变成发后即忘的后台任务。这与 Dub 的异步跟踪模式一脉相承见下文mode: async。customerExternalId: user.id以 Supabase 用户 ID 作为客户外部标识此后该用户的所有后续事件Sale 等都会以这个 ID 为准进行归因聚合。删除 Cookie 的时机在成功上报后立即删除保证同一个浏览器后续登录时不会再触发重复上报。五、dub.track.lead参数详解与可选字段指南示例使用了 6 个参数但 Dub 的 Lead 跟踪接口还支持更多可选字段。仓库的请求校验 Schema 定义在 apps/web/lib/zod/schemas/leads.ts各参数说明如下参数类型必填说明clickIdstring是点击的唯一 ID即从dub_idCookie 读取的值用于将 Lead 归因到具体点击eventNamestring是Lead 事件名称最长 255 字符同时可作为后续 Sale 事件关联的标识通过/track/sale的leadEventName属性customerExternalIdstring是你系统中客户的唯一 ID此处为 Supabaseuser.id最长 100 字符将作为该客户所有后续事件的归因主键customerNamestring否客户姓名最长 100 字符不传时 Dub 会生成随机名称如 Big Red CariboucustomerEmailstring否客户邮箱需符合 email 格式最长 100 字符customerAvatarstring否客户头像 URLmodeenum(async/wait/deferred)否默认async不阻塞当前请求wait阻塞直到 Lead 完全落库deferred延后到后续请求再创建eventQuantitynumber否事件数值如免费试用开通的席位数量设为 N 则该 Lead 会被记录 N 次范围 1-100metadataobject否附加元数据总长不超过 10,000 字符两个值得留意的细节clickId也支持延迟归因Schema 注释指出如果传入空字符串Dub 会尝试按customerExternalId查找已存在的客户并复用其clickId。这为回调中拿不到 Cookie的边缘场景提供了兜底方案。mode默认值是async这意味着即使不手动包一层waitUntildub.track.lead本身也设计为不阻塞调用方waitUntil的作用是让任务在响应返回后继续存活两者配合效果最佳。六、防重复上报的两种手段新用户窗口 Cookie 删除这套方案的健壮性建立在两道保险之上时间窗口过滤只对created_at在最近 10 分钟内的用户上报。即便回调被重放、或用户刷新页面只要不是新注册就不会再次上报。一次性 Cookie上报成功后立即cookies().delete(dub_id)。Cookie 被消费后即失效从根源上杜绝同一次点击产生多条 Lead 的可能。仓库自身的认证链路采用了同样的读 Cookie → 上报 → 删除模式作为佐证。在 apps/web/lib/auth/track-dub-lead.ts 中Dub 的 NextAuth 集成同样先读取dub_id调用dub.track.lead事件名同样为Sign Up然后删除dub_id与dub_partner_data两个 Cookie。这说明上报即删除是 Dub 官方集成的标准做法且合作伙伴归因数据dub_partner_data也会在同一步骤被清理避免敏感归因信息长期驻留浏览器。七、方案对比Supabase 与 NextAuth / Auth0 / Clerk 集成方式的异同本指南属于 Dub 认证集成系列中的一篇同一套dub_idCookie 归因心智模型在其他认证方案中均有对应实现可互相参照NextAuth在signIn事件回调中通过message.isNewUser判断新用户逻辑与本文的isNewUser等价但判断责任由 NextAuth 承担Auth0在afterCallback中通过数据库中是否已存在该邮箱用户来判断新旧同样读取dub_id、上报、删 CookieClerk走客户端 Server Action / API 路由路线用user.publicMetadata.dubClickId标记该用户是否已上报实现幂等。可以看到不同认证体系只是新用户判定与上报触发点不同核心的dub.track.lead({ clickId, eventName, customerExternalId, ... })调用与dub_idCookie 读取逻辑完全一致。这意味着你可以在多认证方案共存的架构中复用同一套归因上报封装。八、验证与排错建议完成接入后建议按以下顺序验证链路是否打通确认 Cookie 已种下先访问一条启用了转化跟踪的 Dub 短链在浏览器 DevTools 的 Application → Cookies 中确认dub_id或dub_id_{domain}_{key}已写入触发一次真实注册带着该 Cookie 完成 Supabase Auth 注册流程观察回调路由是否命中dub_id isNewUser分支检查请求与后台在 Network 面板确认存在发往 Dub 跟踪端点的请求并在 Dub 控制台的 Lead 事件分析中看到对应记录验证幂等性注册完成后再次登录同一账号确认没有产生第二条 Lead 记录——这同时验证了 10 分钟窗口与 Cookie 删除两道保险。若事件未上报优先排查DUB_API_KEY是否配置、dub_idCookie 是否在请求作用域内可读、user.created_at是否真的落在 10 分钟窗口内以及vercel/functions的waitUntil是否被正确引入。相关文档Dub 官方指南NextAuth 集成Dub 官方指南Auth0 集成Dub 官方指南Clerk 集成Dub 官方指南GTM 埋点跟踪Dub 官方指南手动调用 SDK / REST API 跟踪仓库内 Dub SDK 客户端实例仓库内 Lead 请求参数 Schema含全部字段约束仓库内短链中间件对dub_id_{domain}_{key}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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 在 Supabase Auth 回调中接入 Dub Lead 转化跟踪：从 `dub_id` Cookie 归因到 Sign Up 事件上报
在 Supabase Auth 回调中接入 Dub Lead 转化跟踪从dub_idCookie 归因到 Sign Up 事件上报【免费下载链接】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 开源仓库中的官方集成指南完整讲解如何在基于 Supabase 的 Next.js 应用里通过在/api/auth/callback回调路由中上报 Lead 转化事件把点击 Dub 短链 → 注册成为新用户这一链路以可归因的方式接入 Dub 的分析与归因体系。读完本文你将掌握dub.track.lead的完整调用方式、dub_idCookie 的来源与生命周期以及如何用 10 分钟新用户窗口精确区分新注册与老用户登录避免重复上报与归因污染。一、背景Dub 的转化归因模型为什么依赖dub_idDub 的转化归因Lead / Sale 归因核心思路是一次点击对应一个全局唯一的点击 IDclickId后续发生的转化事件必须携带该 ID 才能回溯到来源链接。在 Dub 的短链跳转链路中当用户点击一个启用了转化跟踪trackConversion的短链时服务端会为该次点击生成一个 16 位随机 IDnanoid(16)并以 Cookie 形式种在浏览器里。从仓库源码 lib/middleware/link.ts 可以看到这一机制的实现细节Cookie 的命名格式为dub_id_{domain}_{key}例如访问dub.sh/launch后浏览器会持有名为dub_id_dub.sh_launch的 Cookie只有当链接满足启用转化跟踪 / 合作伙伴链接 / Singular、AppsFlyer 跟踪 URL等条件时点击 ID 才会被缓存shouldCacheClickId从而支撑后续的/track/lead请求归因若命中 Redis 中缓存的点击记录会复用原 clickId否则新生成一个。而 Dub 的客户端分析脚本gtm-client-sdk.md 中提到的dubcdn.com/analytics/script.js与各类 SDK 在对外接口上统一将归因标识暴露为dub_idCookie。因此在应用服务端读取dub_idCookie就等价于拿到用户是经由哪一次 Dub 点击进入本站这一归因信息。二、集成前提准备好 Supabase 客户端与 Dub SDK在编写回调路由之前你的应用需要具备以下基础能力Supabase 服务端客户端用于在回调中通过exchangeCodeForSession完成 OAuth Code 换取会话。指南中的示例引用了/lib/supabase/server即应用内对 Supabase SSR 客户端的封装通常基于supabase/ssr的createServerClient实现并接收cookies()作为存储。Dub SDK 客户端指南中的import { dub } from /lib/dub对应应用内对 Dub TypeScript SDK 的实例化。仓库自身就是这么做的见 apps/web/lib/dub.tsimport { Dub } from dub; export const dub new Dub();new Dub()默认读取DUB_API_KEY环境变量作为鉴权凭据。因此请确保在部署环境中配置了DUB_API_KEY可在 Dub 后台的 Tokens 页面生成否则dub.track.lead会因缺少凭证而失败。三、核心工作流三步完成 Lead 事件上报指南给出的整体思路可以浓缩为以下三步检查dub_idCookie 是否存在存在说明该用户确实是通过 Dub 短链点击进入的具有归因价值判断是否为新注册用户通过user.created_at是否落在最近 10 分钟窗口内来判定避免老用户每次登录都重复上报上报 Lead 事件并清理 Cookie调用dub.track.lead把点击 ID 与用户身份绑定随后删除dub_idCookie。三步全部发生在 Supabase 的 Auth 回调中因为这是服务端唯一能同时拿到OAuth 用户信息 请求 Cookie的位置。四、完整实现在/api/auth/callback中上报 Lead以下为指南提供的完整代码并补充了关键注释说明// app/api/auth/callback/route.ts import { dub } from /lib/dub; import { createClient } from /lib/supabase/server; import { waitUntil } from vercel/functions; import { cookies } from next/headers; import { NextResponse } from next/server; export async function GET(request: Request) { const { searchParams, origin } new URL(request.url); const code searchParams.get(code); // if next is in param, use it as the redirect URL const next searchParams.get(next) ?? /; if (code) { const supabase createClient(cookies()); const { data, error } await supabase.auth.exchangeCodeForSession(code); if (!error) { const { user } data; const dub_id cookies().get(dub_id)?.value; // if the user is created in the last 10 minutes, consider them new const isNewUser new Date(user.created_at) new Date(Date.now() - 10 * 60 * 1000); // if the user is new and has a dub_id cookie, track the lead if (dub_id isNewUser) { waitUntil( dub.track.lead({ clickId: dub_id, eventName: Sign Up, customerExternalId: user.id, customerName: user.user_metadata.name, customerEmail: user.email, customerAvatar: user.user_metadata.avatar_url, }), ); // delete the clickId cookie cookies().delete(dub_id); } return NextResponse.redirect(${origin}${next}); } } // return the user to an error page with instructions return NextResponse.redirect(${origin}/auth/auth-code-error); }实现要点逐条拆解exchangeCodeForSession(code)Supabase Auth 的标准授权码交换流程。这里必须先于 Lead 上报完成因为只有拿到data.user才能获得created_at、user_metadata等判断与上报所需的用户信息。dub_id的读取时机务必在next/headers的cookies()上下文中读取且 Cookie 名保持与 Dub 客户端脚本写入的一致。isNewUser的 10 分钟窗口Date.now() - 10 * 60 * 1000是一个经验阈值用于容忍注册流程中可能存在的网络延迟与重定向耗时超过该窗口的用户会被视为老用户不会重复上报。waitUntil包裹上报来自vercel/functions它允许异步任务在响应返回后继续执行从而不阻塞注册回调的重定向把dub.track.lead变成发后即忘的后台任务。这与 Dub 的异步跟踪模式一脉相承见下文mode: async。customerExternalId: user.id以 Supabase 用户 ID 作为客户外部标识此后该用户的所有后续事件Sale 等都会以这个 ID 为准进行归因聚合。删除 Cookie 的时机在成功上报后立即删除保证同一个浏览器后续登录时不会再触发重复上报。五、dub.track.lead参数详解与可选字段指南示例使用了 6 个参数但 Dub 的 Lead 跟踪接口还支持更多可选字段。仓库的请求校验 Schema 定义在 apps/web/lib/zod/schemas/leads.ts各参数说明如下参数类型必填说明clickIdstring是点击的唯一 ID即从dub_idCookie 读取的值用于将 Lead 归因到具体点击eventNamestring是Lead 事件名称最长 255 字符同时可作为后续 Sale 事件关联的标识通过/track/sale的leadEventName属性customerExternalIdstring是你系统中客户的唯一 ID此处为 Supabaseuser.id最长 100 字符将作为该客户所有后续事件的归因主键customerNamestring否客户姓名最长 100 字符不传时 Dub 会生成随机名称如 Big Red CariboucustomerEmailstring否客户邮箱需符合 email 格式最长 100 字符customerAvatarstring否客户头像 URLmodeenum(async/wait/deferred)否默认async不阻塞当前请求wait阻塞直到 Lead 完全落库deferred延后到后续请求再创建eventQuantitynumber否事件数值如免费试用开通的席位数量设为 N 则该 Lead 会被记录 N 次范围 1-100metadataobject否附加元数据总长不超过 10,000 字符两个值得留意的细节clickId也支持延迟归因Schema 注释指出如果传入空字符串Dub 会尝试按customerExternalId查找已存在的客户并复用其clickId。这为回调中拿不到 Cookie的边缘场景提供了兜底方案。mode默认值是async这意味着即使不手动包一层waitUntildub.track.lead本身也设计为不阻塞调用方waitUntil的作用是让任务在响应返回后继续存活两者配合效果最佳。六、防重复上报的两种手段新用户窗口 Cookie 删除这套方案的健壮性建立在两道保险之上时间窗口过滤只对created_at在最近 10 分钟内的用户上报。即便回调被重放、或用户刷新页面只要不是新注册就不会再次上报。一次性 Cookie上报成功后立即cookies().delete(dub_id)。Cookie 被消费后即失效从根源上杜绝同一次点击产生多条 Lead 的可能。仓库自身的认证链路采用了同样的读 Cookie → 上报 → 删除模式作为佐证。在 apps/web/lib/auth/track-dub-lead.ts 中Dub 的 NextAuth 集成同样先读取dub_id调用dub.track.lead事件名同样为Sign Up然后删除dub_id与dub_partner_data两个 Cookie。这说明上报即删除是 Dub 官方集成的标准做法且合作伙伴归因数据dub_partner_data也会在同一步骤被清理避免敏感归因信息长期驻留浏览器。七、方案对比Supabase 与 NextAuth / Auth0 / Clerk 集成方式的异同本指南属于 Dub 认证集成系列中的一篇同一套dub_idCookie 归因心智模型在其他认证方案中均有对应实现可互相参照NextAuth在signIn事件回调中通过message.isNewUser判断新用户逻辑与本文的isNewUser等价但判断责任由 NextAuth 承担Auth0在afterCallback中通过数据库中是否已存在该邮箱用户来判断新旧同样读取dub_id、上报、删 CookieClerk走客户端 Server Action / API 路由路线用user.publicMetadata.dubClickId标记该用户是否已上报实现幂等。可以看到不同认证体系只是新用户判定与上报触发点不同核心的dub.track.lead({ clickId, eventName, customerExternalId, ... })调用与dub_idCookie 读取逻辑完全一致。这意味着你可以在多认证方案共存的架构中复用同一套归因上报封装。八、验证与排错建议完成接入后建议按以下顺序验证链路是否打通确认 Cookie 已种下先访问一条启用了转化跟踪的 Dub 短链在浏览器 DevTools 的 Application → Cookies 中确认dub_id或dub_id_{domain}_{key}已写入触发一次真实注册带着该 Cookie 完成 Supabase Auth 注册流程观察回调路由是否命中dub_id isNewUser分支检查请求与后台在 Network 面板确认存在发往 Dub 跟踪端点的请求并在 Dub 控制台的 Lead 事件分析中看到对应记录验证幂等性注册完成后再次登录同一账号确认没有产生第二条 Lead 记录——这同时验证了 10 分钟窗口与 Cookie 删除两道保险。若事件未上报优先排查DUB_API_KEY是否配置、dub_idCookie 是否在请求作用域内可读、user.created_at是否真的落在 10 分钟窗口内以及vercel/functions的waitUntil是否被正确引入。相关文档Dub 官方指南NextAuth 集成Dub 官方指南Auth0 集成Dub 官方指南Clerk 集成Dub 官方指南GTM 埋点跟踪Dub 官方指南手动调用 SDK / REST API 跟踪仓库内 Dub SDK 客户端实例仓库内 Lead 请求参数 Schema含全部字段约束仓库内短链中间件对dub_id_{domain}_{key}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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考