Matomo JS

Matomo JS

用于 Matomo Analytics 的现代 JavaScript/TypeScript 客户端库。

项目状态

⚠️ 此项目仍在开发中。 随着我们继续开发和完善该库，API 未来可能会发生变化。在生产环境中使用时请谨慎。

概述

此 monorepo 包含用于与 Matomo Analytics 交互的 JavaScript/TypeScript 库。该项目使用 TypeScript 构建，并采用 Nx monorepo 结构，以获得最佳开发体验。

软件包

Reporting Client (@mj-kiwi/matomo-client)

用于 Matomo Reporting API 的 TypeScript 客户端，提供强类型接口。此软件包提供了便捷的方式来与 Matomo Reporting API 端点交互。

功能

• 现代化的、基于 Promise 的 API
• 支持 TypeScript，并提供完整的类型定义
• 模块化设计，使用灵活
• 支持 Tree-shaking（仅导入所需内容）

可用模块

报告客户端包含 Matomo API 所有主要端点的模块，包括：

• Core - 核心报告功能（core）
• API - 通用 API 操作（api）
• SitesManager - 管理站点的方法（sitesManager）
• AbTesting - A/B 测试功能的方法（abTesting）
• Actions - 页面浏览量、内容跟踪（actions）
• ActivityLog - 用户活动日志（activityLog）
• AdvertisingConversionExport - 广告转化导出（advertisingConversionExport）
• Annotations - 管理注释（annotations）
• ConnectAccounts - 与其他平台集成（connectAccounts）
• Contents - 内容互动数据（contents）
• CoreAdminHome - 管理任务（coreAdminHome）
• CrashAnalytics - JavaScript 错误跟踪（crashAnalytics）
• CustomAlerts - 自定义警报定义（customAlerts）
• CustomDimensions - 自定义维度跟踪（customDimensions）
• CustomJsTracker - 自定义 JS 跟踪器功能（customJsTracker）
• CustomReports - 自定义报告管理（customReports）
• CustomVariables - 自定义变量数据（customVariables）
• Dashboard - 仪表板管理（dashboard）
• DevicePlugins - 浏览器插件统计（devicePlugins）
• DevicesDetection - 访客设备报告（devicesDetection）
• Events - 事件跟踪与分析（events）
• Feedback - 提交用户反馈（feedback）
• FormAnalytics - 表单互动数据（formAnalytics）
• Funnels - 转化漏斗分析（funnels）
• Goals - 转化目标与电子商务（goals）
• HeatmapSessionRecording - 热力图与会话录制（heatmapSessionRecording）
• ImageGraph - 生成静态 PNG 图表（imageGraph）
• Insights - 生成分析洞察（insights）
• LanguagesManager - 翻译与语言设置（languagesManager）
• Live - 实时访客数据（live）
• Login - 身份验证方法（login）
• MarketingCampaignsReporting - 营销活动数据（marketingCampaignsReporting）
• MediaAnalytics - 媒体互动统计（mediaAnalytics）
• MobileMessaging - 移动消息集成（mobileMessaging）
• MultiChannelConversionAttribution - 多渠道归因（multiChannelConversionAttribution）
• MultiSites - 多站点汇总数据（multiSites）
• Overlay - 页面叠加报告（overlay）
• PagePerformance - 页面加载指标（pagePerformance）
• PrivacyManager - 数据隐私管理（privacyManager）
• Referrers - 流量来源（referrers）
• Resolution - 屏幕分辨率报告（resolution）
• RollUpReporting - 汇总报告功能（rollUpReporting）
• ScheduledReports - 定时报告管理（scheduledReports）
• SearchEngineKeywordsPerformance - SEO 关键词（searchEngineKeywordsPerformance）
• SegmentEditor - 细分管理（segmentEditor）
• Seo - SEO 排名报告（seo）
• TagManager - 标签管理器功能（tagManager）
• Tour - 引导式导览功能（tour）
• Transitions - 访客导航路径（transitions）
• TwoFactorAuth - 双重身份验证管理（twoFactorAuth）
• UserCountry - 地理数据（userCountry）
• UserId - 用户 ID 跟踪（userId）
• UserLanguage - 访客语言报告（userLanguage）
• UsersFlow - 用户流可视化（usersFlow）
• UsersManager - 用户管理（usersManager）
• VisitFrequency - 访客频率指标（visitFrequency）
• VisitTime - 访客时间报告（visitTime）
• VisitorInterest - 互动指标（visitorInterest）
• VisitsSummary - 访问指标与统计数据（visitsSummary）

此外还有许多模块，全面覆盖 Matomo API。

MCP 服务（@mj-kiwi/matomo-mcp-server）

一个模型上下文协议（MCP）服务，充当 AI Agent（如大模型）与 Matomo 分析平台之间的桥梁。此软件包将 Matomo Reporting API 的功能作为 MCP 工具提供。

功能

• 实现模型上下文协议规范
• 为 AI Agent 提供对 Matomo 数据的直接访问
• 可通过环境变量轻松配置
• 模块化设计，与 Matomo API 结构相对应

实现状态

目前，MCP 服务已实现 47 个 Matomo API 模块中的 4 个（完成度为 8.5%）：

• SitesManager
• TagManager
• Tour
• UserId

其他模块正在积极开发中。

开始使用

先决条件

• Node.js（推荐 v18 或更高版本）
• npm、yarn 或 pnpm

安装

# Install the reporting client
npm install @mj-kiwi/matomo-client

# Or with yarn
yarn add @mj-kiwi/matomo-client

# Or with pnpm
pnpm add @mj-kiwi/matomo-client

基本用法

import { ReportingClient } from '@mj-kiwi/matomo-client';

// Create a reporting client instance
const client = new ReportingClient({
  baseUrl: 'https://your-matomo-instance.com',
  apiKey: 'your-api-key', // if using token-auth
});

// Fetch site analytics data
const siteData = await client.core.getVisits({
  idSite: 1,
  period: 'day',
  date: 'yesterday',
});

许可证

MIT