# @happyvertical/analytics 中文文档

规范地址：https://npmcn.com/package/%40happyvertical/analytics/

版本：0\.113\.1
npm 元数据更新时间：2026-11-17T00:01:14.698Z
中文译文更新时间：2026-11-17T14:20:10.369Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40happyvertical/analytics
原文对照：https://npmcn.com/package/%40happyvertical/analytics/?lang=original
项目主页：https://github.com/happyvertical/sdk/tree/main/packages/analytics#readme
源码仓库：https://github.com/happyvertical/sdk

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

- 包体积（解压后）：376 kB，37 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：2 个
- 首次发布：2026-06-23T08:14:11.685Z
- 最新版本发布：2026-11-17T00:01:14.495Z
- 近 30 天下载量：5250（2026-10-17 至 2026-11-15，npm 官方下载统计）
- 已发布版本数：132（近 12 个月 132 个）

## 中文简介

Google Analytics 4, Plausible 等的统一分析界面

## 安装

```sh
npm install @happyvertical/analytics
```

也可以使用：`pnpm add @happyvertical/analytics`、`yarn add @happyvertical/analytics`、`bun add @happyvertical/analytics`

## README

# @ 喜悦的垂直/分析

Google Analytics 4, Plausible 和 Matomo 的统一分析界面.

## Matomo报告

使用的日期分配报告 `VisitsSummary.get` 与 `period=day`每个日期在 Matomo的答复产生了一行报告,包括日期: 空数组或空记录 。 空日有零度量; 保留人口日数 他们的计数。 提供者在答复中不提出日期.

使用页数报告 `Actions.getPageUrls`为兼容性, `pagePath` 财务报告和审定财务报表 `unifiedPagePathScreen` 提供时返回 Matomo 的完整页面 URL, 后退 到它的标签。 匹配本地内容路径的消费者应解析 URL 它们的应用边界.

`activeUsers` 读取 `nb_uniq_visitors` 或者说 `nb_users`当马多摩忽略了两者时, 当前的提供者返回为零;这意味着没有访问量度, 不是没有访客的证据. `nb_visits` 地图到 `sessions` 并且必须 无法替换独有访客。 已读页视图参数 `nb_hits` 或者说 `nb_pageviews`消费者应使用现有的衡量标准,并区别 无法访问者从观测到的零数计数 .

运行软件包验证 `pnpm --filter @happyvertical/analytics test` 财务报告和审定财务报表 `pnpm exec turbo run build --filter=@happyvertical/analytics`。 。 。 .

## 准确的时间戳间隔集合

`runIntervalReport(propertyId, { interval: { startTime, endTime, timeZone }, metrics })` 与日历日期分开 `runReport`它描述的是准确的 半开间距 `[startTime, endTime)`: 末端瞬间被排除. 时间戳 需要秒和明确冲抵`Z` 或者说 `+/-HH:MM`),最多3个 分数. 明确的IANA `timeZone` 提供上下文; 时间戳 抵消定义即时,包括DST折叠期间。 空/ 反相间距, 无效的日历时间戳, 未知的抵消 `-00:00`,未知区域并空出或 拒绝的重复度数 `RangeError` 在供应商访问之前.

检查 `getCapabilities().timestampIntervalReporting` 和可选方法 ; 缺少能力/方法表示不支持。 Matomo广告 `{ precision: 'utc-calendar-days', metrics: ['screenPageViews'] }`它验证 从提供者元数据获取属性的属性时区, 只支持 UTC 属性 两个瞬间都在协调世界时午夜 当前时间后结束的间隔 返回不可用( e)`interval-incomplete`)没有提供者报告。 它要求 `Actions.get` 一次给 包含的日历范围结束专有边界的前一天。 这个 支持可复制的全天或季度页面视图总和而不作总结 访客数。 非UTC属性,DST日数,部分日数等度量衡 返回时 `status: 'unsupported'`;未知的属性时区返回不可用 .

仅 `status: 'available'` 包含 `metrics`,包括观测值 `'0'`。 。 。 . 丢失/变质提供者页面视图返回 `status: 'unavailable'`从零开始. 认证、网络和供应商故障通常都会被拒绝。 GA4 和可扩展 目前广告 `false` 而不请求返回不支持的精确度. 没有适配器静默地将任意的时间戳转换为日历日期. 现有 日历报告保留其行为和记录的可用性限制.

```typescript
const capabilities = await analytics.getCapabilities();
if (capabilities.timestampIntervalReporting && analytics.runIntervalReport) {
  const result = await analytics.runIntervalReport('site-id', {
    interval: {
      startTime: '2026-07-01T00:00:00Z',
      endTime: '2026-10-01T00:00:00Z',
      timeZone: 'UTC',
    },
    metrics: [{ name: 'screenPageViews' }],
  });
  if (result.status === 'available') console.log(result.metrics);
}
```

供应商边界合同: [马托莫报告 API](https://developer.matomo.org/guides/reporting-api) 使用属性时区中的包容性日历区域。 有记录显示 时间戳支持本身并不能确定 API 的确切半开 精确的保证,所以它仍然不支持在这里.

## 常见问题

### @happyvertical/analytics 是什么？

Google Analytics 4, Plausible 等的统一分析界面

### 如何安装 @happyvertical/analytics？

在项目目录运行 npm install @happyvertical/analytics，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 have-analytics-context，可以用 npx have-analytics-context 直接运行。

### @happyvertical/analytics 支持 TypeScript 吗？

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

### @happyvertical/analytics 支持 ESM 还是 CommonJS？

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

### @happyvertical/analytics 可以商用吗？

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

### @happyvertical/analytics 的下载量有多少？

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

### @happyvertical/analytics 还在维护吗？

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

