Getting started with @d-cat/utility-ga-event-listener

This utility package is designed for @d-cat/tag-manager. It uses DDM-NPM to subscribe to both ga.event as other events with a ga_data prop. Make sure Google Analytics is available at runtime.

Install

npm i @d-cat/utility-ga-event-listener

Usage

Two listeners are set through this package:

• 'ga.event'
• '**'

By default the listeners abort sending hits to Google Analytics when they do not validate against the following (RegExo) categories:

• ^click.(button|link|click|outbound|download)$
• ^bat$

Enhancing this list goes by passing an RegExp[] with accepted categories.

Init

The initialization happens 1 time per page.

import gaEvent from '@d-cat/utility-ga-event-listener';

const TRACKER_NAMES = ['directsales'];

// empty array when no additional whitelisted categories are given
// this means the default whitelist apply
gaEvent({
  names: TRACKER_NAMES,
});

// No array given,
// this means the default whitelist apply
gaEvent({ names: TRACKER_NAMES });

// Given string merges with the default array
// that means the default whitelisted categories apply including connected-cloud.
gaEvent({
  categories: [/connect\-cloud/],
  names: TRACKER_NAMES,
});

Sending data to Google Analytics

There are 2 options, after the initialization is done to send data to Google Analytics:

• triggering ga.event (with a whitelisted category)
• triggering a random event, while passing additional attributes

ga.event

import { emit } from '@d-cat/digital-data-manager'

// Triggering ga.event with a NOT whitelisted category
// this will abort sending the hit to GA, however the event
// will be visible in the eventbus.
emit({
  event: 'ga.event',
  data: {
    data: {
      category: 'category',
      action: 'random action',
      label: 'really long label',
    },
  },
});

Random event

| Property | Type | Descrioption | | --------- | --------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- | | ga_data | {category: string, action: string, label?:string} | Object where category should validate against given whitelist, action and label have to be of type string. |

import { emit } from '@d-cat/digital-data-manager'

// Each event can trigger to send a hit to Google Analytics
// by forwarding send_to_ga: true including ga_data object
// default rules apply according to whitelisted categories
emit({
  event: 'random.event',
  data: {
    data: {
      ga_data: {
        category: 'click.link',
        action: 'random action',
        label: 'random label',
      },
    },
  },
});

Send to a single trackerName

You can override the trackernames by providing a new array with trackers. This will then only send data to the given tracker names, and not to the initial tracker names.

import { emit } from '@d-cat/digital-data-manager'

// Each event can trigger to send a hit to Google Analytics
// by forwarding send_to_ga: true including ga_data object
// default rules apply according to whitelisted categories
emit({
  event: 'random.event',
  data: {
    data: {
      ga_data: {
        category: 'click.link',
        action: 'random action',
        label: 'random label',
        trackers: ['t0', 'ziggo'],
      },
    },
  },
});