@daun/analytics

Analytics

Easy way to get up and running with Google Analytics.

Personalized version of the original Analytics.js Boilerplate, with a few additions.

• Tracks uncaught errors
• Tracks custom user, session, and hit-level dimensions
• Sends an initial pageview
• Sends a pageload performance event
• Autoload the analytics.js script
• Supports sending custom events and page views

See this article for an in-depth explanation of the features used.

Installation

npm install @daun/analytics

Usage

This package automatically loads the Google Analytics library.

Recommended: load the tracking code lazily so it's non-blocking.

import('@daun/analytics').then(analytics => {
  analytics.init({ /* options */ })
})

Synchronous import is possible, but only recommended for separate entrypoints.

import { init } from '@daun/analytics'

init({ /* options */ })

API

init

Setup the tracker and set initial values.

init({
  trackingId: 'UA-X-XXXXXX',
  timeZone: 'Europe/London'
})

Options

• trackingId → Google Analytics tracking ID, required
• timeZone → Time zone (default: Europe/London)
• anonymizeIp → Anonymize last IP octet? (default: true)
• removeTrailingSlash → Remove trailing slash (default: true)

trackEvent

Track a custom event.

trackEvent({
  eventCategory: 'Video',
  eventAction: 'play',
  eventLabel: 'Video title'
})

trackPageview

Track a page view. This should only be required in rare cases where autotracking URL changes is not sufficient.

trackPageview('/some/page')

Autotrack

This setup includes a few useful autotrack plugins:

• clean-url-tracker
• max-scroll-tracker
• outbound-link-tracker
• page-visibility-tracker
• url-change-tracker

Custom dimensions & metrics

The boilerplate scripts use several custom dimensions and metrics that you'll need to set up within Google Analytics.

Custom dimensions

These can be set up on Google Analytics by going to the Admin section, clicking on Custom Definitions in the PROPERTY column will reveal a link to Custom Dimensions.

Make sure the dimension index number in the admin panel matches up with the number appended to dimension for the corresponding key in the dimensions object in the script you use; i.e. if when you set up the Hit Source dimension it ends up with an index of 12, then the dimensions object should include HIT_SOURCE: 'dimension12'.

Name	Script reference	Scope
Tracking Version	TRACKING_VERSION	Hit
Client ID	CLIENT_ID	User
Window ID	WINDOW_ID	Hit
Hit ID	HIT_ID	Hit
Hit Time	HIT_TIME	Hit
Hit Type	HIT_TYPE	Hit
Hit Source	HIT_SOURCE	Hit
Visibility State	VISIBILITY_STATE	Hit
Url Query Params	URL_QUERY_PARAMS	Hit

Custom metrics

These can be set up on Google Analytics by going to the Admin section, clicking on Custom Definitions in the PROPERTY column will reveal a link to Custom Metrics.

Make sure the metric index number in the admin panel matches up with the number appended to metric in the metrics object in the script you use; i.e. if when you set up the Max Scroll Percentage metric it ends up with an index of 9, then the metrics object should include MAX_SCROLL_PERCENTAGE: 'metric9'.

Name	Script reference	Scope	Formatting Type
Response End Time	RESPONSE_END_TIME	Hit	Integer
DOM Load Time	DOM_LOAD_TIME	Hit	Integer
Window Load Time	WINDOW_LOAD_TIME	Hit	Integer
Page Visible	PAGE_VISIBLE	Hit	Integer
Max Scroll Percentage	MAX_SCROLL_PERCENTAGE	Hit	Integer
Page Loads	PAGE_LOADS	Hit	Integer

Running the boilerplate locally

analytics.js boilerplate uses webpack to compile the source and webpack-dev-server to run it locally.

To install the dependencies and load the boilerplate in a browser, run the following commands:

npm install
npm start

Then visit localhost:8080 in your browser and open the developer console to see the analytics.js debug output.

Running different boilerplate versions

The boilerplate index.js JavaScript file imports the base boilerplate by default. To run a different version, replace the URL imported via import('./analytics/base.js') with the version you want to load.