Have ideas to improve npm?Join in the discussion! »

    @datapunt/matomo-tracker-js
    TypeScript icon, indicating that this package has built-in type declarations

    0.4.0 • Public • Published

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

    Install

    npm i @datapunt/matomo-tracker-js

    DownloadsWeekly Downloads

    10,314

    Version

    0.4.0

    License

    MPL-2.0

    Unpacked Size

    77.7 kB

    Total Files

    35

    Last publish

    Collaborators

    • avatar
    • avatar