Questions? Ask in Slack #vcc-ui

@volvo-cars/tracking

A declarative way to add Google Tag Manager tracking data to your application. It supports multiple ways of sending analytics events by supporting event data inheritance and the possibility to send events with vanilla JavaScript without rendering/hydrating your React application.

💡 This package includes Typescript definitions

The simplest way of adding an event to GTM is by using the useTracker hook which returns a Tracker instance that exposes helpful methods that send different event types such as interaction or noninteraction. It sends these events by modifying the window.dataLayer global array. This array is watched for changes by GTM when embedded on a page, which means any pushes to this array will trigger a new GTM event.

() => {
  const tracker = useTracker();
  return (
    <View>
      <Button
        onClick={() => {
          tracker.interaction({
            eventAction: 'click',
            eventLabel: 'cta1',
          });
        }}
      >
        Button 1
      </Button>
      <Spacer />
      <Button
        onClick={() => {
          tracker.interaction({
            eventAction: 'click',
            eventLabel: 'cta2',
          });
        }}
      >
        Button 2
      </Button>
      {/* ↓↓↓ this is only to view the `window.dataLayer` in the preview above.*/}
      <DataLayerViewer />
    </View>
  );
};

In the above example, we send an interaction event and attach eventAction and eventLabel to it. Notice the event additions to window.dataLayer on each button click. It's also worth noticing how Tracker.interaction adds the event property automatically to each event. This is to distinguish between the types of events sent to GTM.

useTracker takes 3 optional arguments. The first is an event data object that will be added to all events sent by the returned Tracker. The second is any Tracker options and the third is options?.ignoreIfEmptyContext which is used in conjunction with the TrackingProvider mentioned below, this will disable sending events if the hook is not wrapped with a parent TrackingProvider.

To send page load events without needing user input, immediately on page load, you can be done by adding the PageTrackingProvider. There can only be one PageTrackingProvider in the tree per page.

render(
  <PageTrackingProvider pageName="Landing Page" pageType="Campaign">
    {children}
  </PageTrackingProvider>
  {/* ↓↓↓ this is only to view the `window.dataLayer` in the preview above.*/}
  <DataLayerViewer />
);

Notice how the events pushed to window.dataLayer in the above example include pageName and pageType.

All events are forced to be lowercase by default but it's also possible to disable this behaviour, based on specific requirements. This can be done with the forceLowerCase prop.

render(
  <PageTrackingProvider pageName="Landing Page" pageType="Campaign" forceLowerCase={false}>
    {children}
  </TrackingProvider>
  {/* ↓↓↓ this is only to view the `window.dataLayer` in the preview above.*/}
  <DataLayerViewer />
);

We can enable logging of events in development with the logging prop on the PageTrackingProvider.

While useTracker works fine for simple cases, we sometimes want to send shared data between all events without needing to rewrite said data with every event we send. This can be done by passing the default data as props to TrackingProvider.

const Component = () => {
  const tracker = useTracker();
  return (
    <View>
      <Button
        onClick={() => {
          tracker.interaction({
            eventAction: 'click',
            eventLabel: 'cta1',
          });
        }}
      >
        Button 1
      </Button>
      <Spacer />
      <Button
        onClick={() => {
          tracker.interaction({
            eventAction: 'click',
            eventLabel: 'cta2',
          });
        }}
      >
        Button 2
      </Button>
    </View>
  );
};

const Wrapper = ({ children }) => {
  return (
    <>
      <TrackingProvider pageName="landing page" eventCategory="category">
        {children}
      </TrackingProvider>
      {/* ↓↓↓ this is only to view the `window.dataLayer` in the preview above.*/}
      <DataLayerViewer />
    </>
  );
};
render(
  <Wrapper>
    <Component />
  </Wrapper>
);

Notice how the events pushed to window.dataLayer in the above example include pageName and eventCategory.

TrackingProvider supports inheritance, meaning that for any data added to any of the parant TrackingProviders, all will be sent and not just the last in the tree.

const Component = () => {
  const tracker = useTracker();
  return (
    <View>
      <Button
        onClick={() => {
          tracker.interaction({
            eventAction: 'click',
            eventLabel: 'cta1',
          });
        }}
      >
        Button 1
      </Button>
      <Spacer />
      <Button
        onClick={() => {
          tracker.interaction({
            eventAction: 'click',
            eventLabel: 'cta2',
          });
        }}
      >
        Button 2
      </Button>
    </View>
  );
};

const Wrapper = ({ children }) => {
  return (
    <>
      <TrackingProvider pageName="landing page">
        <TrackingProvider pageName="landing page" eventCategory="category">
          <TrackingProvider
            customEventData="custom data"
            eventCategory="override category"
          >
            {children}
          </TrackingProvider>
        </TrackingProvider>
      </TrackingProvider>
      {/* ↓↓↓ this is only to view the `window.dataLayer` in the preview above.*/}
      <DataLayerViewer />
    </>
  );
};
render(
  <Wrapper>
    <Component />
  </Wrapper>
);

In the above example, all event data from all TrackingProviders was sent with each event in that tree. Notice how eventCategory was overridden in the last TrackingProvider.

It's sometimes desired to send page load events without needing user input. This can be done by adding the trackPageLoad prop on any TrackingProvider in the tree.

() => {
  return (
    <TrackingProvider trackPageLoad pageType="pdp" pageName="xc40">
      <Block>...</Block>
    </TrackingProvider>
  );
};

All events are forced to be lowercase by default but it's also possible to disable this behaviour, based on specific requirements. This can be done with the forceLowerCase prop.

const Component = () => {
  const tracker = useTracker();
  return (
    <View>
      <Button
        onClick={() => {
          tracker.interaction({
            eventAction: 'Click',
            eventLabel: 'Cta1',
          });
        }}
      >
        Button 1
      </Button>
      <Spacer />
      <Button
        onClick={() => {
          tracker.interaction({
            eventAction: 'Click',
            eventLabel: 'CTA2',
          });
        }}
      >
        Button 2
      </Button>
    </View>
  );
};

const Wrapper = ({ children }) => {
  return (
    <>
      <TrackingProvider pageName="landing PAGE" forceLowerCase={false}>
        <TrackingProvider customEventData="CUStom data">
          {children}
        </TrackingProvider>
      </TrackingProvider>
      {/* ↓↓↓ this is only to view the `window.dataLayer` in the preview above.*/}
      <DataLayerViewer />
    </>
  );
};
render(
  <Wrapper>
    <Component />
  </Wrapper>
);

We can enable logging of events in development with the logging prop on the TrackingProvider.

TrackingProvider can store information in data attributes. This allows us to push event tracking information in places where we don't want to hydrate/render our React application. A useful case is for static sites that don't need any user input except for sending tracking events. A useful usecase is the DotCom SiteFooter which is rendered using React server-side but does not render/hydrate client-side. This can be done by disabling the enableReactTracking prop on the TrackingProvider. A more detailed explanation can be found in the Dom Tracking.

Allows any child element to attach tracking events to any event.

const Wrapper = ({ children }) => {
  return (
    <TrackingProvider pageName="landing page" enableReactTracking={false}>
      <TrackingProvider
        eventCategory="promotional hero"
        enableReactTracking={false}
      >
        {children}
      </TrackingProvider>
      {/* ↓↓↓ this is only to view the `window.dataLayer` in the preview above.*/}
      <DataLayerViewer />
    </TrackingProvider>
  );
};

const Component = () => {
  return (
    <View>
      <Track eventLabel="cta11">
        <Button>Button 1</Button>
      </Track>
      <Spacer />
      <Track eventLabel="cta22">
        <Button>Button 2</Button>
      </Track>
    </View>
  );
};
render(
  <Wrapper>
    <Component />
  </Wrapper>
);

This package also exports a HOC that helps with attaching tracking events based on domEvents

const Wrapper = ({ children }) => {
  return (
    <TrackingProvider pageName="landing page">
      <TrackingProvider eventCategory="promotional hero">
        {children}
      </TrackingProvider>
      {/* ↓↓↓ this is only to view the `window.dataLayer` in the preview above.*/}
      <DataLayerViewer />
    </TrackingProvider>
  );
};

const TrackedButton = withTracker(Button, {
  event: 'onClick',
  defaultAction: 'click',
});

const Component = () => {
  return (
    <View>
      <TrackedButton trackEventLabel="cta1">Button 1</TrackedButton>
      <Spacer />
      <TrackedButton trackEventLabel="cta2">Button 2</TrackedButton>
    </View>
  );
};
render(
  <Wrapper>
    <Component />
  </Wrapper>
);

As mentioned earlier in the enableReactTracking section. TrackingProvider can store information in data attributes. This allows us to push event tracking information in places where we don't want to hydrate/render our React application.

To enable this, first set enableReactTracking to false on the TrackingProvider. This will generate the following html, notice the data-track-onclick attributes.

const Wrapper = ({ children }) => {
  return (
    <div id="root">
      <FelaWrapper>
        <TrackingProvider pageName="landing page" enableReactTracking={false}>
          <TrackingProvider
            eventCategory="promotional hero"
            enableReactTracking={false}
          >
            {children}
          </TrackingProvider>
        </TrackingProvider>
      </FelaWrapper>
    </div>
  );
};

const TrackedButton = withTracker(Button, {
  event: 'onClick',
  defaultAction: 'click',
});

const Component = () => {
  return (
    <View>
      <TrackedButton trackEventLabel="cta1">Button 1</TrackedButton>
      <Spacer />
      <TrackedButton trackEventLabel="cta2">Button 2</TrackedButton>
    </View>
  );
};
render(() => {
  const decodeHtml = function decodeHtml(html) {
    if (typeof window === 'undefined') return '';
    var txt = document.createElement('textarea');
    txt.innerHTML = html;
    return txt.value;
  };
  return (
    <>
      <code>
        {decodeHtml(
          ReactDomRenderToStaticMarkup(
            <Wrapper>
              <Component />
            </Wrapper>
          )
        )}
      </code>
    </>
  );
});

We then attach the tracking listeners with createDomTrackingListener.

import { createDomTrackingListener } from '@volvo-cars/tracking/domTracking';

document
  // first get the parent of the nested components which have tracking
  .getElementById('root')
  // attach the listener which will traverse up the tree to get all the
  // context data from parent `data` attributes
  ?.addEventListener('click', createDomTrackingListener('onClick'));

When rendering the static content, and wanting to use the TrackingProvider passing custom react components will just pass in props with data. It's up to you to pass them down the line. It will only add them in two cases:

1. Direct child is a simple dom element.
2. Children is a fragment or multiple elements, in this case, the'll be wrappedj with div

Examples:

// this will add data attributes
// to the `main`
<TrackingProvider
  pageType="catch all"
  enableReactTracking={false}
>
  <main>
    {/* .... */}
  </main>
</TrackingProvider>

// this will wrap children
// with `div` containing data
<TrackingProvider
  pageType="catch all"
  enableReactTracking={false}
>
  {header}
  <main>
    {/* .... */}
  </main>
</TrackingProvider>

// this will pass down `data-track-context`
// to the `App` it's up to developer to handle this
<TrackingProvider
  pageType="catch all"
  enableReactTracking={false}
>
  <App />
</TrackingProvider>

This package exports non-strict types for TrackingData and CustomDimension

export interface TrackingData extends Record<string, any> {}
export type CustomDimension = string;

Those types can be made stricter depending on your use case. To override those types you can create a declartions file in your types directory somewhere in your application and overide them as needed.

import '@volvo-cars/tracking';
declare module '@volvo-cars/tracking' {
  export interface TrackingData {
    eventAction?: string;
    eventLabel?: string;
    eventCategory?: string;
  }
}

You can measure Web Vitals metrics on real users, in a way that accurately matches how they're measured by Chrome and reported to other Google tools. This can be done in two ways depending on the use case:

Starting from Next.js v10.0.0, you can export a reportWebVitals function from _app which helps provide Web Vital metrics:

import { reportWebVitals as webVitals } from '@volvo-cars/tracking/webVitals';

export function reportWebVitals(metrics: NextWebVitalsMetric) {
  return webVitals({
    metrics,
  });
}

This will report something like the following, depending on the metric dispatched by Next.js

      {
        event: 'noninteraction',
        eventAction: 'fcp',
        eventCategory: 'web vitals',
        eventLabel: 'uniqueid',
        eventValue: 2,
      },

Any additional event data can be sent using additionalEventData property:

import { reportWebVitals as webVitals } from '@volvo-cars/tracking/webVitals';

export function reportWebVitals(metrics: NextWebVitalsMetric) {
  return webVitals({
    metrics,
    additionalEventData: {
      pageName: 'my page name',
      pageType: 'my page type',
    },
  });
}

If not using Next.js, Web Vitals can be reported and measured using measureWebVitals:

import { measureWebVitals } from '@volvo-cars/tracking/webVitals';

measureWebVitals();

constructor(
    eventData?: TrackingData | null,
    {
      forceLowerCase = true,
      logging = false,
      disabled = false,
    }: TrackerOptions = {}
  )

Pushes an event: interaction event to the data layer.

Pushes an event: noninteraction event to the data layer. If no object with the pageType or pageName is in the data layer yet, nonInteraction events are queued for up to 90 seconds to avoid affecting the order of events used to determine bounce rates.

Pushes an event: virtualPageView event to the data layer.

Pushes a custom dimension to the data layer.

useTracker(
  hookData?: TrackingData | null,
  trackerOptions?: TrackerOptions,
  options?: { ignoreIfEmptyContext?: boolean }
): Tracker

returns a Tracker instance.

withTracker(
  Component: React.ComponentType,
  {
    event: 'onClick';
    defaultAction: string;
    ga3?: GA3Event;
  });

returns a new React.ComponentType with tracking data attached.

createDomTrackingListener(eventName:string, options?: TrackerOptions, event?: TrackEvent )

return a new event listener.

Pushes an event: TrackEvent event to the data layer.

TrackEvent =
  | 'chat_interaction'
  | 'custom_event'
  | 'sitenav_interaction'
  | 'view_item'
  | 'page_view'
  | 'web_vitals'
  | 'add_to_cart'
  | 'cart_view'
  | 'begin_checkout'
  | 'add_payment_info'
  | 'purchase'
  | 'config_start'
  | 'config_finish'
  | 'login'
  | 'account_created'
  | 'form_load'
  | 'form_submit'
  | 'search';

Pushes an event: custom_event event to the data layer.

Pushes an event: site_navInteraction event to the data layer.

Pushes an event: chat_interaction event to the data layer.

Pushes an event: page_view event to the data layer.

Pushes an event: view_item event to the data layer.

Pushes an event: add_to_cart event to the data layer.

Pushes an event: cart_view event to the data layer.

Pushes an event: begin_checkout event to the data layer.

Pushes an event: add_payment_info event to the data layer.

Pushes an event: purchase event to the data layer.

Pushes an event: config_start event to the data layer.

Pushes an event: config_finish event to the data layer.

Pushes an event: form_load event to the data layer.

Pushes an event: form_submit event to the data layer.

Pushes an event: web_vitals event to the data layer.

Start to set mode to both and set logging to true to see that two events are sent in the console.

<TrackingProvider logging mode="both">
  children
</TrackingProvider>

To have every event sent for example add_to_cart

<TrackingProvider event="add_to_cart" logging mode="both">
  children
</TrackingProvider>

You can override event in children to set a new event prop for example

<TrackingProvider event="add_to_cart" logging mode="both">
  children
  <TrackingProvider event="purchase" logging mode="both">
    children
  </TrackingProvider>
</TrackingProvider>

You can also specify on every child for example

<TrackingProvider event="add_to_cart" logging mode="both">
  children
  <Click trackEvent="purchase" trackEventLabel="label">
    button
  </Click>
  <Track event="add_payment_info" eventLabel="label">
    <>
      <button />
      <button />
    </>
  </Track>
</TrackingProvider>

You can now also use our new typed functions instead

const tracker = new Tracker(null, { mode: 'both' });
tracker.addToCart({
  countryCode: 'countryCode',
  pageName: 'pageName',
  pageType: 'pageType',
  ecommerce: {
    items: [
      {
        itemName: 'itemName',
      },
    ],
  },
});