@politico/analytics-tracker

A tool for page tracking on POLITICO interactives pages.

Usage

Install this library as a dependency.

$ yarn add @politico/analytics-tracker

Create a folder called analytics in your utilities directory (the location of this directory may differ depending on your template). Inside of that, make a filed called events.js and export constants for each event you want to track. (See Naming Your Events for more.)

export const ACTION_NAME_ONE = 'action-one';
export const ACTION_NAME_TWO = 'action-two';
export const ACTION_NAME_THREE = value => `action-three:${value}`;

There are two ways to use the analytics tracker depending on your template and personal preference.

As a Class

You can use the tracker as a class. If you need to track different things in different React components for example, you should instantiate it outside of your components, and import it as a module.

To use it as a class, create a file in your analytics directory called index.js. In it, instantiate a new tracker. You'll need to pass a configuration object (see Creating a Tracking Conf for more).

// analytics/index.js
import { AnalyticsTracker } from '@politico/analytics-tracker';

const tracker = new AnalyticsTracker(conf);

export default tracker;

Then you can import it along with an event string and use its event method, passing the name of the event as an argument.

// Some file with an action that should be tracked
import tracker from './path/to/analytics/';
import { ACTION_NAME_ONE } from './path/to/analytics/events.js';

tracker.event(ACTION_NAME_ONE);
tracker.event(ACTION_NAME_THREE('my-value'));

You can also track a page view (for use in SPAs) by invoking the class's view method, passing the name of the view (or the pageName in typical utag parlance) as the argument.

// Some file with an action that should be tracked
import tracker from './path/to/analytics/';
import { ACTION_NAME_ONE } from './path/to/analytics/events.js';

tracker.view('Page 2');

As a React Hook

You can also use it as a React hook. Pass the same conf into the useTracker hook to receive an object with a trackEvent key and a trackView key for their respective actions.

For ease of use, you should create a file in your analytics directory called index.js. In it, create a hook that returns the value of this hook while passing the conf object (see Creating a Tracking Conf for more). This way you only have to do it once.

import { useTracker } from '@politico/analytics-tracker';
import conf from '../path/to/conf';

export default function useMyTracker(){
  return useTracker(conf);
}

import useMyTracker from './path/to/analytics';
import { ACTION_NAME_ONE } from './path/to/analytics/events.js';

const MyComponent = props => {
    // ...

    const {trackEvent, trackView} = useMyTracker();
    const onButtonClick = () => {
      trackEvent(ACTION_NAME_ONE)
      trackView(props.pageName);
    }

    // ...
}

Creating a Tracking Conf

The definition for the tracking conf is the following. As a reminder params wrapped in [] are optional.

/**
 * A configuration object.
 * @param {Object} conf

 * @param {String} conf.appName - The name of your app. See below for more.
 * @param {String} conf.siteSection - The section of the site the app belongs to. Usually either "politics" or "elections".
 * @param {String} [conf.pageType=interactives] - Either "interactives" or "2020 Elections"
 * @param {String} [conf.pageSubType] - Usually the name of the app or a broader package the app belongs to. See Mitch if you're not sure if you need one.
 * @param {String} [conf.adUnitSection=politics] - Almost always "politics".
 * @param {String} [conf.freePaidContent=free] - Almost always "free".

 * @param {Object[]} conf.authors - A list of authors
 * @param {String} conf.authors[].name - The name of the author
 * @param {String} [conf.authors[].link] - A link to the authors bio
 */

Naming Your App

Each project should have its own app name. This value must be unique across all interactives and cannot have spaces. The easiest thing to use is the slug of your project. That will ensure it is unique and spaceless.

Naming Your Events

Event names should also be spaceless. If you have multiple groups of events, you can prefix your events with the name of the group followed by a colon.

For example, in my app, I have two views. One is called List and the other is called Detail. I might make the events related to actions in my List view something like list:nav-button-click and list:expand-button-click.

You may also have a situation where you have a list of slightly different variations on an action. In this case, rather than making one event for every vartion you can make a functional event.

For example, I have a datepicker with every year from 2000 to 2010. Instead of making one event for each date in the datepicker, I can use a functional event like this:

export const DATE_PICKED = date => `datepicked:${date}`;

Then when I want to use it I can pass a value to that event such as:

tracker.event(DATE_PICKED('2012'));

Finding The Data

So you've gone through all the work to track interactivity, but how do you find the results of this testing?

1. Go to the Omniture login
2. Choose to use the Experience Cloud login
3. Use the login for Adobe in the 1Password (the one for [email protected], not your personal one).
4. In "Workspace", make a new project (or edit an existing one of yours)
5. Drag "Interactives" (the dimension) on to the Freeform table. Then drop "Interactive Interaction" as a metric.
6. Then you can use the filter options on interactions to filter for only: interactives:YOUR-APP-NAME.