@happyvertical/analytics

中文文档
0.113.1发布于 2026/11/17MITTypeScriptES Module近 30 天下载 5250

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

中文使用文档

@ 喜悦的垂直/分析

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 而不请求返回不支持的精确度. 没有适配器静默地将任意的时间戳转换为日历日期. 现有 日历报告保留其行为和记录的可用性限制.

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 使用属性时区中的包容性日历区域。 有记录显示 时间戳支持本身并不能确定 API 的确切半开 精确的保证,所以它仍然不支持在这里.

版本与发布记录

@happyvertical/analytics 共发布 132 个版本,首次发布于 2026/06/23;过去 12 个月发布了 132 个版本。

版本发布日期距今
0.113.1latest2026/11/17今天
0.113.02026/11/152 天前
0.112.32026/11/134 天前
0.112.22026/11/125 天前
0.112.12026/11/125 天前
0.112.02026/11/125 天前

关于 @happyvertical/analytics 的常见问题

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