# @dub/analytics 中文文档

规范地址：https://npmcn.com/package/%40dub/analytics/

版本：0\.0\.33
npm 元数据更新时间：2026-11-11T21:07:18.765Z
中文译文更新时间：2026-11-12T23:32:21.962Z
软件包许可：MPL-2\.0

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40dub/analytics
原文对照：https://npmcn.com/package/%40dub/analytics/?lang=original
项目主页：https://github.com/dubinc/analytics#readme
源码仓库：https://github.com/dubinc/analytics

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：114 kB，21 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：1 个
- 首次发布：2024-02-13T21:04:06.438Z
- 最新版本发布：2026-11-11T21:07:18.574Z
- 近 30 天下载量：751730（2026-10-13 至 2026-11-11，npm 官方下载统计）
- 已发布版本数：30（近 12 个月 1 个）

## 中文简介

`@dub/analytics` 允许您追踪 Dub 的线索和销售转换.

## 安装

```sh
npm install @dub/analytics
```

也可以使用：`pnpm add @dub/analytics`、`yarn add @dub/analytics`、`bun add @dub/analytics`

## README

## 概览

`@dub/analytics` 允许您追踪 Dub 的线索和销售转换.

## 快开始

1.  启用您的 Dub 链接的转换跟踪 .
2.  安装 `@dub/analytics` 软件包到您的工程

```bash
npm install @dub/analytics
```

3.  将分析脚本注入您的应用程序

```tsx
import { Analytics as DubAnalytics } from '@dub/analytics/react';

export default function RootLayout({
  children,
}: Readonly<{
  children: React.ReactNode;
}>) {
  return (
    <html lang="en">
      <body>{children}</body>
      <DubAnalytics />
    </html>
  );
}
```

你们都可以使用 `inject()` 函数将跟踪脚本添加到其他框架.

## 可用的道具

你可以将以下道具传递给 `Analytics` 用于自定义跟踪脚本的组件.

### `apiHost`

用于跟踪的API主机. 这对于设置反向代理以避免被阻塞有用. 默认是 `https://api.dub.co`。 。 。 .

### `domainsConfig`

这是配置 Dub 将跟踪的域的 JSON 对象 .

-   `refer`: Dub 的短域 [推荐程序客户端点击跟踪](https://d.to/clicks/refer) (先前为 `shortDomain`) (中文(简体) ).
-   `site`: Dub 的短域 [跟踪实地访问](https://d.to/clicks/site)。 。 。 .
-   `outbound`: 用于跨域跟踪的一系列域. 配置时,已有 `dub_id` cookie将自动被附加到针对这些域的所有出行链接上,以便能够跨域跟踪不同应用程序.

### `shortDomain`

\[已删除:使用 `domainsConfig.refer` 转而 您在 Dub 上为您的短链接使用的自定义短域( 用于客户端点击跟踪) .

### `attributionModel`

决定用于跟踪的归属模型. 默认是 `last-click`。 。 。 .

-   `first-click` - 第一次点击模式将所有的功劳都归功于客户旅程中的第一个触点.
-   `last-click` - 最后一个点击模式将所有功劳都归功于客户旅程中最后一个触点.

### `cookieOptions`

这个 `cookieOptions` prop 接受以下密钥 :

| 密钥 | 默认 | 说明 | 示例 |
| --- | --- | --- | --- |
| `domain` | `null` | 指定 `Domain` Set-Cookie属性. | `example.com` |
| `expires` | 90天后,我们再走 | 指定 `Date` 对象为 `Expires` Set-Cookie属性. | `new Date('2024-12-31')` |
| `expiresInDays` | `90` | 指定数值( 天数) 为 `Expires` Set-Cookie属性. | `90` |
| `path` | `/` | 指定 `Path` Set-Cookie属性. 默认情况下,路径被认为是"默认路径". | `/` |

例如,要设置一个60天的饼干窗口,可以使用以下代码:

```tsx
import { Analytics as DubAnalytics } from "@dub/analytics"

<DubAnalytics
   cookieOptions={{
      expiresInDays: 60,
   }}
/>
```

### `queryParam`

用于客户端点击跟踪的查询参数(例如. `?via=john`, (中文(简体) ), `?ref=jane`) (中文(简体) ). 默认是 `via`。 。 。 .

### `trackIdentityPaths`

在给定的路径上识别访客设备,并将其链接到他们的 Dub 点击,以进行伴侣风险监测.

路径完全匹配( 后面的斜线被忽略 ) 。 尾声 `/*` 也匹配路径下的一切,所以 `/checkout/*` 匹配 `/checkout` 财务报告和审定财务报表 `/checkout/plan`。它运行在第一页负载和客户端导航到匹配路径上.

它只用于客户端合作伙伴点击,跟踪 `?via=` 或您设置的参数 `queryParam` (这样定) `domainsConfig.refer`) (中文(简体) ). 该点击设置 `dub_partner_data` cookie, 脚本仅在该 cookie 属于点击时识别 `dub_id`。点击建议和网站点击被跳过,所以它们从不使用指纹.

它每点击一次运行:在识别后,它会将设备的访客ID附加到饼干上(cookie)`dub_id=<clickId>_<visitorId>`) (中文(简体) ). 新的点击可以替换饼干并再次被识别. `trackLead` 财务报告和审定财务报表 `trackSale` 发送全部值, 因此 Dub 可以将客户端链接到设备中; 通过 cookie , 就像您从服务器跟踪转换时一样 。 脚本为出行链接去掉后缀,在其它地方读取 `dub_id` 自己做曲奇,点击ID是前面的部分 `_`。设备识别代理只有在识别运行时才被装入,失败者从未丢出或屏蔽页面.

身份识别需要封存客户端结果在指纹工作区被关闭,因此代理机返回访客身份识别.

```tsx
<DubAnalytics trackIdentityPaths={['/signup', '/checkout/*']} />
```

为了有条件地识别,拨打 `trackIdentity` 你自己来 也一样 `dub_id` 规则和需要 `trackIdentityPaths` 加载身份变体的道具( p)`trackIdentityPaths={[]}` 关闭自动识别).

在法律要求设备指纹鉴定同意的情况下,使用 `trackIdentityPaths={[]}` 打电话 `trackIdentity()` 只有在来访者同意之后。 剧本没有自己的同意或选择退出设置. 先打个电话,待会再说 `?via=` 点击,它不能被取消,所以如果在等待期间撤回同意,身份识别仍然可以开始.

```tsx
const { trackIdentity } = useAnalytics();

await trackIdentity();
```

没有反应,请使用 `identity` 脚本变体( e)`script.identity.js`,或组合起来类似 `script.site-visit.identity.js`) (中文(简体) ). 设置路径为 `data-track-identity-paths` 属性和调用 `dubAnalytics.trackIdentity()`中,添加 `trackIdentity` 到片段的方法列表.

```html
<script
  src="https://www.dubcdn.com/analytics/script.identity.js"
  data-track-identity-paths='["/signup", "/checkout/*"]'
  defer
></script>
```

设备识别代理从 `identity-agent.js` 脚本旁边。 如果您从自己的域名或代理服务脚本, 请服务 `identity-agent.js` 从同一个文件夹.

### `scriptProps`

自定义要传递到脚本标记的属性 。 参见 [MDN 数据](https://developer.mozilla.org/en-US/docs/Web/API/HTMLScriptElement) 用于所有可用的选项.

## 常见问题

### @dub/analytics 是什么？

@dub/analytics 允许您追踪 Dub 的线索和销售转换\.

### 如何安装 @dub/analytics？

在项目目录运行 npm install @dub/analytics，或使用 pnpm add / yarn add / bun add。

### @dub/analytics 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @dub/analytics 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @dub/analytics 可以商用吗？

@dub/analytics 使用 MPL-2\.0 许可。弱 Copyleft：可以商用，也可以和闭源代码一起使用；但如果分发时修改了 MPL 授权的文件，这些文件的修改需以 MPL 开源。以上为概括，不构成法律意见，请以许可原文为准。

### @dub/analytics 的下载量有多少？

根据 npm 官方下载统计，@dub/analytics 在 2026/10/13 – 2026/11/11 这 30 天内被下载 751,730 次，日均约 25,058 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @dub/analytics 还在维护吗？

最新版本 0\.0\.33 发布于 2026/11/12（1 天前）；至今共发布 30 个版本，其中过去 12 个月发布了 1 个；首次发布于 2024/02/14。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。