# @faststats/web 中文文档

规范地址：https://npmcn.com/package/%40faststats/web/

版本：0\.15\.1
npm 元数据更新时间：2026-11-08T21:37:19.944Z
中文译文更新时间：2026-11-14T11:29:53.899Z
软件包许可：未声明

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

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

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

- 包体积（解压后）：93.7 kB，17 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：4 个
- 首次发布：2026-03-15T11:57:08.898Z
- 最新版本发布：2026-11-08T21:37:19.765Z
- 近 30 天下载量：3802（2026-10-15 至 2026-11-13，npm 官方下载统计）
- 已发布版本数：55（近 12 个月 55 个）

## 中文简介

> \[有重大意义\] 这个储存库处于早期开发阶段,并不打算用于生产.

## 安装

```sh
npm install @faststats/web
```

也可以使用：`pnpm add @faststats/web`、`yarn add @faststats/web`、`bun add @faststats/web`

## README

## FastStats 网络分析核心

> \[大 这个储存库处于早期开发阶段,并不打算用于生产.

基础 SDK 处理分析、 身份、 会话、 导航、 输出链接 点击,同意. 错误跟踪、 Web Vitals、 会话重放、 特征标记是独立的 扩展,所以应用程序只下载它们使用的产品.

```ts
import { init, track } from "@faststats/web";
import { errorTracking } from "@faststats/web/error";
import { sessionReplay } from "@faststats/web/replay";
import { webVitals } from "@faststats/web/web-vitals";

init({
    siteKey: "site_123",
    extensions: [
        errorTracking(),
        webVitals(),
        sessionReplay({ recordConsole: true }),
    ],
});

track("checkout_completed", { total: 42 });
```

`init()` 启动一个共享客户端并具有同位素,从而安全地从 应用程序拖带代码。 在初始化之前发出的呼吁被忽略了 而不是带有僵硬上下文的缓冲。 使用 `shutdown()` 初始化前使用新程序 选项.

对于多个站点,测试或框架集成,创建一个独立的站点 具有明确生命周期控制的客户端:

```ts
import { createClient } from "@faststats/web";

const analytics = createClient({ siteKey: "site_123" });
analytics.start();
analytics.track("checkout_completed", { total: 42 });
analytics.destroy();
```

当地客户同意:使用 `"anonymous"` 为无饼干收藏, `"granted"` 用于普通收藏,或 `"denied"` 让客户保持休眠.

### 身份和特征

`identify()` 链接访问者到您的用户ID,并设置配置字段和 特质. `traits` 覆盖现有值; `traitsOnce` 只填写特征 人还没有.

```ts
import { identify, setTraits, unsetTraits } from "@faststats/web";

await identify("user_123", "ada@example.com", {
    traits: { plan: "free" },
    traitsOnce: { signupSource: "reddit" },
});

await setTraits({ plan: "pro" });
await setTraits({ firstFeature: "export" }, { mode: "setOnce" });
await unsetTraits(["legacyPlan"]);
```

成功过后 `identify()`,该用户ID存储在匿名地址旁边 访客身份证明,并作为 `externalId` 以每件事物、每一件事物、每一件事物、每一件事物、每一件事物、每一件事物, 所以收藏家知道谁是访客 使用不透明的ID而不是电子邮件 地址 电话. `getExternalId()` 返回,或 `""` 在此之前 `identify()`输入 无饼干模式,同时拒绝同意. `logout()` 和拒绝同意 永远忘了它。 Cookieless客户从不存储或发送.

一个 `identify()` 与本次浏览器会话中上次发送的相同 相同的匿名访客, 没有队列特征变化, 解析 `true` 无 请求,所以调用它 每一个页面负荷是便宜的。 过 `force: true` 永远 发送.

`setTraits()` 财务报告和审定财务报表 `unsetTraits()` 更新身份识别的访客,不包含 一个完整的身份证明。 它们适用于最新的用户 `identify()` 打电话,甚至 当它的请求在逃时 在此之前 `identify()`,更改保留在内存中 对于当前页面,并按顺序在下次成功之后发送 `identify()`类似 `identify()`他们决定 `false` 再不送进去 无饼干模式.

### 访问时间

`properties.time_on_page` 打开 `$page_ping` 财务报告和审定财务报表 `$page_leave` 是累积的 以毫秒表示的页面可见,其文档有焦点。 当标签是时会暂停 隐藏,窗口失去焦点,或者页面进入后向缓存,以及 在导航、登出或会话旋转时重新发送。 单调的钟表 系统时钟的变化不会影响这一持续时间。 60后也暂停 秒没有指针、键盘或滚动输入,除非 `<video>` 或者说 `<audio>` 元素在页面上播放,并恢复下一个输入。 时间 用于睡眠或被冻结的标签不计算.

页面视图等待页面可见 。 已替换或关闭的页面 显示时不显示页面视图或页外事件.

SDK发送一个累积 `$page_ping` 当活动暂停和定期 活动时:15和45秒后,每60秒一次。 增加不的接力 时间被压制。 访问结束 一个 `$page_leave`在导航上,一个终端 `pagehide`,登录,同意 更改,或会话旋转。 浏览器在无通知的情况下丢弃的一页 发送一个,所以它的最后一个接力维持其持续时间。 页面视图,它的收音机 休假份额 `properties.visit_id`;消费者应使用最大 `time_on_page` 每一次访问 跨越两次事件, 永远不要将它们相加.

在0.13之前,这些小叮当被发送到 `page_leave` 每15秒钟。 那个收藏家 和仪表板读取两种形状;在释放出这个SDK之前部署.

### 内建事件名称

SDK发送自己的事件作为 `$pageview`, (中文(简体) ), `$page_ping`, (中文(简体) ), `$page_leave`, (中文(简体) ), `$outbound_link`,以及 `$error`名称 `$` 预留用于 内建事件,所以 `track()` 无视他们,并警告每个名字一次 操纵台 其他名称,包括: `pageview` 或者说 `error`,是一个自定义事件.

每个有效载荷 `protocol: 2`。年长的 SDK 发送内建事件没有 前缀; 收藏家重命名这些事件, 因此旧版本继续工作.

### 默认上下文

每件事都带 `timezone` (IANA名称), `language`,以及 `screen` (单位:千美元)`1920x1080`, CSS 像素)在页面上下文旁,与其属性相分离. 自定义事件和外出链接也载有 `visit_id` 页面视图 发生期间.

每次访问都保留其原始身份、会话和页面元数据。 届会 或者改变身份开始新的访问, 即使在同一条路线上。 两者都是持久性的 无饼干会议在30分钟后或24小时后失效.

`session_duration` 从会话开始到最后的时长 计算活动。 它包括相同两个活动期间之间的时间间隔 语句,因此它与页面上的活跃时间是分开的。 闲来客停了 延长会期,然后与任何其他会议一样在30分钟后结束.

交付是最佳努力:突然过程死亡或网络故障可能失去时间 自从上次送货以来 收藏家必须接受连续的事件 用于同一访客和URL; 部署删除其五秒钟的解禁 在释放SDK之前.

### 地物标志

`featureFlags()` 为访问者加载工程的旗帜、 客户端音轨和 与内存同步解决它们 :

```ts
import { init } from "@faststats/web";
import { featureFlags } from "@faststats/web/flags";

const flags = featureFlags();
init({ siteKey: "site_123", extensions: [flags] });

await flags.ready();
if (flags.isEnabled("new-checkout")) showNewCheckout();
const maxUploads = flags.get("max-uploads", 10);
```

一面旗子算作首次曝光的应用读取服务值 `get()`, (中文(简体) ), `isEnabled()` 或者说 `details()`,不是当它装入。 读者发送到 小批量和页面隐藏, 所以仪表板的曝光号显示 人们实际上看到了旗帜。 在装入或丢失时读取默认值 旗帜,不是暴露.

对匿名访客的标记进行评估,会议ID将每个标记联系起来 评估到分析. `identify()` 重新评价了他们的用户,所以 推出时跟踪用户跨设备,以及 `logout()` 回到一个新的 匿名访客 当用户在启动时被知道时,通过 `userId` 跳过 匿名负载。 没有饼干的访客没有永久的身份证 所以推出时间是 仅限届会。 同意时未加载旗帜 `"denied"`,并撤销 同意减少尚未发出的接触.

`get()` 返回在加载旗帜时在呼叫站点通过的默认值,以及 当旗帜不存在时,存档,有不同的类型,或者服务 无法在 `timeoutMs`。 。 。 . `details(key)` 添加变体和理由 (单位:千美元)`rule_match`, (中文(简体) ), `target_match`, (中文(简体) ), `fallthrough`, (中文(简体) ), `disabled`, (中文(简体) ), `prerequisite_failed`) (中文(简体) ).

```ts
flags.subscribe(() => render(flags.status)); // "idle" | "loading" | "ready" | "error"
await flags.setContext({ attributes: { plan: "pro" } });
await flags.reload();
```

| 选项 |  |
| --- | --- |
| `flags` | 仅装入这些密钥, 用于带有多面旗帜的项目 . |
| `userId` | 您的注册用户身份, 当启动时已知 . |
| `attributes` | 任何目标设定规则都应该遵守. |
| `endpoint` | 旗下服务的基础 URL, 当自运行时. |
| `timeoutMs` | 中止较慢的负载。 默认为 `3000`。 。 。 . |
| `fetch` | A 类 `fetch` 执行,而不是全球. |

#### 已打入标记

从项目的旗帜中生成类型 [快报CLI](https://www.npmjs.com/package/@faststats/cli)数字 :

```sh
faststats flags typegen my-project
```

这个写着 `faststats-flags.d.ts` (进) `src/` 当有一个人的时候 每一个活跃的旗帜 和它所能服务的价值。 键然后自动补全, 打字或 存档的旗帜无法编译, 数值按其变体键入 :

```ts
flags.get("theme", "system"); // "light" | "dark" | "system"
flags.isEnabled("theme"); // error: not a boolean flag
```

默认会加入结果类型, 因为它符合加载服务 。 运行 更改后再次命令,或添加 `--check` 在 CI 中,当 文件已过时。 没有文件,任何密钥都会被接受,结果就是 默认键入.

### 网络记录在会话重播

网络记录默认被禁用. 启用它 `sessionReplay({ recordNetwork: true })`此记录资源 URL 和时间 使用rrweb网络插件的数据。 标题和正文不默认记录. FastStats 收藏端点(包括自定义) `baseUrl`总是被排除在外 防止录制回放上传.

使用 `networkOptions` 以配置 rrweb 插件,包括过滤或编辑:

```ts
sessionReplay({
    recordNetwork: true,
    networkOptions: {
        initiatorTypes: ["fetch", "xmlhttprequest"],
        transformRequestFn: (request) => {
            const url = new URL(request.name);
            if (url.pathname.startsWith("/private/")) return;
            url.search = "";
            request.name = url.toString();
            return request;
        },
    },
});
```

`recordHeaders`, (中文(简体) ), `recordBody`,以及 `recordInitialRequests` 也可以设置在 `networkOptions`。在启用标题或机体之前编辑敏感数据. 仅网络选项无法录制 。 同样的回放选项是 通过 React 和 Nuxt 集成提供.

### 自定义扩展名

扩展只登记它所需要的生命周期钩. 虎克失败了 一个同步的设置在拆解时是安全的, 并收到清理 `discard: true` 取消同意时.

```ts
import type { AnalyticsExtension } from "@faststats/web";

export function diagnostics(): AnalyticsExtension {
    return {
        name: "diagnostics",
        setup(context) {
            const off = context.on("pageChange", ({ url }) => {
                console.debug("page changed", url);
            });

            return () => off();
        },
    };
}
```

## 常见问题

### @faststats/web 是什么？

\[有重大意义\] 这个储存库处于早期开发阶段,并不打算用于生产\.

### 如何安装 @faststats/web？

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

### @faststats/web 支持 TypeScript 吗？

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

### @faststats/web 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @faststats/web 可以商用吗？

@faststats/web 使用 未声明 许可。package\.json 没有声明许可证。没有许可证的代码默认保留全部权利，商用前请联系作者或查看仓库中的 LICENSE 文件。以上为概括，不构成法律意见，请以许可原文为准。

### @faststats/web 的下载量有多少？

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

### @faststats/web 还在维护吗？

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