@getdevteam/analytics-web

中文文档
0.13.0发布于 2026/11/13MITTypeScriptESM + CJS近 30 天下载 6.5万

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

中文使用文档
文档目录5 节
  1. 安装
  2. 使用
  3. 页面 URL
  4. 释放身份
  5. 用户反馈

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

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

安装

npm install @getdevteam/analytics-web

使用

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 无

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。 。 。 . 见 释放身份 和合成交通旗.

用户反馈

设定 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数以毫秒计. 它从不包含页面的内容或基本的渲染错误.

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 读取 用于完整选项表并捕获边界.

你需要一个公开的摄入键( )dtp_...) 和您环境的摄入主机 URL - 见 获取密钥 在完整的SDK文档.

完整客户端 API, 配置选项, 以及发布进程 : 弧/斯德克读取。 。 。 .

版本与发布记录

@getdevteam/analytics-web 共发布 21 个版本,首次发布于 2026/07/05;过去 12 个月发布了 21 个版本。

版本发布日期距今
0.13.0latest2026/11/133 天前
0.12.02026/11/106 天前
0.11.02026/11/096 天前
0.10.02026/11/0313 天前
0.9.02026/11/0213 天前
0.8.32026/10/2917 天前

其他发布通道:dev → 0.1.0-dev.2。

关于 @getdevteam/analytics-web 的常见问题

@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 和提交记录判断。