vue-matomo

    4.1.0 • Public • Published

    VueMatomo

    npm vue2 vue3 npm bundle-size license

    Link your Piwik/Matomo installation. Compatible with vue 2.x and 3.x.

    Installation

    npm install --save vue-matomo

    Browser

    <!-- Include after Vue -->
    <!-- Local files -->
    <script src="vue-matomo/dist/vue-matomo.js"></script>
    
    <!-- From CDN -->
    <script src="https://unpkg.com/vue-matomo"></script>

    Usage

    Bundler (Webpack, Rollup)

    import Vue from 'vue'
    import VueMatomo from 'vue-matomo'
    
    Vue.use(VueMatomo, {
      // Configure your matomo server and site by providing
      host: 'https://matomo.example.com',
      siteId: 5,
    
      // Changes the default .js and .php endpoint's filename
      // Default: 'matomo'
      trackerFileName: 'matomo',
    
      // Overrides the autogenerated tracker endpoint entirely
      // Default: undefined
      // trackerUrl: 'https://example.com/whatever/endpoint/you/have',
    
      // Overrides the autogenerated tracker script path entirely
      // Default: undefined
      // trackerScriptUrl: 'https://example.com/whatever/script/path/you/have',
    
      // Enables automatically registering pageviews on the router
      router: router,
    
      // Enables link tracking on regular links. Note that this won't
      // work for routing links (ie. internal Vue router links)
      // Default: true
      enableLinkTracking: true,
    
      // Require consent before sending tracking information to matomo
      // Default: false
      requireConsent: false,
    
      // Whether to track the initial page view
      // Default: true
      trackInitialView: true,
    
      // Run Matomo without cookies
      // Default: false
      disableCookies: false,
    
      // Require consent before creating matomo session cookie
      // Default: false
      requireCookieConsent: false,
    
      // Enable the heartbeat timer (https://developer.matomo.org/guides/tracking-javascript-guide#accurately-measure-the-time-spent-on-each-page)
      // Default: false
      enableHeartBeatTimer: false,
    
      // Set the heartbeat timer interval
      // Default: 15
      heartBeatTimerInterval: 15,
    
      // Whether or not to log debug information
      // Default: false
      debug: false,
    
      // UserID passed to Matomo (see https://developer.matomo.org/guides/tracking-javascript-guide#user-id)
      // Default: undefined
      userId: undefined,
    
      // Share the tracking cookie across subdomains (see https://developer.matomo.org/guides/tracking-javascript-guide#measuring-domains-andor-sub-domains)
      // Default: undefined, example '*.example.com'
      cookieDomain: undefined,
    
      // Tell Matomo the website domain so that clicks on these domains are not tracked as 'Outlinks'
      // Default: undefined, example: '*.example.com'
      domains: undefined,
    
      // A list of pre-initialization actions that run before matomo is loaded
      // Default: []
      // Example: [
      //   ['API_method_name', parameter_list],
      //   ['setCustomVariable','1','VisitorType','Member'],
      //   ['appendToTrackingUrl', 'new_visit=1'],
      //   etc.
      // ]
      preInitActions: [],
    
      // A function to determine whether to track an interaction as a site search
      // instead of as a page view. If not a function, all interactions will be
      // tracked as page views. Receives the new route as an argument, and
      // returns either an object of keyword, category (optional) and resultsCount
      // (optional) to track as a site search, or a falsey value to track as a page
      // view.
      // Default: false, i.e. track all interactions as page views
      // Example: (to) => {
      //   if (to.query.q && to.name === 'search') {
      //     return { keyword: to.query.q, category: to.params.category }
      //   } else {
      //    return null
      //   }
      // }
      trackSiteSearch: false
    });
    
    // Now you can access piwik api in components through
    this.$matomo
    
    // or
    window._paq.push
    
    // or through
    window.Piwik.getTracker

    For available operations see the matomo api docs

    Note on async loading

    This plugin loads the matomo.js asynchronously, which means it is possible that $matomo is not (yet) loaded. Furthermore anti-tracking plugins on browsers might block matomo.js entirely. You should always guard your calls to $matomo, or use window._paq.push:

    this.$matomo && this.$matomo.trackPageView()
    
    // Or...
    
    window._paq.push(['trackPageView'])

    Note on external link tracking

    When using the option to trackExternalLinks, vue-matomo ensures the corresponding Matomo method is called after each navigation event. Matomo scans the entire DOM for external links and adds its link handling. This means that if your external links are rendered dynamically these links may not be picked up. You need to call this method manually if links might not exist after the page has finished rendering (for example if the links come from some REST call). For more information refer to https://developer.matomo.org/guides/spa-tracking#link-tracking

    this.$matomo && this.$matomo.enableLinkTracking()
    
    // Or...
    
    window._paq.push(['enableLinkTracking'])

    Nuxt

    Nuxt can work by creating a plugin that will load VueMatomo with SSR disabled. Note how the router is passed in the second snippet:

    // nuxt.config.js
    
    export default {
      plugins: [
        { src: '~/plugins/vue-matomo.js', ssr: false }
      ]
    }
    
    // plugins/vue-matomo.js
    
    import Vue from 'vue'
    import VueMatomo from 'vue-matomo'
    
    export default ({ app }) => {
      Vue.use(VueMatomo, {
        router: app.router
    
        /** Other configuration options **/
      })
    }

    Ignoring routes

    It is possible to ignore routes using the route meta:

    {
      path: '/page-2',
      name: 'Page2',
      component: Page2,
      meta: {
        analyticsIgnore: true
      }
    }

    Managing tracking consent

    First of all load the plugin with the requireConsent option enabled:

    Vue.use(VueMatomo, {
      // ...
      requireConsent: true
    })

    Matomo has a built in way to give and remember consent. The simplest way is to simply use this method provided by Matomo:

    <button @click="handleConsent()">Accept Tracking</button>
    
    handleConsent() {
      this.$matomo.rememberConsentGiven()
    }

    Another option is to use your own implementation for remembering consent. In that case you can simply call this.$matomo.setConsentGiven() on each page load when you establish that the user has given consent.

    Managing cookie consent

    You can use Matomo Analytics without consent and cookie banner. For more information see matomo faq: "How do I use matomo analytics without consent or cookie banner?.

    First of all load the plugin with the requireCookieConsent option enabled:

    Vue.use(VueMatomo, {
      // ...
      requireCookieConsent: true
    })

    Matomo has a built in way to give and remember consent. The simplest way is to simply use this method provided by Matomo:

    <button @click="handleConsent()">Accept Cookies</button>
    
    handleConsent() {
      this.$matomo.rememberCookieConsentGiven()
    }

    Another option is to use your own implementation for remembering cookie consent. In that case you can simply call this.$matomo.setCookieConsentGiven() on each page load when you establish that the user has given cookie consent.

    Build

    Bundle the js and css of to the dist folder:

    npm run build

    License

    MIT

    Keywords

    none

    Install

    npm i vue-matomo

    DownloadsWeekly Downloads

    8,438

    Version

    4.1.0

    License

    MIT

    Unpacked Size

    20.5 kB

    Total Files

    6

    Last publish

    Collaborators

    • amazingdreams