怎么在 Next.js 上安装 TapCub？

简短回答

在根布局的 head 里加一次 TapCub 脚本标签（app router 是 app/layout.tsx，pages router 是 pages/_document）。app router 的跳转会自动记录。tapcub 只能在客户端组件里调用，服务端组件和 server action 里没有 tapcub。

站点密钥在 网站统计 › 配置 › SDK 代码 里。

1. 只加一次脚本

app router，把标签放在根布局的 head 里：

// app/layout.tsx
export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="zh">
      <head>
        <script defer src="https://static.pathclue.com/client.js" data-site="YOUR_SITE_KEY" />
      </head>
      <body>{children}</body>
    </html>
  )
}

pages router 把同一个标签放在 pages/_document 的 head 里。不要在页面组件里再输出一次。

脚本会在浏览器里自己启动。不要在组件里再创建或注入一次；重复插入会被忽略。

2. 页面浏览和路由切换

首次加载和之后使用 history 模式的路由切换，都会自动发送。app router 的客户端跳转走浏览器 history，后续的页面浏览不用写代码也会发送。

想自己发送页面浏览，在脚本上设置 data-auto-track="false"，并在每次路由完成后调用 tapcub.pageview()。注意这也会关掉自动的外链和下载点击、Web Vitals 和 404 事件。见在单页应用上安装。

3. 事件和登录

tapcub.track('purchase', { revenue: 19.9 });

在客户端组件（文件开头写 "use client"）里调用，比如放在点击处理函数里。服务端组件和 server action 运行的地方没有 tapcub。事件名超过 100 个字符会被截断；最多保留 20 个属性，键名截到 50 个字符、字符串值截到 200 个字符。属性值只保留字符串、数字和布尔值。

用户登录后，把访客和你的用户 ID 关联起来：

tapcub.login(userId, { plan: 'pro' }, { type: 'login' });

login 来自身份脚本，调用前先确认它存在。详见识别用户。

检查是否生效

localhost 这类本地主机名默认不发送，很容易被误以为安装失败。在部署好的预览地址或线上网站测试，看浏览器网络面板里的采集请求，然后按检查安装确认。

常见问题

不是用 Next.js？见安装 TapCub。