@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 记录运行时合同直至 该指南得到更新.
服务器- 服务器事件生命周期
事件以内置重试支持跟踪其交付状态 :
- 预告 -- 创建, 尚未发送到提供者
- 发送 -- 成功交付(
markSent()套装sentAt时间戳) - 失败 -- 交付失败( 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 用于软件包结构、变化、验证、,
和贡献者的指导.
浏览器跟踪
使用隔离 @happyvertical/smrt-analytics/browser 输入可选择的浏览器/ SPA 跟踪和 Matomo 适配器。 共享组件通过可选程序释放静态标准事件 @happyvertical/smrt-ui/analytics 上下文。 见 浏览器集成和隐私合同。 。 。 .
OpenObserve 项目度量衡( 只有服务器)
@happyvertical/smrt-analytics/observability 出口 OpenObserveStreamReader
联 合 国 default/project_observability 流线 : latestPerProject() 财务报告和审定财务报表
queryWindow() 返回每个项目的快照和收藏记录。 仅读
证书来自你的秘密店 在呼叫时间,从来没有达到一个
客户捆绑。 见 代理人/可观察性。 。 。 .