@happyvertical/smrt-analytics

中文文档
0.62.1发布于 2026/11/17MITTypeScriptES Module近 30 天下载 1.5万

SMRT框架的分析一体化模型

中文使用文档
文档目录13 节
  1. 安装
  2. 使用量
  3. 服务器- 服务器事件生命周期
  4. 报表时间安排
  5. API 密码
  6. 模型
  7. 收款
  8. 数字
  9. SDK 类型
  10. 依赖关系
  11. 贡献者指南
  12. 浏览器跟踪
  13. OpenObserve 项目度量衡( 只有服务器)

@happyvertical/smrt-分析

S-m-r-t框架分析集成模型. 管理分析属性(GA4, Plausible, Matomo), 数据流, 有重试支持的服务器侧事件跟踪, 以及带有调度的 AI 动力报告生成 .

安装

pnpm add @happyvertical/smrt-analytics

使用量

import {
  AnalyticsProperty, AnalyticsPropertyCollection,
  AnalyticsDataStream, AnalyticsDataStreamCollection,
  AnalyticsEvent, AnalyticsEventCollection,
  AnalyticsReport, AnalyticsReportCollection,
  AnalyticsProvider, DataStreamType, ReportFrequency
} from '@happyvertical/smrt-analytics';

// Create a GA4 property
const properties = await AnalyticsPropertyCollection.create({ db });
const property = await properties.create({
  name: 'main-site',
  displayName: 'Main Site Analytics',
  provider: AnalyticsProvider.GA4,
  externalId: 'properties/123456789',
  measurementId: 'G-XXXXXXXXXX',
  apiSecret: 'server-side-secret',
  status: 'active',
});

// Add a web data stream
const streams = await AnalyticsDataStreamCollection.create({ db });
await streams.create({
  propertyId: property.id,
  displayName: 'Web Traffic',
  streamType: DataStreamType.WEB,
  measurementId: 'G-XXXXXXXXXX',
  defaultUri: 'https://example.com',
  status: 'active',
});

// Track a server-side event with retry support
const events = await AnalyticsEventCollection.create({ db });
const event = await events.create({
  propertyId: property.id,
  eventName: 'purchase',
  clientId: 'client-uuid',
  params: JSON.stringify({ value: 99.99, currency: 'USD' }),
  status: 'pending',
});
// After sending: event.markSent() or event.markFailed('timeout')
// Retry logic: event.shouldRetry(3) checks retryCount < maxRetries

// Create a scheduled report with dimensions and metrics
const reports = await AnalyticsReportCollection.create({ db });
const report = await reports.create({
  propertyId: property.id,
  name: 'Weekly Traffic Report',
  dimensions: JSON.stringify([{ name: 'country' }, { name: 'deviceCategory' }]),
  metrics: JSON.stringify([{ name: 'activeUsers' }, { name: 'sessions' }]),
  dateRangeStart: '7daysAgo',
  dateRangeEnd: 'today',
  frequency: ReportFrequency.WEEKLY,
});

// AI-powered operations (uses do() and is() from SmrtObject)
const analysis = await property.analyzePerformance({ period: '30 days' });
const isHealthy = await property.isPerformingWell();
const insights = await report.analyzeResults();
const trending = await report.hasPositiveTrends();

hasPositiveTrends() 保持布尔的API。 何时 decisions: { type: 'typesafe' } 已配置且没有 AI 工具注册,它发送 已解决的报告迅速加上只选定指标并持续汇总 排行到键入决定路径。 其阈值默认为 0.5; 已配置 不确定波段在基因路径上使用相同的解析快取, 匹配 框架的决定的倒置行为。 路线比较高 用户增长、参与和转换值为有利和较高 或误差率为负数。 未知的计量方向, 不完整的比较 数据不充分或含糊不清,不能推定为正数. 配置的决定失败 。 没有决策者 现有即时驱动 yes编号 :no 行为仍在使用. resultData 保留 两种途径中都有记录的呼叫者管理的PII限制.

框架网站的分析指南应增加一个行之有效的决策者 配置示例; 此软件包 README 记录运行时合同直至 该指南得到更新.

服务器- 服务器事件生命周期

事件以内置重试支持跟踪其交付状态 :

  1. 预告 -- 创建, 尚未发送到提供者
  2. 发送 -- 成功交付(markSent() 套装 sentAt 时间戳)
  3. 失败 -- 交付失败( e)markFailed(error) 递增 retryCount(中文(简体) )

使用 shouldRetry(maxRetries) 检查一个失败的事件是否应当重审,以及 resetForRetry() 重置为 PENDING .

报表时间安排

报告支持通过 ReportFrequency数字 :

  • ONCE -- 单跑,不重新安排
  • DAILY 编号 : WEEKLY 编号 : MONTHLY - 说吧 calculateNextRun() 套装 nextRunAt 每次运行后

使用 isDue() 以检查计划报告是否需要运行.

API 密码

模型

导出说明
AnalyticsPropertyGA4 地产 活泼地产 或 Matomo 地产 人工智能方法: analyzePerformance(), (中文(简体) ), isPerformingWell()
AnalyticsDataStream属性内的数据流(web/iOS/Android). getPlatformId() 返回测量 Id 或 firebaseAppId
AnalyticsEvent服务器侧跟踪事件, 并重试队列 . toTrackEvent() 构建 SDK 有效载荷
AnalyticsReport保存了包含尺寸/度量的报表配置,调度,结果缓存. 人工智能方法: analyzeResults(), (中文(简体) ), hasPositiveTrends()

收款

AnalyticsPropertyCollection, (中文(简体) ), AnalyticsDataStreamCollection, (中文(简体) ), AnalyticsEventCollection, (中文(简体) ), AnalyticsReportCollection

数字

导出说明
AnalyticsProviderga4, (中文(简体) ), plausible, (中文(简体) ), matomo
AnalyticsPropertyStatusactive, (中文(简体) ), inactive, (中文(简体) ), pending
DataStreamTypeWEB_DATA_STREAM, (中文(简体) ), ANDROID_APP_DATA_STREAM, (中文(简体) ), IOS_APP_DATA_STREAM
DataStreamStatusactive, (中文(简体) ), inactive
TrackingEventStatuspending, (中文(简体) ), sent, (中文(简体) ), failed
ReportStatusdraft, (中文(简体) ), scheduled, (中文(简体) ), running, (中文(简体) ), completed, (中文(简体) ), failed
ReportFrequencyonce, (中文(简体) ), daily, (中文(简体) ), weekly, (中文(简体) ), monthly
CountingMethodONCE_PER_EVENT, (中文(简体) ), ONCE_PER_SESSION
CustomDimensionScopeEVENT, (中文(简体) ), USER, (中文(简体) ), ITEM

SDK 类型

从 ./types sDK 兼容性 : AnalyticsInterface, (中文(简体) ), AnalyticsCapabilities, (中文(简体) ), SDKProperty, (中文(简体) ), SDKDataStream, (中文(简体) ), SDKTrackEvent, (中文(简体) ), SDKPageviewEvent, (中文(简体) ), SDKReportOptions, (中文(简体) ), SDKReportResult, (中文(简体) ), SDKCustomDimension, (中文(简体) ), SDKCustomMetric, (中文(简体) ), SDKKeyEvent, (中文(简体) ), PropertyStatsWithTrend。 。 。 .

依赖关系

  • @happyvertical/smrt-core -- ORM 和代码生成
  • 端点 : svelte (可选,用于Svelte组件通过 @happyvertical/smrt-analytics/svelte(中文(简体) )

贡献者指南

见 AGENTS.md 用于软件包结构、变化、验证、, 和贡献者的指导.

浏览器跟踪

使用隔离 @happyvertical/smrt-analytics/browser 输入可选择的浏览器/ SPA 跟踪和 Matomo 适配器。 共享组件通过可选程序释放静态标准事件 @happyvertical/smrt-ui/analytics 上下文。 见 浏览器集成和隐私合同。 。 。 .

OpenObserve 项目度量衡( 只有服务器)

@happyvertical/smrt-analytics/observability 出口 OpenObserveStreamReader 联 合 国 default/project_observability 流线 : latestPerProject() 财务报告和审定财务报表 queryWindow() 返回每个项目的快照和收藏记录。 仅读 证书来自你的秘密店 在呼叫时间,从来没有达到一个 客户捆绑。 见 代理人/可观察性。 。 。 .

版本与发布记录

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

版本发布日期距今
0.62.1latest2026/11/17今天
0.62.02026/11/17今天
0.61.62026/11/161 天前
0.61.52026/11/161 天前
0.61.42026/11/161 天前
0.61.32026/11/152 天前

关于 @happyvertical/smrt-analytics 的常见问题

@happyvertical/smrt-analytics 是什么?

SMRT框架的分析一体化模型

如何安装 @happyvertical/smrt-analytics?

在项目目录运行 npm install @happyvertical/smrt-analytics,或使用 pnpm add / yarn add / bun add。

@happyvertical/smrt-analytics 支持 TypeScript 吗?

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

@happyvertical/smrt-analytics 支持 ESM 还是 CommonJS?

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

@happyvertical/smrt-analytics 可以商用吗?

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

@happyvertical/smrt-analytics 的下载量有多少?

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

@happyvertical/smrt-analytics 还在维护吗?

最新版本 0.62.1 发布于 2026/11/17(今天);至今共发布 366 个版本,其中过去 12 个月发布了 366 个;首次发布于 2026/06/23。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。