@getdevteam/analytics-web

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

Browser SDK for the DevTeam analytics and logging platform.

原始使用文档
文档目录5 节
  1. Install
  2. Use
  3. Page URLs
  4. Release identity
  5. User feedback

@getdevteam/analytics-web

Browser SDK for the DevTeam Analytics & Logging Platform. Drop it into any browser app - plain JS, Astro, Vue, Svelte, or React without the hooks - to send analytics events and logs. Building with React and want a useAnalytics() hook? Pair this with @getdevteam/analytics-react.

Install

npm install @getdevteam/analytics-web

Use

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" });

Auto-captures uncaught errors (except the browser's harmless ResizeObserver loop warning) and unhandled promise rejections (turn off with autoCaptureErrors: false), and flushes queued events when the page is hidden or closed so nothing is lost on navigation.

Page URLs

Tracked pageviews and feedback submissions send the page's origin and path only: the query string and fragment, where reset, invite and OAuth tokens travel, are never collected. A page at https://app.example/reset?token=abc#access_token=xyz is sent as https://app.example/reset. To reduce the URL differently, pass pageUrl; it receives location.href and returns the URL to send, or undefined to send none:

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
});

A URL you pass yourself to analytics.page({ url }) is sent as given.

Every log line and caught error carries the page's path as its screen attribute, reduced by the same pageUrl: the page above logs screen: "/reset", and a page pageUrl sends no URL for logs no screen.

Release identity

Pass release: { version, commit } so every event and log names the build that sent it. Devteam sets DEVTEAM_RELEASE_VERSION and DEVTEAM_COMMIT_SHA on every deploy; expose them under your framework's public prefix (NEXT_PUBLIC_, VITE_, PUBLIC_, REACT_APP_) and pass them as release. Without it the SDK falls back to globalThis.__DEVTEAM_RELEASE__, then a <meta name="devteam-release" content="<version>;<commit>"> tag, then process.env. See Release identity for the full precedence and the synthetic-traffic flag.

User feedback

Set allowUserFeedback: true to render a floating feedback button (isolated in a Shadow DOM host, loaded lazily): the user gets a screenshot of the page, drawing tools, and a comment box, and the result lands in the platform's feedback inbox. analytics.showFeedback() opens the overlay programmatically; it is a no-op while the feature is off or unavailable. Customize with feedback: { colors, accentColor, buttonLabel, title, submitLabel, commentPlaceholder, successMessage, position, zIndex, pixelRatio, shakeToReport, shakeHint, draggable }. draggable: true lets the user drag the button off its place to any edge of the screen: let go, it settles dimmed against the nearest edge and stays there on later visits; until then it stands where it always does. shakeToReport: true makes phones and tablets (a touch screen with no hover) open the overlay when the device is shaken, with no floating button; desktop browsers keep the button (which draggable lets them move). Where the device's motion cannot be read - no sensor, motion access refused, or on iOS until a tap on the button allows it - the button stays, dimmed, and can be dragged to any edge of the screen, where it is remembered. shakeHint (default Shake your phone to send feedback) is shown once per device, the first time shaking is what opens the overlay, and a shake is ignored while a text field is focused (iOS reads it as undo) or while the page hides the widget's host element. The widget's host element carries the mode in use as data-mode: button, pending (still finding out), shake or floating. Call analytics.identify(user.id, { name: user.fullName }) after login and session restore so feedback says who sent it; the name goes with feedback only, never with events or logs, and reset() on logout forgets it.

The screenshot is a DOM-to-canvas render. Individual images the browser cannot fetch are left blank so screenshot and drawing remain available; cross-origin iframes, tainted canvases, and video frames can still come out blank or make the capture fail, and a failed capture falls back to comment-only feedback instead of breaking the app.

The capture has one 5-second limit, counted from the press of the button, so the spinner never runs longer. When pixelRatio is above 1, the full-resolution render gets the first 2 seconds of it, and if it fails or has not finished by then, the rest goes to a render at 1x. At 1x the single render gets the whole 5 seconds. The Retry screenshot button in the form works to the same limit. A screenshot that finishes after its limit, or after the form was closed, is thrown away.

A failed capture reaches onError as a ScreenshotCaptureError, with reason ("timeout" or "render_error") and elapsedMs, the milliseconds it took. It never carries the page's content or the underlying render error.

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 });
    }
  },
});

See the SDK README for the full option table and capture boundary.

You need a public ingest key (dtp_...) and the ingest host URL for your environment - see Getting a key in the full SDK docs.

Full client API, config options, and release process: src/sdk README.

版本与发布记录

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

版本发布日期距今
0.13.0latest2026/11/133 天前
0.12.02026/11/106 天前
0.11.02026/11/097 天前
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 是什么?

Browser SDK for the DevTeam analytics and logging platform.

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