# @happyvertical/smrt-analytics 中文文档

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

版本：0\.62\.1
npm 元数据更新时间：2026-11-17T07:56:07.365Z
中文译文更新时间：2026-11-17T10:06:43.207Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：801 kB，85 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：5 个
- peer 依赖：svelte ^5\.57\.0
- 首次发布：2026-06-23T01:18:27.666Z
- 最新版本发布：2026-11-17T07:56:07.165Z
- 近 30 天下载量：14819（2026-10-17 至 2026-11-15，npm 官方下载统计）
- 已发布版本数：366（近 12 个月 366 个）

## 中文简介

SMRT框架的分析一体化模型

## 安装

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

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

## README

# @happyvertical/smrt-分析

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

## 安装

```bash
pnpm add @happyvertical/smrt-analytics
```

## 使用量

```typescript
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 密码

### 模型

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

### 收款

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

### 数字

| 导出 | 说明 |
| --- | --- |
| `AnalyticsProvider` | `ga4`, (中文(简体) ), `plausible`, (中文(简体) ), `matomo` |
| `AnalyticsPropertyStatus` | `active`, (中文(简体) ), `inactive`, (中文(简体) ), `pending` |
| `DataStreamType` | `WEB_DATA_STREAM`, (中文(简体) ), `ANDROID_APP_DATA_STREAM`, (中文(简体) ), `IOS_APP_DATA_STREAM` |
| `DataStreamStatus` | `active`, (中文(简体) ), `inactive` |
| `TrackingEventStatus` | `pending`, (中文(简体) ), `sent`, (中文(简体) ), `failed` |
| `ReportStatus` | `draft`, (中文(简体) ), `scheduled`, (中文(简体) ), `running`, (中文(简体) ), `completed`, (中文(简体) ), `failed` |
| `ReportFrequency` | `once`, (中文(简体) ), `daily`, (中文(简体) ), `weekly`, (中文(简体) ), `monthly` |
| `CountingMethod` | `ONCE_PER_EVENT`, (中文(简体) ), `ONCE_PER_SESSION` |
| `CustomDimensionScope` | `EVENT`, (中文(简体) ), `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`](https://npmcn.com/package/%40happyvertical/smrt-analytics/AGENTS.md) 用于软件包结构、变化、验证、, 和贡献者的指导.

## 浏览器跟踪

使用隔离 `@happyvertical/smrt-analytics/browser` 输入可选择的浏览器/ SPA 跟踪和 Matomo 适配器。 共享组件通过可选程序释放静态标准事件 `@happyvertical/smrt-ui/analytics` 上下文。 见 [浏览器集成和隐私合同](https://npmcn.com/package/%40happyvertical/smrt-analytics/agents/browser.md)。 。 。 .

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

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

## 常见问题

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

