event-translator v1.0.1

Event translator

An event driven tracking middleware which will translate the captured events to the connected providers (GTM, QA..)

Available providers:

• Google Tag Manager (GTM)
• QA (used for testing in development mode)

Available methods:

• trackEvent
• trackPageImpression
• trackComponentImpression
• trackComponentClick

Installation

Install event-translator with npm

  npm install event-translator

with yarn

  yarn add event-translator

Providers setup

QA

qaProvider.init(config)

import { qaProvider } from "event-translator";

qaProvider.init()

Config options

{
    develop: true, //default

    // `customEventNames` will allow you to override the default event namings 
    customEventNames: {
        componentImpression: "contentblock-impression",
        componentClick: "contentblock-click",
    }
}

GTM

gtmProvider.init(config)

import { gtmProvider } from "event-translator";

gtmProvider.init()

Config options

{
    develop: false, //default

    // `customEventNames` will allow you to override the default event namings 
    customEventNames: {
        componentImpression: "contentblock-impression",
        componentClick: "contentblock-click"
    }
}

Default event mappings

{
  customEvent: 'custom-event',
  pageImpression: 'page-impression',
  componentImpression: 'component-impression',
  componentClick: 'component-click',
}

Usage/examples

Note: all events will automatically include A pageInfo object containing the following fields:

• url
• path
• useragent
• language
• domain
• referrer
• title
• params
• timestamp

example

{
    "url": "http://localhost:8000/nl/uw-pand-schatten?numberOfRooms=0&livableSurfaceArea=&totalSurfaceArea=",
    "path": "/nl/uw-pand-schatten",
    "useragent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/93.0.4577.63 Safari/537.36",
    "language": "nl",
    "domain": "localhost",
    "referrer": "/nl",
    "title": "Laat gratis de waarde van jouw woning schatten. Met de online schattingstool verkrijg je eenvoudig een eerste waardeschatting van jouw huis.",
    "params": {
        "numberOfRooms": "0"
    },
    "timestamp": "2021-09-29 16:42:55"
}

Track custom events

import { trackEvent } from "event-translator";

trackEvent({
  event: "tool-fieldvalidation", //default: custom-event

  // include all the event related info within the `info` object
  info: {
      stepnumber: 1,
      stepname: "property details 1",
      fieldName: "propertyType",
      message: "Veld mag niet leeg zijn",
      type: "user",
  },

  // use the `pageInfo` object to extend or override the default pageInfo attributes
  pageInfo: {
      agencyPage: false
  }
});

Example output

{
  "event": "tool-fieldvalidation",
  "info": {
      "stepnumber": 1,
      "stepname": "property details 1",
      "fieldName": "propertyType",
      "message": "Veld mag niet leeg zijn",
      "type": "user"
  },
  "pageInfo": {
      "url": "http://localhost:8000/nl/uw-pand-schatten",
      "path": "/nl/uw-pand-schatten",
      "useragent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/93.0.4577.63 Safari/537.36",
      "language": "en-GB",
      "domain": "localhost",
      "referrer": "http://localhost:8000/nl",
      "title": "Laat gratis de waarde van jouw woning schatten. Met de online schattingstool verkrijg je eenvoudig een eerste waardeschatting van jouw huis.",
      "params": "",
      "timestamp": "2021-09-30 10:54:07"
  }
}

Track page impressions

import { trackPageImpression } from "event-translator";

trackPageImpression({
      agencyPage: false
  });

These fields will be appendend to the default page info object.

Example output

{
  "event": "page-impression",
  "pageInfo": {
      "url": "http://localhost:8000/nl",
      "path": "/nl",
      "useragent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/93.0.4577.63 Safari/537.36",
      "language": "nl",
      "domain": "localhost",
      "referrer": "",
      "title": "",
      "params": "",
      "timestamp": "2021-09-30 09:47:46",
      "agencyPage": false
  }
}

Track component impressions

Let's say we have the following structure:

<div data-placement="home">
   <div data-type="section1">
      <a data-type="internal-link" href="/nl/uw-pand-schatten">Gratis schatting</a>
   </div>
</div>

import { trackComponentImpression } from "event-translator";

//let's assume we observe the viewport possition from the <a> element which triggers the `trackCommponent` function.

const trackComponent = (event) => {
   trackComponentImpression({
      element: event.target,
      info: {
            targeturl: "/nl/uw-pand-schatten"
      },
      event: "button-impression",
   });
}

Example output

{
  "event": "button-impression",
  "info": {
      "type": "internal-link",
      "targeturl": "/nl/uw-pand-schatten",
      "placement": "home:section1",
      "text": "Gratis schatting"
  },
  "pageInfo": {
      "url": "http://localhost:8000/nl",
      "path": "/nl",
      "useragent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/93.0.4577.63 Safari/537.36",
      "language": "en-GB",
      "domain": "localhost",
      "referrer": "http://localhost:8000/nl",
      "title": "CENTURY 21 Benelux - Nummer 1 netwerk van vastgoed makelaars in België en Luxemburg",
      "params": "",
      "timestamp": "2021-09-30 09:47:47"
  }
}

Notice that the placement, text & type values will be automatically appended to the info object. The placement value will be determined by the all the collected data-placement and and data-type attributes from the element's parent nodes.

Track component clicks

Let's say we have the following structure:

<div data-placement="home">
   <div data-type="section1">
      <a onClick="trackComponentClick" data-type="internal-link" href="/nl/uw-pand-schatten">Gratis schatting</a>
   </div>
</div>

import { trackComponentClick } from "event-translator";

const trackComponentClick = (event) => {
   trackComponentClick({
      element: event.target,
      info: {
            targeturl: "/nl/uw-pand-schatten"
      },
      event: "button-click",
   });
}

Example output

{
  "event": "button-click",
  "info": {
      "type": "internal-link",
      "targeturl": "/nl/uw-pand-schatten",
      "placement": "home:section1",
      "text": "Gratis schatting"
  },
  "pageInfo": {
      "url": "http://localhost:8000/nl",
      "path": "/nl",
      "useragent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/93.0.4577.63 Safari/537.36",
      "language": "en-GB",
      "domain": "localhost",
      "referrer": "http://localhost:8000/nl",
      "title": "CENTURY 21 Benelux - Nummer 1 netwerk van vastgoed makelaars in België en Luxemburg",
      "params": "",
      "timestamp": "2021-09-30 09:47:47"
  }
}

Notice that the placement, text & type values will be automatically appended to the info object. The placement value will be determined by the all the collected data-placement and and data-type attributes from the element's parent nodes.