# @certible/use-matomo 中文文档

规范地址：https://npmcn.com/package/%40certible/use-matomo/

版本：1\.3\.0
npm 元数据更新时间：2026-11-09T07:40:28.483Z
中文译文更新时间：2026-11-09T08:13:52.828Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：21.1 kB，5 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：0 个
- 首次发布：2025-08-11T06:34:23.254Z
- 最新版本发布：2026-11-09T07:40:28.089Z
- 近 30 天下载量：9299（2026-10-10 至 2026-11-08，npm 官方下载统计）
- 已发布版本数：6（近 12 个月 4 个）

## 中文简介

用于 Matomo js ,包括 SPA 跟踪的可忽略框架包.

## 安装

```sh
npm install @certible/use-matomo
```

也可以使用：`pnpm add @certible/use-matomo`、`yarn add @certible/use-matomo`、`bun add @certible/use-matomo`

## README

# 用户- matomo

用于 Matomo js ,包括 SPA 跟踪的可忽略框架包.

## 安装

```bash
# NPM
npm install @certible/use-matomo
# PNPM
pnpm add @certible/use-matomo
```

## 使用量

```javascript
import { initMatomo } from '@certible/use-matomo';

const matomo = initMatomo({
  host: 'https://your-matomo-instance.com',
  siteId: 1,
  // trackRouter: true, automatically tracks SPA page changes via history tracking
});

// Manually track router changes
// router.afterEach((to, from) => {
//   matomo.trackPageView(to.path, opts);
// });

// Track an event
matomo.trackEvent('Category', 'Action', 'Name', 1);
```

### 时间轴:

```typescript
import { initMatomo } from '@certible/use-matomo';
import { createApp } from 'vue';
import App from './App.vue';

const app = createApp(App);

const matomo = initMatomo({
  host: 'https://your-matomo-instance.com',
  siteId: 1,
  // trackRouter: true, automatically tracks SPA page changes via history tracking
}));

app.provide<MatomoTracker>('matomo', matomo);
```

```typescript
// In your components, you can access Matomo like this:
import { inject } from 'vue';

const matomo = inject<MatomoTracker>('matomo');
```

#### 夸萨

```javascript
// quasar boot file: src/boot/matomo.js
import { defineBoot } from '#q-app/wrappers';
import { initMatomo } from '@certible/use-matomo';


export default defineBoot(({ app }) => {
  const matomo = initMatomo({
    host: 'https://your-matomo-instance.com',
    siteId: 1,
    // trackRouter: true, automatically tracks SPA page changes via history tracking
  });

  app.provide('matomo', matomo);
});
```

## 配置选项

这个 `initMatomo` 函数接受配置对象,其选项如下:

### 需要的选项

| 选项 | 类型 | 说明 |
| --- | --- | --- |
| `host` | `string` | 您 Matomo 实例的 URL( 例如 ), `https://your-matomo-instance.com`(中文(简体) ) |
| `siteId` | `number | string` | 您的 Matomo 实例中的站点ID |

### 选项

| 选项 | 类型 | 默认 | 说明 |
| --- | --- | --- | --- |
| `trackerFileName` | `string` | `'matomo'` | 跟踪脚本和端点的文件名 |
| `trackerUrl` | `string` | `''` | 自定义跟踪器端点 URL 。 如果为空, 则使用 `{host}/{trackerFileName}.php` |
| `trackerScriptUrl` | `string` | `''` | 自定义跟踪脚本 URL 。 如果为空, 则使用 `{host}/{trackerFileName}.js` |
| `trackerScriptDisable` | `boolean` | `false` | 禁用自动加载追踪器脚本( 如果已装入则有用) |
| `enableLinkTracking` | `boolean` | `true` | 启用自动跟踪出入境链接和下载 |
| `requireConsent` | `boolean` | `false` | 跟踪前需征得用户同意(符合国内生产总值要求) |
| `userId` | `string` | `''` | 设置一个用户ID, 用于跟踪会话 |
| `disableCookies` | `boolean` | `false` | `window._paq.push(['disableCookies'])` |
| `requireCookieConsent` | `boolean` | `false` | `window._paq.push(['requireCookieConsent'])` |
| `enableHeartBeatTimer` | `boolean` | `false` | `window._paq.push(['enableHeartBeatTimer', options.heartBeatTimerInterval])` |
| `heartBeatTimerInterval` | `number` | `15` | 心跳计时器间隔( 秒) |
| `cookieDomain` | `string` | `''` | 设定用于跨子域跟踪的 cookie 域, `window._paq.push(['setCookieDomain', options.cookieDomain])` |
| `domains` | `string[]` | `[]` | 内部跟踪域列表(用于跨域跟踪), `window._paq.push(['setDomains', options.domains])` |
| `crossOrigin` | `'anonymous' | 'use-credentials'` | `undefined` | 跟踪脚本的交叉原生属性 |
| `preInitActions` | `MatomoCommand[]` | `[]` | 初始化前要执行的 Matomo 命令阵列 |
| `trackRouter` | `boolean` | `false` | 通过历史 API 监视自动跟踪 SPA 页面变化 |
| `trackInitialView` | `boolean` | `true` | 初始化时跟踪初始页面视图 。 设定为 `false` 调用 `trackPageView()` 自己,比如在您的应用程序设置路由标题之后 |

### 初始页面视图

`initMatomo` 立即排入初始页面视图,因此,早期导航无法替换条目 URL。 跟踪器脚本处理队列时会读取 `document.title` 只要 URL 不变, 也一样。 因此,在使用 tracker 脚本时,您的应用程序会设置标题 .

如果您的应用程序稍后设定标题, 设置 `trackInitialView: false` 并跟踪初始页面视图:

```javascript
const matomo = initMatomo({
  host: 'https://analytics.example.com',
  siteId: 1,
  trackInitialView: false,
});

// After the first route resolved and set the title
matomo.trackPageView();
```

链接跟踪`enableLinkTracking`)与每个排队 `trackPageView()` 电话 与 `trackInitialView: false`从你的第一通电话开始.

### 带有全部选项的示例

```javascript
const matomo = initMatomo({
  host: 'https://analytics.example.com',
  siteId: 1,
  trackerFileName: 'piwik', // For older Matomo instances
  enableLinkTracking: true,
  requireConsent: true, // GDPR compliance
  disableCookies: false,
  enableHeartBeatTimer: true,
  heartBeatTimerInterval: 30,
  cookieDomain: '.example.com',
  domains: ['*.example.com', 'subdomain.example.com'],
  trackRouter: true, // Automatic SPA tracking
  preInitActions: [
    ['setCustomDimension', 1, 'Premium User']
  ]
});
```

## API 方法

Matomo 跟踪器初始化后,返回一个对象,其方法如下:

### `trackEvent(category, action, name?, value?)`

跟踪自定义事件.

**参数:**

-   `category` (弦):活动类别
-   `action` (弦):事件的动作
-   `name` (弦,可选): 活动名称
-   `value` (数目,可选): 事件的价值

**示例**

```javascript
// Track a button click
matomo.trackEvent('Navigation', 'Click', 'Header Logo');

// Track with a value
matomo.trackEvent('Purchase', 'Complete', 'Premium Plan', 99.99);
```

### `trackPageView(url?, props?)`

在单页应用程序中跟踪页面视图.

**参数:**

-   `url` (弦,可选): 要跟踪的页面的 URL 。 默认为 `window.location.href`
-   `props` (对象,可选): 页面视图的额外属性
    -   `deleteCustomVariables` (boolean):是否删除自定义变量. 默认 : `true`
    -   `documentTitle` (字符串):自定义文档标题. 默认 : `document.title`

**示例**

```javascript
// Track current page
matomo.trackPageView();

// Track specific URL
matomo.trackPageView('/dashboard');

// Track with custom title
matomo.trackPageView('/profile', { 
  documentTitle: 'User Profile - MyApp' 
});
```

### `setUserId(userId)`

设置或重置用户ID, 用于跨会话的跟踪 .

**参数:**

-   `userId` (字符串 = 无效): 要设置的用户 ID, 或 `null` 重设

**示例**

```javascript
// Set user ID
matomo.setUserId('user123');

// Reset user ID
matomo.setUserId(null);
```

### `destroy()`

删除路由器跟踪收听器并恢复补丁历史方法.

使用这个当 `trackRouter` 被启用,您的应用程序会从跟踪器上撕裂, 例如在热模块替换或测试时.

**数据元数据监测网的例子:**

```javascript
const matomo = initMatomo({
  host: 'https://analytics.example.com',
  siteId: 1,
  trackRouter: true,
});

if (import.meta.hot) {
  import.meta.hot.dispose(() => {
    matomo.destroy();
  });
}
```

### `ready`

保证在追踪器脚本装入后解决. 初始页面视图( 如果 `trackInitialView` 实值 `true`)在初始化时被排入队列. 它拒绝当脚本无法加载时.

**示例**

```javascript
await matomo.ready;
```

### `push(args)`

将任何指令直接推进到 Matomo 跟踪器。 这使得您可以使用任何没有被这个包装器明确曝光的Matomo跟踪方法.

**参数:**

-   `args` (阵列):要传递给马多莫的一系列论据

**示例**

```javascript
// Set custom dimension
matomo.push(['setCustomDimension', 1, 'Premium User']);

// Track site search
matomo.push(['trackSiteSearch', 'keyword', 'category', 5]);

// Set custom variable
matomo.push(['setCustomVariable', 1, 'UserType', 'Premium', 'visit']);
```

关于现有马托莫跟踪方法的完整清单,请参见: [Matomo JavaScript 跟踪指南](https://developer.matomo.org/guides/tracking-javascript-guide)。 。 。 .

## 许可证

这个项目根据麻省理工学院的许可证获得许可.

## 关于

这个软件包由 **[可认证](https://certible.com/)**。 。 。 .

## 常见问题

### @certible/use-matomo 是什么？

用于 Matomo js ,包括 SPA 跟踪的可忽略框架包\.

### 如何安装 @certible/use-matomo？

在项目目录运行 npm install @certible/use-matomo，或使用 pnpm add / yarn add / bun add。

### @certible/use-matomo 支持 TypeScript 吗？

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

### @certible/use-matomo 支持 ESM 还是 CommonJS？

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

### @certible/use-matomo 可以商用吗？

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

### @certible/use-matomo 的下载量有多少？

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

### @certible/use-matomo 还在维护吗？

最新版本 1\.3\.0 发布于 2026/11/09（今天）；至今共发布 6 个版本，其中过去 12 个月发布了 4 个；首次发布于 2025/08/11。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。