@schibsted/niche-tracking

Niche Tracking

Description

This repository contains code we use for tracking. The goal of niche-tracking is to be used in all of our products, however currently it's used only for tek-web.

Local development

Nothing fancy here. First install dependencies clone repository, open terminal and run.

npm i

Next start transpiling the source code:

npm run transpile:watch

Make your project available as package locally:

npm link

And in project you need:

npm link @schibsted/niche-tracking

And now you are all good. Your project will now use the local version of niche-tracking instead of the one in node_modules.

Supported trackers

Currently pulse, google analytics and linkpulse trackers are implemented.

How to use it and how it works

Package exports Tracker class and all implemented tracker objects. You can import it like this:

import { Tracker, pulse } from '@schibsted/niche-tracking';

Next you need to create tracker instance with proper parameters

const tracker = new Tracker({
    pageviewTrackerMappers,
    eventTrackerMappers,
    logger,
    enabled,
    mutateScript,
    trackers: [pulse],
});

When you have the tracker instance you will have to initialize it with proper config. Calling this method will download all tracking scripts and actually make them work. Don't worry, you can call tracker.pageView and tracker.event methods before calling tracker.initialize as all build in trackers have event queue that will be unloaded after initialization.

tracker.initialize methods takes config with tracker specific options. You can see them here:

• pulse
• google analytics
• linkpulse

Let's discuss Tracker constructor parameters

logger

Optional object containing 4 methods:

• log
• info
• warn
• error

trackers

Array with trackers you want to use. You can import those from package or provide your own. They must be objects with three methods:

• pageview
• event
• initialize

pageViewTrackerMappers, eventTrackerMappers

These are objects with following format:

{
    [TYPE]: {
        [TRACKERNAME]: optionTransormFunction
    }
}

enabled

This flag lets you disable the tracking. Please keep in mind that even if you set enabled: false mappers will still be called to keep the behaviour as close to production as it can be.

Where TYPE is unique name of event type you want to track (defined by you), TRACKERNAME is (who would have guessed?) tracker name and optionTransformFunction is function that transforms data from option object to data that specific tracker needs for that event.

For example it could look like this:

const pageViewTrackerMappers = {
    [SCREENS.SECTION]: {
        pulse: options => ({
            object: {
                id: 'sectionScreen',
                type: 'Listing',
                category: options.type === 'guide' ? 'reise>byguide' : 'reise',
                filters: {
                    query: `?page=${options.pagination}`,
                },
                name: options.title,
            },
        }),
        linkpulse: options => ({
            contentType: 'Sectionpage',
            pagination: options.pagination,
            url: getCurrentUrl(),
            referer: options.appReferrer,
        }),
        googleAnalytics: options => ({
            pathname: options.pathname,
        })
    }
}

Remember out tracker instance? Just to remind you:

const tracker = new Tracker({
    pageviewTrackerMappers,
    eventTrackerMappers,
    logger,
    enabled,
    mutateScript,
    trackers: [pulse, linkpulse, googleAnalytics],
});

Now each time you call tracker.pageView(SCREENS.SECTION, options) the tracker will create:

• pulseSpecificOptions,
• linkpulseSpecificOptions,
• googleAnalyticsSpecificOptions according to transform functions you provided in pageViewTrackerMappers.

Next it will call pulse.pagewiew(pulseSpecificOptions), linkpulse.pageView(linkpulseSpecificOptions), googleAnalytics.pageView(googleAnalyticsSpecificOptions).

As you can see it enables you to implement most of the tracking in declarative way. All you need is choose which trackers you need and provide proper options mapping.

As a recommendation I suggest providing redux state as options and using selectors in option transorm function.

mutateScript

This function allows for mutating scripts that will be injected in dom. You can for example add css class to them.

mutateScript: script => {
    script.classList.add('no-prerender');
}

Experiments

Experiments is a field used for A/B tests tracking. It should be passed during tracker initalization and contain list of all A/B tests that user is part of. For example it could look like this:

const tracker = new Tracker({
    pageviewTrackerMappers,
    eventTrackerMappers,
    logger,
    enabled,
    mutateScript,
    trackers: [pulse],
});
const experiments = [
    {
        id: 'experimentId', // unique identifier of A/B test
        name: 'Readable explanation of A/B test',
        variant: 'variant-b' // identifier of a variant which will be served to user
    },
    {
        id: 'anotherExperimentId',
        name: 'Readable explanation of another A/B test',
        variant: 'another-variant-a'
    },
];
tracker.initalize({
    ...trackersConfig,
    clientId,
    experiments,
})

In the case of the pulse tracker, this list will be added to every page view and engagement event.

Polyfills

This package requires only one polyfill: Promise.

Useful links

To get more general idea of how tracking works check our team docs