# @cookie3/analytics 中文文档

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

版本：0\.6\.0
npm 元数据更新时间：2023-09-28T21:02:15.856Z
中文译文更新时间：2026-11-10T19:50:40.615Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40cookie3/analytics
原文对照：https://npmcn.com/package/%40cookie3/analytics/?lang=original

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

- 包体积（解压后）：529 kB，27 个文件
- 模块格式：CommonJS
- TypeScript 类型：包内自带
- 运行依赖：0 个
- 首次发布：2023-09-08T13:12:16.946Z
- 最新版本发布：2023-09-28T21:02:15.691Z
- 近 30 天下载量：3039（2026-10-11 至 2026-11-09，npm 官方下载统计）
- 已发布版本数：14（近 12 个月 0 个）

## 中文简介

Cookie3分析插件是一个多功能工具,旨在为Cookie3客户端简化网站添加跟踪的过程. 无论是与传统代码库合作还是与框架lik构建的现代单页应用程序(SPA)合作

## 安装

```sh
npm install @cookie3/analytics
```

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

## README

# 概览

Cookie3分析插件是一个多功能工具,旨在为Cookie3客户端简化网站添加跟踪的过程. 无论是与传统代码库合作,还是与Next.js,React,或Nuxt等框架相构建的现代单页应用程序(SPA)合作,这个库提供了您需要的集成的灵活性和方便.

## 特征

-   跨框架相容性:与各种网络开发框架和库,包括Next.js,React,Nuxt等,工作无缝.
-   通用跟踪(Universal Tracking):提供统一的API,用于跟踪不同类型网络应用程序的用户互动,事件等计量.
-   自定义跟踪: 轻松配置跟踪参数和事件以适应您特定的分析要求.
-   同步加载:通过同步加载跟踪脚本,确保最小影响您网站的性能.
-   实时数据:通过Cookie3仪表板获取实时分析数据,用于知情决策.

## 安装

您可以通过 npm 或 纱线安装 Cookie3 分析插件 :

```bash
npm install @cookie3/analytics
```

或者说

```bash
yarn add @cookie3/analytics
```

## 开始

> 通知: Cookie3 分析插件需要有效的 Cookie3 `siteId` 工作的时候。 如果你没有Cookie3账户,你可以 [在这里注册免费账户](https://app.cookie3.co/)。 。 。 .

### 在 Cookie3 中注册网站

> 注意: 如果您已经注册了 Cookie3 的网站, 请跳过此步骤 .

在开始追踪网站分析之前,需要用Cookie3注册网站. 为此,遵循这些步骤:

1.  登录到您的 Cookie3 账户 .
2.  转到 [/数据来源](https://app.cookie3.co/data-sources) 页 次.
3.  点击整合网站按钮.
4.  在下页,点击右上角"添加新网站"按钮.
5.  输入您的网站的 URL 和名称, 然后点击“ Add site” 按钮 .
6.  从脚本片段复制站点ID并保存到以后.

您现在可以开始使用 Cookie3 分析插件跟踪您的网站的分析.

#### 获取现有网站的标识

如果您已经在 Cookie3 注册了网站, 您可以通过下列步骤获取其网站ID :

打开 [/数据来源](https://app.cookie3.co/data-sources) 页面中,单击“整合网站”按钮。 您应当查看您的网站在页面上列出。 点击网站名称旁的"查看脚本"按钮. 您应该看到一个脚本片段 与您的网站的ID。 复制站点标识并保存到稍后.

## 使用量

### 1\. 进口图书馆

导入库到您的工程开始使用 :

```ts
import { cookie3Analytics } from "@cookie3/analytics";
```

### 2\. 图书馆的初始化

初始化库与您的 `siteId` 从 Cookie3 键 :

```ts
const analytics = cookie3Analytics(options);
```

这个 `options` 参数是一个接受以下属性的对象:

| 财产 | 类型 | 说明 |
| --- | --- | --- |
| `siteId` | `number` | 你的Cookie3网站身份证. |
| `disabled` | `boolean` | 是否禁用跟踪 。 默认为 `false`。 。 。 . |
| `autoDetectWalletAddresses` | `boolean` | 是否在页面中自动检测钱包地址并跟踪它们 。 默认为 `true`。 。 。 . |
| `autoDetectWalletExtensions` | `boolean` | 是否在页面中自动检测钱包扩展并跟踪它们 。 默认为 `true`。 。 。 . |
| `heartBeat` | `active: boolean; seconds?: number;` | 是否启用心脏跳动跟踪和间隔数秒 。 这个选项能够更准确地跟踪访问时间。 默认间隔被设定为10秒. 默认为 `undefined`。 。 。 . |
| `linkTracking` | `boolean` | 是否启用链接跟踪 。 默认为 `true`。 。 。 . |
| `disableCookies` | `boolean` | 是否禁用 cookie 。 默认为 `false`。 。 。 . |
| `staging` | `boolean` | 是否使用中转环境 。 默认为 `false`仅供内部使用. |

### 3\. 音轨页面视图

#### 重要信息

当使用 Cookie3 分析插件时, 所有跟踪的页面视图都被程序化注册了, 所以您需要调用 `trackPageView` 方法.

开始追踪页面浏览, 通过呼叫库 `trackPageView` 方法 :

#### 跟踪页面视图

```javascript
analytics.trackPageView();
```

默认情况下 `trackPageView` 方法将自动跟踪当前页面的URL和标题。 您也可以通过自定义参数来覆盖默认值 :

```javascript
analytics.trackPageView({
  documentTitle: "Custom title",
  href: "https://example.com",
});
```

> 说明: `trackPageView` 方法应该调用到每一页的负载.

### 4\. 轨迹活动

通过调用库的跟踪方法开始跟踪事件和用户互动:

```javascript
analytics.trackEvent({
  category: "Call to action",
  action: "Click",
  value: 200,
});
```

> 说明: `value` 参数是可选的,用于跟踪事件的财务价值. 例如,如果你正在跟踪一个购买事件,你可以通过购买总额作为 `value` 参数.

## 如何运作

库向 Cookie3 API 发送请求,以跟踪页面视图,事件和用户互动. API然后处理请求并存储到Cookie3数据库中. 然后可以通过Cookie3仪表板访问数据.

#### 白列 Cookie3 API 域名

Cookie3分析插件向Cookie3 API域发送请求. 如果您在您的网站上使用内容安全政策(CSP),则需要将 Cookie3 API 域名白列,以便插件正常工作. Cookie3 API 域名为 `webanalytics.cookie3.co`。 。 。 .

## 用下个.js/反应

1.  创建上下文提供者, 在您的 React app 中提供实例 :

```tsx
import { type Cookie3Analytics } from "@cookie3/analytics";
import { createContext, useContext } from "react";

export interface ProviderProps {
  children?: React.ReactNode;
  value: Cookie3Analytics;
}

const Cookie3Context = createContext<Cookie3Analytics | undefined>(undefined);

export const Cookie3Provider = ({ children, value }: ProviderProps) => {
  return (
    <Cookie3Context.Provider value={value}>{children}</Cookie3Context.Provider>
  );
};

export const useCookie3 = () => {
  const context = useContext(Cookie3Context);

  return context;
};
```

2.  在您初始化此实例 `_app.tsx` 文件 :

```tsx
import type { AppProps } from "next/app";

import { UserOptions, cookie3Analytics } from "@cookie3/analytics";
import { Cookie3Provider } from "@/hooks/useCookie3Analytics";

const config: UserOptions = {
  siteId: YOUR_SITE_ID,
};

const analytics = cookie3Analytics(config);

export default function App({ Component, pageProps }: AppProps) {
  return (
    <Cookie3Provider value={analytics}>
      <Component {...pageProps} />
    </Cookie3Provider>
  );
}
```

3.  您组件中的跟踪事件 :

```tsx
const cookie3 = useCookie3();

useEffect(() => {
  cookie3?.trackPageView();
}, []);
```

## 常见问题

### @cookie3/analytics 是什么？

Cookie3分析插件是一个多功能工具,旨在为Cookie3客户端简化网站添加跟踪的过程\. 无论是与传统代码库合作还是与框架lik构建的现代单页应用程序\(SPA\)合作

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

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

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

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

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

以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。

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

@cookie3/analytics 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

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

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

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

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