EventTracker

A library for capturing and distributing event tracking data.

Installation

$ npm i --save 'rentpath/event-tracker'

Usage

Create a new EventTracker instance, specifying which providers, trackers, and reducers to use.

const tracker = EventTracker.create({
  providers: [
    ['Tealium', { env: 'dev', account: 'acme', profile: 'primary' }]
  ],
  trackers: [
    'Click',
    'Select'
  ],
  reducers: [
    'Session',
    'Element'
  ]
})

API

EventTracker.create(config)

Creates a new tracker instance.

const tracker = EventTracker.create({ ... })

tracker.track(action, [props])

Records a custom user action.

tracker.track('user_registration', { userId: 123 })

tracker.view([props])

Records a page view action.

tracker.view({ page: 'home' })

tracker.include(props, merge = true)

Attaches additional data to every subsequent tracking event. Data is merged by default if called multiple times, unless the merge argument is false, in which case any existing data is overwritten. Note: data does not persist between separate page loads.

tracker.include({ browser: 'Chrome' })

Configuration

Each EventTracker instance needs to be configured to use at least a single provider, and optionally trackers and/or reducers.

Providers

Providers are 3rd party tag analytics services that offer custom event tracking, such as Tealium, Google Tag Manager or Adobe. In the context of EventTracker they are implemented as proxy adapters to the API's offered by each service.

Tealium

Tealium is a real-time data platform and tag management service. It is the only provider currently supported natively by EventTracker.

Options

| Option | Type | Default | Description | | --- | --- | --- | --- | env | string | dev | The TealiumIQ environment. Options are dev, 'qa', prod. | account | string | undefined | The TealiumIQ account name. | profile | string | undefined | The TealiumIQ profile name.

GoogleTagManager

GoogleTagManager is a real-time data platform and tag management service.

Options

| Option | Type | Default | Description | | --- | --- | --- | --- | gtmId | string | undefined | Tag Manager Id. | dataLayer | object | {} | Default dataLayer values | auth | string | undefined | authentication for the container | preview | string | undefined | preview id for the container

Trackers

Trackers are observers that listen for native DOM events, and record corresponding tracking actions. The following trackers are currently supported:

View

Records a view action on page load (DOMContentLoaded).

Click

Records a click action on all native click events.

Select

Records a select action on all native change events.

Form

Records a submit action on all native submit events.

Reducers

Named after the reduce method found in many programming languages, reducers are utilities for adding additional information to each tracking event that gets dispatched. They are called reducers because they are implemented as functions that receive the data payload as an argument, and whatever they return gets sent to the provider adapter. The following reducers are currently supported:

Device

Adds information about the device being used.

Provided Data

| Field | Description | --- | --- | screen_type | The type of device being used, determined by screen size. | screen_resolution | The device screen size. | operating_system | The device operating system.

Options

| Option | Type | Default | Description | | --- | --- | --- | --- | breakpoints | object | { mobile: 0, tablet: 768, desktop: 1024 } | An object whose keys represent screen types, and values represent breakpoint thresholds.

Browser

Adds information about the browser being used.

Provided Data

| Field | Description | --- | --- | browser | The browser type (e.g. Chrome) | browser_size | The browser size (width x height) | browser_version | The browser version

Request

Adds information about the current page request.

Provided Data

| Field | Description | --- | --- | url | The url of the current page. | path | The pathname of the current url. | hash | The url hash. | domain | The current domain. | query_string | The query string on the current url.

Meta

Adds data collected from meta tags.

Options

| Option | Type | Default | Description | | --- | --- | --- | --- | filter | string | null | A DOM selector used to filter which meta tags to use.

Session

Adds session/visitor ID.

Options

| Option | Type | Default | Description | | --- | --- | --- | --- | visitorKey | string | rp_visitor_id | The name of the cookie used to store the visitor ID. | sessionKey | string | rp_session_id | The name of the cookie used to store the session ID. | visitorAge | int | 86400 * 365 * 5 * 1000 (5 years) | The expiry age of the visitor cookie in milliseconds. | sessionAge | int | 30 * 60 * 1000 (30 minutes) | The expiry age of the session cookie in milliseconds.

Provided Data

| Field | Description | --- | --- | visitor_id | The unique ID used to identify a user. | visit_id | A unique ID used to identify a user session.

Element

Adds data collected from data tags placed on DOM nodes associated with native events (e.g. click events).

Options

| Option | Type | Default | Description | | --- | --- | --- | --- | tagPrefix | string | data-tag_ | The beginning part of the node attribute used to extract data.

TagManagerEvent

Adds data collected from data tags and transforms to GTM specific KVP's (e.g. click events).

Event

Adds information extracted from event objects.

Provided Data

| Field | Description | --- | --- | x_coordinate | The mouse position relative to the left edge of the document for click events. | y_coordinate | The mouse position relative to the top edge of the document for click events.

Development

Scripts

• npm run compile - Compiles the module to disk (~/lib).
• npm run compile:watch - Same as npm run compile but watches files for changes.
• npm run lint - Lints all files.
• npm run lint:fix - Lints all files and attempts to fix any issues.
• npm run test - Runs unit tests.
• npm run test:watch - Same as npm test but watches files for changes.
• npm run test:cov - Generates a test coverage report.

Distribution

Execute one of the following commands

npm version patch -m "bump to %s"
npm version minor -m "bump to %s"
npm version major -m "bump to %s"