Matomo Tracker (JavaScript)

Stand alone library for using Matamo tracking in frontend projects

Installation

npm install @datapunt/matomo-tracker-js

Usage

Before you're able to use this Matomo Tracker you need to initialize Matomo with your project specific details.

Initialize:

import MatomoTracker from '@datapunt/matomo-tracker-js'

const tracker = new MatomoTracker({
  urlBase: 'https://LINK.TO.DOMAIN',
  siteId: 3,
  userId: 'UID76903202', // optional, default value: `undefined`.
  trackerUrl: 'https://LINK.TO.DOMAIN/tracking.php', // optional, default value: `${urlBase}matomo.php`
  srcUrl: 'https://LINK.TO.DOMAIN/tracking.js', // optional, default value: `${urlBase}matomo.js`
  disabled: false, // optional, false by default. Makes all tracking calls no-ops if set to true.
  heartBeat: { // optional, enabled by default
    active: true, // optional, default value: true
    seconds: 10 // optional, default value: `15
  },
  linkTracking: false, // optional, default value: true
  alwaysUseSendBeacon: true, // optional, default value: true
  configurations: { // optional, default value: {}
    // any valid matomo configuration, all below are optional
    disableCookies: true,
    setSecureCookie: true,
    setRequestMethod: 'POST'
  }
})

After initialization you can use the Matomo Tracker to track events and page views like this:

import MatomoTracker from '@datapunt/matomo-tracker-js'

const tracker = new MatomoTracker({
  /* setup */
})

tracker.trackPageView()

tracker.trackEvent({
  category: 'sample-page',
  action: 'click-event',
  name: 'test', // optional
  value: 123, // optional, numerical value
})

tracker.trackLink({
  href: 'https://link-to-other-website.org',
})

Advanced usage

By default the Matomo Tracker will send the window's document title and location, but you're able to send your own values. Also, custom dimensions can be used:

import MatomoTracker from '@datapunt/matomo-tracker-js'

const tracker = new MatomoTracker({
  /* setup */
})

tracker.trackPageView({
  documentTitle: 'Page title', // optional
  href: 'https://LINK.TO.PAGE', // optional
  customDimensions: [
    {
      id: 1,
      value: 'loggedIn',
    },
  ], // optional
})

tracker.trackEvent({
  category: 'sample-page',
  action: 'click-event',
  name: 'test', // optional
  value: 123, // optional, numerical value
  documentTitle: 'Page title', // optional
  href: 'https://LINK.TO.PAGE', // optional
  customDimensions: [
    {
      id: 1,
      value: 'loggedIn',
    },
  ], // optional
})

tracker.trackLink({
  href: 'https://link-to-your-file.pdf',
  linkType: 'download', // optional, default value 'link'
})

Next to the tracking of events, this project also supports tracking site searches:

import MatomoTracker from '@datapunt/matomo-tracker-js'

const tracker = new MatomoTracker({
  /* setup */
})

tracker.trackSiteSearch({
  keyword: 'test',
  category: 'blog', // optional
  count: 4, // optional
  documentTitle: 'Page title', // optional
  href: 'https://LINK.TO.PAGE', // optional
  customDimensions: [
    {
      id: 1,
      value: 'loggedIn',
    },
  ], // optional
})

Or if you want to stay away from inline JavaScript events, this project can be used to track events from buttons with data attributes:

HTML5 data-attributes

<button
  data-matomo-event="click"
  data-matomo-category="sample-page"
  data-matomo-action="click-event"
  data-matomo-name="test" // optional
  data-matomo-value="123" // optional, numerical value
  type="button">
  Track me!
</button>

import MatomoTracker from '@datapunt/matomo-tracker-js'

const tracker = new MatomoTracker({
  /* setup */
})

// Load the event listeners
tracker.trackEvents()

// Track page views
tracker.trackPageView()

References

• Matomo JavaScript Tracking Guide