tracking.js

Wrapper for handling tracking events via Segment or GTM

Installation

npm install --save @pod-point/tracking.js

Deploy

To publish a new version to NPM run the following commands:

npm version [patch|minor|major]

This creates an automatic commit with the new version for the package.json, so be sure to push that commit before merging to main.

git push --tags

This pushes the version tag to Github, which you can see under the releases tab.

Usage

Either import the module in Node:

import { segment, gtm } from '@pod-point/tracking';

Or in the browser, create a new <script> tag to include the library on the page:

<script src="https://unpkg.com/@pod-point/tracking.js@<version>/dist/bundle.min.js"></script>

Init

Support by: Segment, GTM

For Segment, should only be used if the api key needs to be added dynamically. Otherwise use the snippet.

// Segment example
segment.init('segment-key');

// GTM example
gtm.init('gtm-id');

Track

Support by: Segment, GTM

tracking.track('Event name', {
    properties: 1,
});

Track Page

Support by: Segment

https://segment.com/docs/libraries/analytics.js/#page

Used to manually track a page view allowing to set the url.

tracking.trackPage('http://website.com/url?page=1');

Used to manually track a page view allowing to append more data to the default sent by the lib.

tracking.page({ label: 'label' });

Track Form

Support by: Segment

Used to track a form submit.

const form = document.querySelector('#form-to-track');
// The form fields you want to track
const fieldsToTrack = ['product', 'price'];
// The form fields which are only passed to the identify/alias call
const fieldsForIdentity = ['email', 'first_name', 'last_name'];

form.addEventListener('submit', e => {
    // Stop form from submitting automatically
    e.preventDefault();

    // Do anything else you want to do before the data is sent here, such as validation
    // ...

    tracking.trackForm('Event name', fieldsToTrack, fieldsForIdentity).then(() => {
        // Do anything you want to do after the tracking request has completed here, such as submitting the form
        // ...

        form.submit();
    });
});

Identify

Support by: Segment

Used to identify a user.

https://segment.com/docs/libraries/analytics.js/#identify

tracking.identify('[email protected]', {
    userParams: 1,
});

Alias

Support by: Segment

Used to alias a user.

https://segment.com/docs/libraries/analytics.js/#page

tracking.alias('[email protected]').then(() => tracking.identify('[email protected]', userDetails));

Reset

Support by: Segment

Used to delete the cookies/localStorage set by Segment, resetting the id and traits of the user.

https://segment.com/docs/sources/website/analytics.js/#reset-logout

tracking.reset();

Implementations

Browser environment

See browser.js.

This file registers custom event listeners on the DOM for all supported tracking actions.

In your application, you can then dispatch events as so:

document.dispatchEvent(
    // Segment example
    helpers.createCustomEvent('tracking.init.segment', {
        detail: {
            key,
        },
    })
    // GTM example
    helpers.createCustomEvent('tracking.init.gtm', {
        detail: {
            key,
        },
    })
);

document.dispatchEvent(
    helpers.createCustomEvent('tracking.track', {
        detail: {
            event,
            properties,
            options,
        },
    })
);

document.dispatchEvent(
    helpers.createCustomEvent('tracking.trackPage', {
        detail: {
            url,
        },
    })
);

This file is bundled up and available to reference in your application via this script tag:

<script src="https://unpkg.com/@pod-point/tracking.js@<version>/dist/browser.min.js"></script>

This separation away from making tracking calls directly within an applications JavaScript is with cookie compliance in mind. This library drops various cookies, and isolating that plus any tracking functionality to this external script will mean it is what is identified and blocked by our cookie management solution as opposed to our applications JavaScript which would likely result in breaking changes to its functionality.

Node environment

See node.js.

This file initiates an event manager / emitter with listeners for the following tracking actions: tracking.init, tracking.track, and tracking.trackPage.

In your application, you can then dispatch events as so:

import eventManager from './node';

eventManager.emit('tracking.init', key);
eventManager.emit('tracking.track', event, properties, options);
eventManager.emit('tracking.trackPage', url);

This can be useful for decoupling making tracking calls away from an applications business logic.