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.