Piwik React Router

Piwik analytics component for react-router

Installation

npm install piwik-react-router --save

or

yarn add piwik-react-router

Features

• asynchronous loading of Piwik
• javascript error tracking
• low level access to piwik.push()

Usage

Simply create your instance with the same url and siteId as described in the piwik documentation and connect it to your history object.

Starting with v2.0 react-router won't provide a default history. Why?.

const PiwikReactRouter = require('piwik-react-router');

const piwik = PiwikReactRouter({
    url: 'your-piwik-installation.com',
    siteId: 1
});

/**
 * Create your history in advance. Please head over to the react-router FAQ for more infos:
 * @see https://github.com/ReactTraining/react-router/blob/master/FAQ.md#how-do-i-access-the-history-object-outside-of-components
*/
<Router history={piwik.connectToHistory(history)}>
    <Route path="/" component={MyComponent} />
</Router>

If you're using react-router prior to v1.0 please head over to the react-router0.13.x branch.

For the url-option you can also include http:// or https:// in the beginning of the url, if you piwik installation is on ssl, but your react-site is not, or visa versa.

Options

enableLinkTracking: true

Link tracking to track outgoing and download links is enabled by default.

userId: undefined

User ID to associate every request with a username or email. More information here: User ID

updateDocumentTitle: true

Updates the document title before adding a new page view as the title may changed during the route rendering. Make sure you call piwik.track after React has rendered the <Handler /> to make this work correctly. If you don't know how to update the title, check out the great react-document-title or react-helmet module.

trackErrors: false

By enabling this option occurring javascript errors will be tracked as a JavaScript Error piwik event.

see http://davidwalsh.name/track-errors-google-analytics for further details

trackErrorHandler: [default error handler]

Set a custom error handler for javascript errors, allowing custom formatting of events published when an error occurs.

see Tracking Events for further details

ignoreInitialVisit: false

By enabling ignoreInitialVisit it connects to the history without tracking the initial visit.

injectScript: true

By disabling injectScript the piwik.js script will not be injected automatically to allow a separate loading.

Starting with version 0.12.0 the usually required options siteId and url are now optional if a running instance of the piwik tracking script is detected by validating the following cases:

• A <script> src matches the url defined via opts.url and opts.clientTrackerName
• siteId and setTrackerUrl calls are already present in window._paq

clientTrackerName: 'piwik.js'

The name of the piwik.js static resource on the Piwik server. Set this option if the Piwik instance uses a different name.

serverTrackerName: 'piwik.php'

The name of the piwik.php script on the Piwik server. Set this option if the Piwik instance uses a different name.

API

track (Location location)

Adds a page view from a history Location if the path changed.

path = location.pathname + location.search

push (args)

Pushes the specified args to the Piwik tracker the same way as you're using the _paq.push(args); directly. You can use this method as the low-level api to call methods from the Piwik API, track events or call custom functions.

setUserId (userId)

Sets the specified user id to the Piwik tracker after PiwikReactRouter has been initialized. It wraps around the 'setUserId' method of Piwik User ID

trackError (error, [eventName])

Tracks the given error as a new Piwik Event for the given event name. If you don't specify any name here it will fallback to JavaScript Error.

The handler is overriden if the trackErrorHandler option is set.

connectToHistory(history, [modifier])

Adds a listener to the passed in history to trigger track(location) whenever the history changes. The optional modifier function (added in version 0.9.0) acts as a proxy to allow the modification of the given location before the track(location) function is called.

const modifier = function (location) {
    location.search = 'campain=ID';

    return location;
}

<Router history={piwik.connectToHistory(history, modifier)}>

Connecting to the history also tracks the location of the initial visit since release 0.7.0 if not manually disabled via ignoreInitialVisit

disconnectFromHistory()

Disconnects Piwik from a previous connected history. Returns whether it could successfully disconnect.

A note on serverside rendering

Piwik tracking is disabled for serverside rendering and all API methods are replaced with noop-functions so you don't have to worry about it.