# @getdevteam/analytics-web 中文文档

规范地址：https://npmcn.com/package/%40getdevteam/analytics-web/

版本：0\.13\.0
npm 元数据更新时间：2026-11-12T20:52:57.654Z
中文译文更新时间：2026-11-16T05:59:55.264Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：412 kB，16 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：2 个
- 首次发布：2026-07-05T14:58:06.910Z
- 最新版本发布：2026-11-12T20:52:57.439Z
- 近 30 天下载量：64840（2026-10-17 至 2026-11-15，npm 官方下载统计）
- 已发布版本数：21（近 12 个月 21 个）

## 中文简介

DevTeam分析与日志平台的浏览器 SDK.

## 安装

```sh
npm install @getdevteam/analytics-web
```

也可以使用：`pnpm add @getdevteam/analytics-web`、`yarn add @getdevteam/analytics-web`、`bun add @getdevteam/analytics-web`

## README

# @getdevteam/analytics-web (中文(简体) )

浏览器 SDK 用于 [DevTeam 分析与日志平台](https://github.com/getdevteam-ai/analytics)。 。 。 . 把它扔入任何浏览器应用中——平版JS,Astro,Vue,Svelte,或无钩回放——发送分析事件和日志. 用反应来构建想要的 `useAnalytics()` 钩子? 说对了 [`@getdevteam/analytics-react`](https://www.npmjs.com/package/@getdevteam/analytics-react)。 。 。 .

## 安装

```sh
npm install @getdevteam/analytics-web
```

## 使用

```ts
import { createAnalytics } from "@getdevteam/analytics-web";

const analytics = createAnalytics({
  key: "dtp_your_public_key",
  host: "https://ingest.analytics.getdevteam.ai",
  trackPageviews: true,   // auto-send a pageview whenever the URL changes
});

analytics.identify("user_123", { plan: "pro" });          // who the user is
analytics.track("checkout_completed", { amount: 4200 });  // something that happened
analytics.log.error("payment gateway timed out", { gateway: "stripe" });
```

自动抓取未发现出错(除了浏览器无害的调整观察员环路警告)和未处理的承诺拒绝(关闭时使用) `autoCaptureErrors: false`),并在页面被隐藏或关闭时冲出已队列的事件,因此在导航中不会丢失任何东西.

## 页面 URL

被跟踪的页面视图和反馈提交只发送页面的出处和路径: 查询字符串和片段, 重置, 邀请和 OAuth 令牌旅行的地方, 从未被收集 . 页面 `https://app.example/reset?token=abc#access_token=xyz` 以 `https://app.example/reset`。 。 。 . 以不同方式减少 URL, 通过 `pageUrl`; 它接收 `location.href` 返回要发送的 URL,或 `undefined` 无

```ts
import { originAndPath } from "@getdevteam/analytics-web";

const analytics = createAnalytics({
  key: "dtp_your_public_key",
  host: "https://ingest.analytics.getdevteam.ai",
  trackPageviews: true,
  pageUrl: (href) => originAndPath(href)?.replace(/\/invite\/[^/]+$/, "/invite/:token"),   // also collapse a path token
});
```

您通过自己的 URL `analytics.page({ url })` 现按规定发送.

每个日志行和被抓住的错误都带有页面路径作为它的 `screen` 属性,减去相同的 `pageUrl`: 日志上页 `screen: "/reset"`页面 `pageUrl` 没有发送日志和屏幕的 URL .

## 释放身份

过 `release: { version, commit }` 所以,每个事件和日志 命名发送它的建筑. 编队集 `DEVTEAM_RELEASE_VERSION` 财务报告和审定财务报表 `DEVTEAM_COMMIT_SHA` 在每次部署中; 在您框架的公开前缀下曝光( )`NEXT_PUBLIC_`, (中文(简体) ), `VITE_`, (中文(简体) ), `PUBLIC_`, (中文(简体) ), `REACT_APP_`并传为 `release`。 。 。 . 没有它,SDK会回到 `globalThis.__DEVTEAM_RELEASE__`,然后是一个 `<meta name="devteam-release" content="<version>;<commit>">` 标记,然后 `process.env`。 。 。 . 见 [释放身份](https://github.com/getdevteam-ai/analytics/tree/main/src/sdk#release-identity) 和合成交通旗.

## 用户反馈

设定 `allowUserFeedback: true` 来制作一个浮出水面的反馈按钮(被隔离在一个Shadow DOM主机中,被装入懒惰:用户得到页面的截图,绘图工具和评论框,结果会降落在平台的反馈收件箱中. `analytics.showFeedback()` 以程序打开覆盖;在功能关闭或无法使用时,它是无操作的. 自定义 `feedback: { colors, accentColor, buttonLabel, title, submitLabel, commentPlaceholder, successMessage, position, zIndex, pixelRatio, shakeToReport, shakeHint, draggable }`。 。 。 . `draggable: true` 让用户将按钮从位置拖到屏幕的任意边缘:放行后,它会与最近的边缘平起平坐并停留在那里;然后它就一直停留在它的位置上. `shakeToReport: true` 使手机和平板电脑(一个没有悬浮的触摸屏)在设备被摇动时打开上覆,没有浮动按钮;桌面浏览器保留按钮(它) `draggable` 让他们移动. 如果设备的运动不能被读取——没有传感器,运动访问被拒绝,或者在iOS上,直到按钮上的一个水龙头允许它——按钮会被保留,被暗地里,可以被拖到屏幕的任何边缘,被记住. `shakeHint` (默认) `Shake your phone to send feedback`)每设备显示一次,第一次摇动是打开上覆的部分,当一个文本字段被聚焦(iOS读作撤销)或页面隐藏部件主机元素时会忽略一个摇动. 部件主机元素将正在使用的模式作为 `data-mode`数字 : `button`, (中文(简体) ), `pending` (还在查), `shake` 或者说 `floating`。 。 。 . 打电话 `analytics.identify(user.id, { name: user.fullName })` 登录和会话恢复后, 反馈会说是谁发送的; 名称只包含反馈, 绝不包含事件或日志 `reset()` 在登录时忘记它.

截图是DOM到canvas的渲染. 浏览器无法获取的单个图像被留作空白,所以截图和绘图仍然可用;跨原生的iframe,被污染的画布,和视频帧仍然可以出现空白或使抓取失败,一个被抓取失败的回落到只评论的反馈而不是打破了应用程序.

捕捉有1个5秒的极限,从按下按钮后计算出,因此自旋者永远无法运行. 何时 `pixelRatio` 在1以上,全分辨率渲染得到它的前2秒,如果它失败或到那时还没有完成,其余的到1x的渲染. 在一分一秒,单一的渲染得到整个5秒. 形式中的重试截图按钮,效果相同. 截图在极限后完成,或窗体关闭后被丢弃.

失败的捕获到达 `onError` 作为 `ScreenshotCaptureError`,与 `reason` (单位:千美元)`"timeout"` 或者说 `"render_error"`和 `elapsedMs`数以毫秒计. 它从不包含页面的内容或基本的渲染错误.

```ts
import { createAnalytics, ScreenshotCaptureError } from "@getdevteam/analytics-web";

const analytics = createAnalytics({
  key: "dtp_your_public_key",
  host: "https://ingest.analytics.getdevteam.ai",
  allowUserFeedback: true,
  onError: (error) => {
    if (error instanceof ScreenshotCaptureError) {
      analytics.track("feedback_screenshot_failed", { reason: error.reason, elapsed_ms: error.elapsedMs });
    }
  },
});
```

见 [SDK 读取](https://github.com/getdevteam-ai/analytics/tree/main/src/sdk#user-feedback) 用于完整选项表并捕获边界.

你需要一个公开的摄入键( )`dtp_...`) 和您环境的摄入主机 URL - 见 [获取密钥](https://github.com/getdevteam-ai/analytics/tree/main/src/sdk#getting-a-key) 在完整的SDK文档.

完整客户端 API, 配置选项, 以及发布进程 : [弧/斯德克读取](https://github.com/getdevteam-ai/analytics/tree/main/src/sdk)。 。 。 .

## 常见问题

### @getdevteam/analytics-web 是什么？

DevTeam分析与日志平台的浏览器 SDK\.

### 如何安装 @getdevteam/analytics-web？

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

### @getdevteam/analytics-web 支持 TypeScript 吗？

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

### @getdevteam/analytics-web 支持 ESM 还是 CommonJS？

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

### @getdevteam/analytics-web 可以商用吗？

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

### @getdevteam/analytics-web 的下载量有多少？

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

### @getdevteam/analytics-web 还在维护吗？

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

