# event-translator

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

Latest version **1.0.1** (published 2021-09-30) · MIT license · 0 weekly downloads

## Install

```sh
npm install event-translator
pnpm add event-translator
yarn add event-translator
bun add event-translator
```

## Health

**Score 15/100 (F)** — status: abandoned.

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 1.0.1 |
| Published | 2021-09-30 |
| First published | 2021-09-30 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 2 |
| Unpacked size | 442.4 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Author | Jason Marysael |
| Maintainers | marysaja |

## Links

- npm: https://www.npmjs.com/package/event-translator
- npm.io page: https://npm.io/package/event-translator

## Dependencies (2)

- [eventemitter3](https://npm.io/package/eventemitter3.md) ^4.0.7
- [lodash.omitby](https://npm.io/package/lodash.omitby.md) ^4.6.0

## Recent versions

- 1.0.1 (latest) — 2021-09-30
- 1.0.0 — 2021-09-30

## README

# 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)](#markdown-header-gtm)
   - [QA](#markdown-header-qa) (used for testing in development mode)

Available methods:

   -  [trackEvent](#markdown-header-track-custom-events)
   -  [trackPageImpression](#markdown-header-track-page-impressions)
   -  [trackComponentImpression](#markdown-header-track-component-impressions)
   -  [trackComponentClick](#markdown-header-track-component-clicks)

## Installation

Install event-translator with npm

```bash
  npm install event-translator
```

with yarn

```bash
  yarn add event-translator
```
## Providers setup

### QA

qaProvider.init([config])

```javascript
import { qaProvider } from "event-translator";

qaProvider.init()
```

#### Config options
```javascript
{
    develop: true, //default

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

### GTM

gtmProvider.init([config])

```javascript
import { gtmProvider } from "event-translator";

gtmProvider.init()
```

#### Config options
```javascript
{
    develop: false, //default

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

```javascript
{
  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 

```javascript
{
    "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

```javascript
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

```javascript
{
  "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

```javascript
import { trackPageImpression } from "event-translator";

trackPageImpression({
      agencyPage: false
  });
```

These fields will be appendend to the [default page info object](#markdown-header-example).

Example output

```javascript
{
  "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:

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

```javascript
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

```javascript
{
  "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:

```html
<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>
```

```javascript
import { trackComponentClick } from "event-translator";

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

```

Example output

```javascript
{
  "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.

---
_Source: https://npm.io/package/event-translator · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._