Dub 如何配置 Clerk 会话自定义声明并追踪新用户的注册转化事件

Dub 如何配置 Clerk 会话自定义声明并追踪新用户的注册转化事件【免费下载链接】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如果你的网站使用 Next.js 和 Clerk 做登录同时通过 Dub 短链接引流你需要让 Dub 知道这个新注册的用户来自哪一次链接点击。Dub 仓库中的 Clerk 集成指南apps/web/guides/clerk.md给出的方案是在用户注册后读取站点上的dub_idCookieDub 链接点击后写入的点击标识调用dub.track.lead上报一次 lead 事件然后把点击 ID 写回 Clerk 用户的publicMetadata避免重复上报。同时需要给 Clerk 会话令牌加一个自定义声明让会话 token 中携带用户的 public metadata。完成本指南后一个新用户从 Dub 链接进入站点并注册时Dub 会把他记录为 customer 并与那次点击事件关联参见同目录 NextAuth 指南对这一机制的说明dub_idCookie 随后被删除。准备工作指南代码依赖以下前提一个 Next.js 应用已接入 Clerk代码中用到clerk/nextjs的useUser与clerk/nextjs/server的clerkClient安装dub/analytics包。按 Dub 的 React 快速上手指南npm install dub/analytics在 Clerk 后台创建应用并拿到 Publishable Key 与 Secret Key指南注释指向 Clerk 后台的建应用页Dub 的 API Key 则从d.to/tokens页面获取。在应用中添加以下环境变量值需替换为你自己的密钥NEXT_PUBLIC_CLERK_PUBLISHABLE_KEYyour_publishable_key CLERK_SECRET_KEYyour_secret_key DUB_API_KEYyour_api_key给 Clerk 会话令牌添加自定义声明在 Clerk 的会话令牌配置中添加如下 JSON 作为自定义声明custom claim{ metadata: {{user.public_metadata}} }其中{{user.public_metadata}}是 Clerk 自定义声明的模板占位符由 Clerk 在签发令牌时替换为该用户的 public metadata无需手动替换。扩展dub/analytics组件Dub 的 React 包提供Analytics /组件负责点击等转化数据的采集。Clerk 指南要求包一层DubAnalytics组件用 Clerk 的useUserhook 拿到当前用户当用户已加载、但publicMetadata中还没有dubClickId时即尚未持久化到 Dub的新用户调用trackLeaduse client; import { trackLead } from /actions/track-lead; import { useUser } from clerk/nextjs; import { Analytics, AnalyticsProps } from dub/analytics/react; import { useEffect } from react; export function DubAnalytics(props: AnalyticsProps) { const { user } useUser(); useEffect(() { if (!user || user.publicMetadata.dubClickId) return; // if the user is loaded but hasnt been persisted to Dub yet, track the lead event trackLead({ id: user.id, name: user.fullName!, email: user.primaryEmailAddress?.emailAddress, avatar: user.imageUrl, }).then(async (res) { if (res.ok) await user.reload(); else console.error(res.error); }); }, [user]); return Analytics {...props} /; }然后把DubAnalytics挂到应用根布局中import { DubAnalytics } from /components/dub-analytics; export default function RootLayout({ children, }: { children: React.ReactNode; }) { return ( html body DubAnalytics / {children} /body /html ); }实现trackLeadserver action在服务端实现被组件调用的trackLead。它的逻辑是读取dub_idCookie若存在则以它作为clickId调用dub.track.lead上报事件名为Sign Up的 lead 事件并把 Cookie 置为过期删除随后用clerkClient把dubClickId写入该用户的publicMetadata最后返回{ ok: true }出错时返回{ ok: false, error }// This is a server action use server; import { dub } from /lib/dub; import { clerkClient } from clerk/nextjs/server; import { cookies } from next/headers; export async function trackLead({ id, name, email, avatar, }: { id: string; name?: string | null; email?: string | null; avatar?: string | null; }) { try { const cookieStore await cookies(); const dubId cookieStore.get(dub_id)?.value; if (dubId) { // Send lead event to Dub await dub.track.lead({ clickId: dubId, eventName: Sign Up, customerExternalId: id, customerName: name, customerEmail: email, customerAvatar: avatar, }); // Delete the dub_id cookie cookieStore.set(dub_id, , { expires: new Date(0), }); } const clerk await clerkClient(); await clerk.users.updateUser(id, { publicMetadata: { dubClickId: dubId || n/a, }, }); return { ok: true }; } catch (error) { console.error(Error in trackLead:, error); return { ok: false, error: (error as Error).message }; } }代码中的/lib/dub是你自己项目里导出 Dub 客户端实例的模块。参考 Dub 的 手动追踪 Lead 指南客户端用dub包创建token参数可省略、默认读取DUB_API_KEY环境变量import { Dub } from dub; export const dub new Dub({ // optional, defaults to the DUB_API_KEY environment variable token: process.env.DUB_API_KEY, });可选分支用 API 路由代替 server action指南同时给出 API 路由方案。客户端侧把trackLead调用换成fetch(/api/track-lead, ...)请求体即用户字段fetch(/api/track-lead, { method: POST, body: JSON.stringify({ id: user.id, name: user.fullName, email: user.primaryEmailAddress?.emailAddress, avatar: user.imageUrl, }), }).then(res { if (res.ok) await user.reload(); else console.error(res.statusText); });服务端路由的职责与 server action 相同从req.cookies读取dub_id存在时上报 lead 事件调用clerk.users.updateUser写入dubClickId在响应上把dub_idCookie 置为过期并返回{ ok: true }。注意指南原文的路由代码直接引用了id、name、email、avatar变量实现时需要先解析请求 JSON body 得到这些字段即客户端fetch发送的字段。验证与结果判断指南给出的成功与失败判定来自trackLead的返回值成功返回{ ok: true }客户端useEffect中的.then检测到res.ok后调用user.reload()重新拉取用户数据——此时该用户的publicMetadata.dubClickId已被写入有 Cookie 时为实际点击 ID没有时为n/a。失败返回{ ok: false, error }客户端把res.error打印到控制台。另外两个可在浏览器侧核对的状态均来自指南代码的行为事件上报成功后dub_idCookie 被删除expires: new Date(0)同一点击不会二次触发上报组件开头有if (!user || user.publicMetadata.dubClickId) return;所以已写入dubClickId的用户在后续访问中不会再触发trackLeadlead 事件每次注册只发送一次。边界说明上报以dub_idCookie 存在为前提用户若没有经过 Dub 链接进入站点事件不会上报只会把dubClickId写成n/a。指南代码基于 Next.js 特性next/headers的cookies()、server actions适用于 Next.js 应用。如果不想走前端组件Dub 也支持直接用 TypeScript SDK 或 REST APIhttps://api.dub.co/track/leadAuthorization: Bearer dub_xxxxxx手动上报 lead 事件详见 manual-track-lead.md 与 rest-api.md。【免费下载链接】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），仅供参考