piveau-universal-piwik

A Vue plugin exposing common tracking methods for piveau web apps using Matomo or Piwik Pro.

Installation

npm i @piveau/piveau-universal-piwik

for latest builds:

npm i @piveau/piveau-universal-piwik@beta

Usage

Setup the plugin in main.js. This will add $piwik to Vue to be accessible as app.prototype.$Vue or this.$piwik in all Vue components.

Refer to the demo for an example on how to use this package.

Common usage could look like this:

// In main.ts
import UniversalPiwik from '@piveau/piveau-universal-piwik';
import { router } from './router'; // Optional
import { createApp } from 'vue'
import App from './App.vue'

const app = createApp(App);

app.use(UniversalPiwik, {
  router, // Optional
  isPiwikPro: true
  trackerUrl: 'http://piwik-pro-host.example.org/',
  siteId: 'your-site-id',
  debug: import.meta.env.NODE_ENV === 'development',
});

<template>
  <div id="app">
    <div id="cookies">
      Change consent:
      <div class="flexy consent-action">
        <button class="btn" @click="accept">Accept</button>
        <button class="btn" @click="decline">Decline</button>
        <button class="btn" @click="postpone">Postpone</button>
      </div>
    </div>
    <div id="control-panel">
      <h2>Simulate interactions</h2>
      <div class="flexy">
        <button class="btn" @click="external">External link</button>
        <button class="btn" @click="download">Download</button>
      </div>
    </div>
    <div id="nav">
      <router-link to="/home">Home</router-link> |
      <router-link to="/about">About</router-link>
    </div>
    <router-view/>
  </div>
</template>

<script>
export default {
  name: 'App',
  created() {
    this.$piwik.init();
  },
  methods: {
    accept() {
      this.$piwik.consentGiven();
    },
    decline() {
      this.$piwik.consentDeclined();
    },
    postpone() {
      this.$piwik.consentNoDecision();
    },
    external() {
      this.$piwik.trackOutlink('https://example.org/outlink');
    },
    download() {
      this.$piwik.trackDownload('https://example.org/download');
    }
  }
}
</script>

Plugin reference

Plugin construction options

options = {
    router: VueRouter,
    isPiwikPro: true,
    trackerUrl: 'http://piwik-pro-host.example.org/',
    siteId: 'your-site-id',
    debug: import.meta.env.NODE_ENV === 'development',
    immediate: false,
    removeCookiesWhenNoConsent: true,
    stopWhenNoConsent: true,
    verbose: false,
    pageViewOptions: { onlyTrackWithLocale: true, delay: 1000, beforeTrackPageView: (tracker, to, from) => {} },
    disabled: false,
    requireConsent: 'consent',
}

router

type: VueRouter

when specified, uses default router hooks in order to track page changes. Set it to undefined when it is desired to handle page views manually.

isPiwikPro

type: boolean
default: false

if true, uses Piwik Pro. If false, uses Matomo.

trackerUrl

type: string

Tracker url for Matomo or Piwik Pro

siteId

type: string

Tracker site id for Matomo or Piwik Pro

pageViewOptions

type: Object<{ useDatasetsMinScoreFix: boolean, onlyTrackWithLocale: boolean, delay: number, beforeTrackPageView(tracker, to, from): Function, documentTitleResolver(to, from, title) }>

Options for the default page view tracking implementation. Set onlyTrackWithLocale to true to only track when there is a locale query in the destination route when navigating. This avoids duplicated page views for piveau applications. Set useDatasetsMinScoreFix to true to only track pages named 'Dataset' when there is a minScore query.

Provide beforeTrackPageView hook to do tasks before a page is being tracked but after a navigation is registered as valid.

Provide documentTitleResolver to override the default document title resolver. If not given, use document.title as document title.

Set delay for Piwik Pro tracker for delayed page view tracking after a navigation has been confirmed in milliseconds. This avoids undefined page titles for piveau applications.

debug

type: boolean
default: false

If true, enables debug logging on console. Useful for development.

verbose

type: boolean
default: false

If true and debug is true, additional logging on console.

immediate

type: boolean
default: false

if true, executes piwik init script immediately.

removeCookiesWhenNoConsent

type: boolean
default: true

(PiwikPro only) if true, removes all PiwikPro related cookies when user does not give consent (called by $piwik.declineConsent())

stopWhenNoConsent

type: boolean
default: true

(PiwikPro only) if true, stops tracking when uder does not give consent (called by $piwik.declineConsent())

disabled

type: boolean
default: false

If true, disables all tracker instance methods (the tracker instance still exists). Cannot be changed after initialization.

requireConsent

type: string
default: 'consent'

If 'consent', requires user consent to track using using requireConsent. If 'cookieConsent', requires user consent to set cookies using requireCookieConsent. If falsy, does not require consent.

useSuspendFeature

type: boolean
default: false

(PiwikPro only) If true, enables suspendFilter and resume methods.

$piwik instance properties

isStopped

type: boolean

if true, indicates that $piwik is stopped.

$piwik instance methods

init

Signature:

$piwik.init()

Initializes Tracker script. Note that this may set cookies and execute external $piwik.JavaScript code.

consentGiven

consentDeclined

consentNoDecision

Signatures:

$piwik.consentGiven()
$piwik.consentDeclined()
$piwik.consentNoDecision()

Accepts, declines, and postpones cookies for tracking

trackPageView

trackDatasetDetailsPageView

trackDownload

trackOutlink

trackEvent

trackGotoResource

Signatures:

$piwik.trackPageView(url, title)
$piwik.trackDatasetDetailsPageView()
$piwik.trackDownload(url, dimensions)
$piwik.trackOutlink(url, dimensions)
$piwik.trackEvent(category, action, name, value)
$piwik.trackGotoResource()

trackInteraction

Signature:

$piwik.trackInteraction(eventType = 'screen_load', variables = {})

(Piwik Pro tracker only) track interaction with specific event type and variables.

stop

Signature:

$piwik.stop()

suspendFilter

Signature:

$piwik.suspendFilter(filterFn: (data: Object) => boolean)

(Piwik Pro tracker only) Suspends PiwikPro by intercepting all incoming events. If filterFn is given, will not intercept incoming event, if filterFn(event) === true

resume

Signature:

$piwik.resume()

(Piwik Pro tracker only) Resumes PiwikPro by emitting all events that were emitted during suspension.

$universalPiwik instance methods

beforeTrackPageView

Calls callbackFn() when a valid route is entered and is going to track a page view. Only works when router option is set on initialization.

Signature:

$universalPiwik.beforeTrackPageView(callbackFn)

callbackFn Signature:

callbackFn(to: Route, from: Route)

Project setup

npm install

Compiles and minifies for production

npm run build:lib

Lints and fixes files

npm run lint

Customize configuration

See Configuration Reference.

@piveau/piveau-universal-piwik