A library for capturing and distributing event tracking data.
$ npm i --save 'rentpath/event-tracker'
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'
]
})
Creates a new tracker instance.
const tracker = EventTracker.create({ ... })
Records a custom user action.
tracker.track('user_registration', { userId: 123 })
Records a page view action.
tracker.view({ page: 'home' })
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' })
Each EventTracker
instance needs to be configured to use at least a single provider, and optionally trackers and/or reducers.
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 is a real-time data platform and tag management service. It is the only provider currently supported natively by EventTracker
.
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 is a real-time data platform and tag management service.
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 are observers that listen for native DOM events, and record corresponding tracking actions. The following trackers are currently supported:
Records a view
action on page load (DOMContentLoaded
).
Records a click
action on all native click events.
Records a select
action on all native change
events.
Records a submit
action on all native submit
events.
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:
Adds information about the device being used.
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. |
Option | Type | Default | Description |
---|---|---|---|
breakpoints |
object | { mobile: 0, tablet: 768, desktop: 1024 } |
An object whose keys represent screen types, and values represent breakpoint thresholds. |
Adds information about the browser being used.
Field | Description |
---|---|
browser | The browser type (e.g. Chrome) |
browser_size | The browser size (width x height) |
browser_version | The browser version |
Adds information about the current page request.
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. |
Adds data collected from meta tags.
Option | Type | Default | Description |
---|---|---|---|
filter |
string | null |
A DOM selector used to filter which meta tags to use. |
Adds session/visitor ID.
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. |
Field | Description |
---|---|
visitor_id | The unique ID used to identify a user. |
visit_id | A unique ID used to identify a user session. |
Adds data collected from data
tags placed on DOM nodes associated with native events (e.g. click
events).
Option | Type | Default | Description |
---|---|---|---|
tagPrefix |
string | data-tag_ |
The beginning part of the node attribute used to extract data. |
Adds data collected from data
tags and transforms to GTM specific KVP's (e.g. click
events).
Adds information extracted from event objects.
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. |
npm run compile
- Compiles the module to disk (~/lib).npm run compile:watch
- Same asnpm 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 asnpm test
but watches files for changes.npm run test:cov
- Generates a test coverage report.
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"