用户- matomo

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

安装

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

使用量

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);

时间轴:

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);

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

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

夸萨

// 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 函数接受配置对象,其选项如下:

需要的选项

选项

初始页面视图

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

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

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从你的第一通电话开始.

带有全部选项的示例

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 (数目,可选): 事件的价值

示例

// 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

示例

// 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 重设

示例

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

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

destroy()

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

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

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

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)在初始化时被排入队列. 它拒绝当脚本无法加载时.

示例

await matomo.ready;

push(args)

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

参数:

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

示例

// 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 跟踪指南。 。 。 .

许可证

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

关于

这个软件包由 可认证。 。 。 .