# @enter-pro/analytics-sdk 中文文档

规范地址：https://npmcn.com/package/%40enter-pro/analytics-sdk/

版本：0\.0\.10
npm 元数据更新时间：2026-05-11T08:00:33.404Z
中文译文更新时间：2026-11-13T18:16:24.640Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：116 kB，9 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：0 个
- peer 依赖：web-vitals ^4\.2\.4
- 首次发布：2026-04-21T07:34:29.650Z
- 最新版本发布：2026-05-11T08:00:33.282Z
- 近 30 天下载量：4226（2026-10-14 至 2026-11-12，npm 官方下载统计）
- 已发布版本数：10（近 12 个月 10 个）

## 中文简介

Enter 生成的网站的独立分析 SDK

## 安装

```sh
npm install @enter-pro/analytics-sdk
```

也可以使用：`pnpm add @enter-pro/analytics-sdk`、`yarn add @enter-pro/analytics-sdk`、`bun add @enter-pro/analytics-sdk`

## README

# @ enter- pro/analystics- sdk

用于 Enter 生成网站的独立分析 SDK 。 提供自动仪器和手动跟踪出框,没有运行时间依赖性.

* * *

## 目录

-   [快速启动](https://npmcn.com/package/%40enter-pro/analytics-sdk/#readme-quick-start)
-   [环境变量](https://npmcn.com/package/%40enter-pro/analytics-sdk/#readme-environment-variables)
-   [自动仪器](https://npmcn.com/package/%40enter-pro/analytics-sdk/#readme-automatic-instrumentation)
-   [手工跟踪](https://npmcn.com/package/%40enter-pro/analytics-sdk/#readme-manual-tracking)
    -   [强制性 API - `trackEvent`](https://npmcn.com/package/%40enter-pro/analytics-sdk/#readme-imperative-api--trackevent)
    -   [声明性API——事件定义](https://npmcn.com/package/%40enter-pro/analytics-sdk/#readme-declarative-api--event-definitions)
        -   [触发类型](https://npmcn.com/package/%40enter-pro/analytics-sdk/#readme-trigger-kinds)
        -   [财产约束](https://npmcn.com/package/%40enter-pro/analytics-sdk/#readme-property-bindings)
-   [公共 API 参考](https://npmcn.com/package/%40enter-pro/analytics-sdk/#readme-public-api-reference)
-   [基础设施](https://npmcn.com/package/%40enter-pro/analytics-sdk/#readme-infrastructure)
-   [已知差距](https://npmcn.com/package/%40enter-pro/analytics-sdk/#readme-known-gaps)
-   [出版](https://npmcn.com/package/%40enter-pro/analytics-sdk/#readme-publishing)
-   [正在进入另一回波](https://npmcn.com/package/%40enter-pro/analytics-sdk/#readme-consuming-in-another-repo)
-   [页:1](https://npmcn.com/package/%40enter-pro/analytics-sdk/#readme-notes)

* * *

## 快速启动

```ts
import { bootstrapEnterAnalytics } from '@enter-pro/analytics-sdk';

bootstrapEnterAnalytics();
```

设定所需的环境变量并调用 `bootstrapEnterAnalytics()` 一次在应用条目。 其他的都是自动的.

* * *

## 环境变量

| 变量 | 需求 | 默认 | 说明 |
| --- | --- | --- | --- |
| `VITE_ENTER_ANALYTICS_TOKEN` | 对 | —— 说 | 音轨终点的代理符 |
| `VITE_ENTER_PROJECT_ID` | 对 | —— 说 | 项目标识符 |
| `VITE_ENTER_ANALYTICS_ENDPOINT` | 没有 | `https://api.enter.pro` | API 基础 URL; SDK 附加 `/code/api/v1/track` |
| `VITE_ENTER_ANALYTICS_ENABLED` | 没有 | `true` | 设定为 `"false"` 以禁用所有跟踪 |
| `VITE_ENTER_ANALYTICS_DEBUG` | 没有 | `false` | 设定为 `"true"` 启用调试日志 |

SDK读自 `import.meta.env` (声音)或 `globalThis.__ENTER_ANALYTICS_ENV__` (非病毒环境).

> **端点路径映射 :** sDK 职位到 `<base>/code/api/v1/track`后边 输入 API 网关, 此网关将重写到公众界面 `/v1/track` 路径文件 在分析 API 规格。 如果您是自动主机分析服务, 请配置 您要删除的反向代理 `/code` 前缀或设置 `VITE_ENTER_ANALYTICS_ENDPOINT` 到一个已经针对右主机的基址.

* * *

## 自动仪器

下面的一切都自动收集 `bootstrapEnterAnalytics()` 名为. 不需要额外的代码 .

### 页视图

-   发射 a `page_view` 初始负载时的事件 .
-   补丁 `history.pushState` 财务报告和审定财务报表 `history.replaceState` 以探测SPA导航.
-   监听 `popstate` 用于后向导航.
-   50ms的复制窗口可以防止快速通航的双发.

### 会话周期

-   第一个会话开始 `page_view` 火灾和发射a `session_start` 包含一个事件 `session_reason` 财产(`first_visit` | `expired` | `continued`) (中文(简体) ).
-   会议在30分钟后结束(通过 `bootstrapEnterAnalytics({ inactivityTimeoutMs })`) (中文(简体) ).
-   A 类 `session_end` 当页面卸下时会释放出事件(`beforeunload`)或者当不活动计时器起火时.
-   `visibilitychange → hidden` 已经 **没有** 结束会话——它只会触发同步冲出并暂停不活动计时器. 如果页面隐藏时间长于 `inactivityTimeoutMs`时,会话结束于下一个 `visibilitychange → visible` 与 `ended_by: 'inactivity'`。这避免了用户在移动上短暂切换分页时对会话进行充值.
-   会话状态持续在 `sessionStorage` 因此,它可以在同一个标签中刷新页面.

### SDK 整合验证

靴子装好后,SDK发射一发子弹 `enter_verify` 交通事件,所以后端 `GET /analytics/verify` 端点可以确认SDK被正确接通. 过 `disableVerifyPing: true` 改为 `bootstrapEnterAnalytics` 跳过它.

### JavaScript 错误捕获

-   监听 `window.error` 财务报告和审定财务报表 `window.unhandledrejection`。 。 。 .
-   发射一个 `error` 交通活动 `error_message`, (中文(简体) ), `source`, (中文(简体) ), `lineno`,以及 `colno` 属性.
-   过滤出第三方营销噪声(Facebook Pixel,Google Tag管理器,Twitter Analytics,DoubleClick)来减少无关出错的音量.

### 性能计量

每页装入一次 `load` 事件火灾.

| 度量衡 | 来源 |
| --- | --- |
| LCP (最大内容绘画) | `web-vitals` 或本地语言 `PerformanceObserver` |
| CLS( 组合版式移动) | `web-vitals` 或本地语言 `PerformanceObserver` |
| FID( 第一次输入延迟) | `web-vitals` |
| FCP (第一内容画) | `web-vitals` 或本地语言 `paint` 性能 输入 |
| TTFB( 到第一个字节的时间) | `web-vitals` 或者说 `PerformanceNavigationTiming` |
| `dom_content_loaded_ms` | `PerformanceNavigationTiming` |
| `load_event_ms` | `PerformanceNavigationTiming` |

用于 `web-vitals`,将它暴露为全球前 `bootstrapEnterAnalytics()` 称为:

```ts
import * as webVitals from 'web-vitals';
window.webVitals = webVitals;

bootstrapEnterAnalytics();
```

无 `web-vitals`SDK回归原生性能API. LCP和CLS仍然是可观测的;FID在倒回路径中不可用.

### 访客身份

-   生成一个稳定 `visitor_id` 第一次访问时使用 `crypto.randomUUID()`。 。 。 .
-   将身份识别在两者中 `localStorage` 和一张饼干,用于交叉和相接的连续性.
-   记录 `visitor_first_seen_at` 新的访客检测.

### 每个事件的自动上下文

每个事件——无论是自动的还是人工的——在发作时都会被以下字段所丰富: 1

| 外地 | 来源 |
| --- | --- |
| `page_url`, (中文(简体) ), `page_path`, (中文(简体) ), `page_title` | `window.location` 编号 : `document.title` |
| `referrer` | `document.referrer` |
| `utm_source/medium/campaign/content/term` | URL 搜索参数 |
| `visitor_id` | 长期访客身份 |
| `session_id` | 当前活动会话 |
| `sdk_version`, (中文(简体) ), `schema_version` | 构建时常数 |

> 设备上下文( E)`device_type`, (中文(简体) ), `browser`, (中文(简体) ), `os`, (中文(简体) ), `language`)被检测出并在事件内部筑巢 `context` 对象。 此匹配后端 `/v1/track` schema,它只接受一个固定的顶级字段列表并放下任何额外的根级密钥. `screen_resolution` 也在里面筑巢着 `context`,并且故意只附在 `page_view` 财务报告和审定财务报表 `session_start` 事件(匹配分析设计谱)使有效载荷保持小. 用户提供 `TrackEventOptions.context` 被合并到自动收集设备字段的顶端,所以如果需要,呼叫者可以覆盖任意字段(例如通过) `context: { browser: 'CustomBrowser' }`) (中文(简体) ). Hash-routter 应用程序必须选择使用 `bootstrapEnterAnalytics({ hashRouting: true })` 若为 `page_path` 自动 `page_view` 检测应包括 `location.hash` 例如 `/#templates`。 。 。 .

* * *

## 手工跟踪

### 强制性 API - `trackEvent`

打电话 `trackEvent` 用于发布自定义事件的应用程序代码中的任意位置.

```ts
import { trackEvent } from '@enter-pro/analytics-sdk';

trackEvent('button_clicked', {
  eventType: 'custom',       // 'custom' (default) | 'conversion'
  properties: {
    button_id: 'signup',
    variant: 'primary',
  },
  context: {
    page_section: 'hero',
  },
});
```

`trackEvent` 如果 `bootstrapEnterAnalytics()` 没有被调用或SDK已禁用.

**参数:**

| 参数 | 类型 | 说明 |
| --- | --- | --- |
| `eventName` | `string` | 事件名称 |
| `options.eventType` | `'custom' | 'conversion'` | 默认为 `'custom'` |
| `options.properties` | `Record<string, unknown>` | 任意事件数据 |
| `options.context` | `Record<string, unknown>` | 上下文元数据(例如UI部分,实验ID) |

* * *

### 声明性API——事件定义

事件定义允许您将跟踪规则描述为数据结构并附加到DOM元素上,而不写入每个组件的事件处理器代码. SDK在捕捉相中监听文档,在匹配元素时会自动起火事件.

#### 登记册定义

```ts
import { registerEventDefinition, registerEventDefinitions } from '@enter-pro/analytics-sdk';

// Register a single definition
registerEventDefinition({
  event_name: 'signup_click',
  event_type: 'conversion',
  trigger: { kind: 'click', selector: '#signup-btn' },
  property_bindings: {
    plan: { type: 'attribute', attribute: 'data-plan' },
    label: { type: 'textContent' },
  },
  definition_version: '1',
});

// Register multiple definitions at once
registerEventDefinitions([...]);

// Replace all definitions (e.g. after fetching from a remote config)
replaceEventDefinitions([...]);
```

#### 从远程配置中装入定义

要给"用户通过 Enter Agent → SDK 自动收集它们来定义事件"环线,将 SDK 指向返回当前工程事件定义的远程端点. 获取的列表将替换当前注册的列表 .

```ts
// Option 1: declaratively at bootstrap time
bootstrapEnterAnalytics({
  eventDefinitionsUrl: 'https://api.enter.pro/v1/projects/proj_abc/event-definitions',
  // Optional: provide a fetcher with auth headers if the endpoint is private.
  eventDefinitionsFetcher: (url, init) =>
    fetch(url, { ...init, headers: { Authorization: 'Bearer <token>' } }),
});

// Option 2: imperatively at any time after bootstrap
import { loadEventDefinitionsFromUrl } from '@enter-pro/analytics-sdk';
await loadEventDefinitionsFromUrl(
  'https://api.enter.pro/v1/projects/proj_abc/event-definitions'
);
```

接受响应形状 :

```jsonc
// Raw array
[ { "event_name": "...", ... } ]

// Or wrapped in an envelope
{ "data": { "definitions": [ { "event_name": "...", ... } ] } }
{ "definitions": [ { "event_name": "...", ... } ] }
```

#### 触发类型

| 仁爱 | 行为 |
| --- | --- |
| `click` | 匹配任何元素时起火 `selector` 已单击 |
| `submit` | 匹配窗体时起火 `selector` 提交 |
| `manual` | 没有自动 DOM 听器; 必须通过拨打来触发 `emitDefinedEvent(eventName, element)` 明确 |

#### 财产约束

属性绑定定义在事件起火时如何从 DOM 中提取值 。 解析值成为事件 `properties`。 。 。 .

| 装订类型 | 说明 | 选项 |
| --- | --- | --- |
| `constant` | 静态值 | `value: string | number | boolean` |
| `textContent` | 元素的文本内容 | `selector?` (对触发元素的默认) |
| `attribute` | HTML 属性值 | `attribute: string`, (中文(简体) ), `selector?` |
| `dataset` | A 类 `data-*` 价值 | `key: string`, (中文(简体) ), `selector?` |
| `closestAttribute` | 最近的匹配祖先的属性 | `selector: string`, (中文(简体) ), `attribute: string` |
| `formField` | 按名称排列的单一窗体字段值 | `field: string`, (中文(简体) ), `valueType?: 'value' | 'checked'` |
| `formFields` | 多窗体字段值 | `fields?: string[]`, (中文(简体) ), `includeAll?: boolean`, (中文(简体) ), `valueType?` |

对于带有可选内容的绑定 `selector`,SDK将元素相对于触发元素进行解析. 若为 `selector` 中省略,则使用触发元素本身.

**实例:**

```ts
// Read a data attribute from the clicked element
{ type: 'attribute', attribute: 'data-product-id' }

// Read a data attribute from the nearest ancestor matching a selector
{ type: 'closestAttribute', selector: '[data-experiment]', attribute: 'data-experiment' }

// Collect specific form fields on submit
{ type: 'formFields', fields: ['email', 'plan'] }

// Collect all form fields on submit
{ type: 'formFields', includeAll: true }
```

#### 手动触发

对于 `trigger.kind: 'manual'` 定义,或在方案上触发任何定义:

```ts
import { emitDefinedEvent } from '@enter-pro/analytics-sdk';

// Without a DOM target
emitDefinedEvent('signup_click');

// With a DOM element as the binding resolution context
emitDefinedEvent('signup_click', document.querySelector('#signup-btn'));
```

* * *

## 公共 API 参考

| 导出 | 签署 | 说明 |
| --- | --- | --- |
| `bootstrapEnterAnalytics` | `(options?: BootstrapOptions) => void` | 初始化 SDK. 一次在应用程序条目。 同上,注:. |
| `trackEvent` | `(name: string, options?: TrackEventOptions) => void` | 发送自定义或转换事件 |
| `registerEventDefinition` | `(def: EventDefinition) => void` | 登记单一声明事件定义 |
| `registerEventDefinitions` | `(defs: EventDefinition[]) => void` | 登记多种定义 |
| `replaceEventDefinitions` | `(defs: EventDefinition[]) => void` | 从解剖角度取代所有定义 |
| `unregisterEventDefinition` | `(eventName: string) => void` | 删除单一定义 |
| `clearEventDefinitions` | `() => void` | 删除所有定义 |
| `emitDefinedEvent` | `(eventName: string, target?: Element | null) => void` | 手动发射已注册定义 |
| `loadEventDefinitionsFromUrl` | `(url: string, fetcher?: typeof fetch) => Promise<EventDefinition[]>` | 从远程端点获取定义并替换本地注册 |
| `flush` | `() => Promise<void>` | 立即强行冲出收发箱 |
| `destroy` | `() => void` | 停止所有收藏器并清除运行时态 |
| `getAnalyticsHealth` | `() => AnalyticsHealth` | 检查调试的 SDK 状态 |

### `BootstrapOptions`

```ts
interface BootstrapOptions {
  /** Inactivity timeout before a session expires. Default: 30 minutes. */
  inactivityTimeoutMs?: number;
  /** Skip the one-shot enter_verify ping fired right after bootstrap. */
  disableVerifyPing?: boolean;
  /** Include `location.hash` in `page_path` and automatic `page_view` route detection. */
  hashRouting?: boolean;
  /**
   * If provided, the SDK will GET this URL after bootstrap and call
   * replaceEventDefinitions() with the response. Accepts either a raw array
   * or a `{ data: { definitions: [...] } }` envelope.
   */
  eventDefinitionsUrl?: string;
  /** Optional fetch implementation override (useful for SSR / proxy / auth). */
  eventDefinitionsFetcher?: typeof fetch;
}
```

对于散列程序,请打电话 `bootstrapEnterAnalytics({ hashRouting: true })` 在应用程序条目。 这个工作空间目前不包括被跟踪的生成站点消费者,因此外部模板/bootstrap集成需要明确启用旗帜.

### `AnalyticsHealth`

```ts
interface AnalyticsHealth {
  initialized: boolean;
  enabled: boolean;
  visitorId?: string;
  sessionId?: string;
  outboxSize: number;
  endpoint?: string;
  lastFlushAt?: number;
  lastError?: string;
}
```

* * *

## 基础设施

### 收发箱和交付

-   事件排入内存 + `localStorage`\- 交货前有备份.
-   发件箱幸存的页面刷新:在前一个会话中排队的事件会在下个负载上重试.
-   Flush运行间隔为5秒,分20批发送事件.
-   页面关闭( O)`pagehide`, (中文(简体) ), `visibilitychange`SDK又回到一个认证的 `fetch(..., { keepalive: true })`。 。 。 .
-   Page-exit slushs将记录保存在发件箱中,直到服务器承认它们为止,所以一个失败的卸载请求可以在下一页负载上重试.

### 重试和后退

-   失败请求会以指数回放和随机焦虑的方式重审 .
-   默认碱性延迟: 2 秒. 最大重试次数: 7.
-   超过72小时的事件自动放弃.
-   长期失败(`INVALID_SCHEMA`, (中文(简体) ), `UNAUTHORIZED`, (中文(简体) ), `FORBIDDEN`, (中文(简体) ), `BAD_REQUEST`,或服务器侧拒绝有永久原因)不重审.

### 数据保密

-   排序前, SDK 将匹配的属性密钥( 大小写不敏感子字符串) : `password`, (中文(简体) ), `token`, (中文(简体) ), `cookie`, (中文(简体) ), `authorization`, (中文(简体) ), `auth`, (中文(简体) ), `email`, (中文(简体) ), `phone`。 。 。 .
-   字符串属性值被缩短为256个字符.

* * *

## 已知差距

在代码库中确定了以下能力,但尚未完成:

| 差距 | 细节 |
| --- | --- |
| **没有 `identify()` API 密码** | 没有办法联系匿名者 `visitor_id` 带有认证的用户身份。 登录用户跟踪需要自定义 `properties` 工作经过 `trackEvent`。 。 。 . |
| **无漏斗/ 事件关联字段** | 事件不会带一个共享的关联ID,用于跨用户流的漏斗分析. |
| **`error` 财务报告和审定财务报表 `performance` 事件必须是预先注册的服务器侧** | SDK自动实体 `error` 财务报告和审定财务报表 `performance` 交通事件,但他们是 **没有** 后端默认事件白列表的一部分( 只有) `page_view` 编号 : `session_start` 编号 : `session_end` 编号 : `enter_verify` (见A/CN.9/WG.III/WP.96和Corr.1)。 直到后端将它们添加到默认列表中,或者您的工程通过 `POST /v1/projects/:pid/analytics/events/registry`他们将被弃绝 `event not registered`。 。 。 . |

* * *

## 出版

```bash
# Dry run to verify package contents
npm pack --dry-run
npm publish --dry-run

# Publish to npm
npm publish
```

该软件包发布到 `https://registry.npmjs.org/` 与 `access: public` 下划线 `@enter-pro` 范围.

* * *

## 正在进入另一回波

添加数据 `@enter-pro` 范围至 `.npmrc`数字 :

```ini
@enter-pro:registry=https://registry.npmjs.org/
//registry.npmjs.org/:_authToken=<NPM_TOKEN>
always-auth=true
```

安装 :

```bash
pnpm add @enter-pro/analytics-sdk
```

要在发布前进行测试,请从本地的焦油球上安装:

```bash
npm pack   # run in packages/analytics-sdk
pnpm add /absolute/path/to/enter-pro-analytics-sdk-0.0.6.tgz
```

* * *

## 页:1

-   此软件包是完全独立的, 不得导入运行时代码 `packages/analytics`。 。 。 .
-   发电机侧项目设置应复制 `skills/enter-analytics-auto.md` 输入 `.enter/skills/` 这样 Enter 代码就可以自动执行新工程.
-   SDK只采用无害环境管理(`"type": "module"`消费者必须使用捆绑机(Vite, esbuilt, Rollup等).

## 常见问题

### @enter-pro/analytics-sdk 是什么？

Enter 生成的网站的独立分析 SDK

### 如何安装 @enter-pro/analytics-sdk？

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

### @enter-pro/analytics-sdk 支持 TypeScript 吗？

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

### @enter-pro/analytics-sdk 支持 ESM 还是 CommonJS？

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

### @enter-pro/analytics-sdk 可以商用吗？

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

### @enter-pro/analytics-sdk 的下载量有多少？

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

### @enter-pro/analytics-sdk 还在维护吗？

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