Meh-activity-logger NPM

MEH Activity Logger

Log custom events and pageviews with opinionated defaults to Google Analytics through Express middleware, Node or the browser.

Install

yarn add meh-activity-logger

Usage

Event logging example in all three environments with the same outcome:

// 1. Node with Express
import { expressMiddleware as mehActivityLogger } from 'meh-activity-logger';
import express from 'express';

express()
  .use(mehActivityLogger('UA-XXXXXX-X')) // Equivalent to: mehActivityLogger({ tid: 'UA-XXXXXX-X' })
  .get('/example', (req, res) => {
    req.event('Example event').catch(console.error); // Equivalent to: event({ action: 'Example event' })
    res.sendStatus(200);
  })
  .listen(3000);

// 2. Node without Express
import mehActivityLogger from 'meh-activity-logger';

const { event } = mehActivityLogger('UA-XXXXXX-X');

event({
  action: 'Example event',
  clientId: '0.0.0.0',
  uip: '0.0.0.0',
  ua:
    'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_3) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/80.0.3987.132 Safari/537.36',
  dr: 'https://www.example.com/',
  dh: 'example.com',
  dp: '/example',
}).catch(console.error);

<!-- 3. Browser with JavaScript -->
<script src="https://unpkg.com/meh-activity-logger"></script>
<script>
  var logger = window.mehActivityLogger.default({
    tid: 'UA-XXXXXX-X',
    appName: 'example-app',
    appVersion: '1.0.0',
  });

  logger
    .event({
      action: 'Example event',
      clientId: '0.0.0.0',
      uip: '0.0.0.0',
    })
    .catch(console.error);
</script>

Will all result in:

// POST https://www.google-analytics.com/collect (form data)

v=1
&tid=UA-XXXXXX-X
&ua=Mozilla%2F5.0+%28Macintosh%3B+Intel+Mac+OS+X+10_15_4%29+AppleWebKit%2F537.36+%28KHTML%2C+like+Gecko%29+Chrome%2F81.0.4044.138+Safari%2F537.36
&dr=https%3A%2F%2Fwww.example.com%2F
&dh=example.com
&dp=%2Fexample
&uip=0.0.0.0
&t=event
&cid=2065339419
&ec=Primary+KPI
&ea=Example+event
&an=example-app
&aid=example-app
&cd1=example-app
&av=1.0.0
&cd2=1.0.0

API

`activityLogger([measurementId|properties])`

Returns: Function (event)

Sets global properties for all GA events.

`measurementId`

Type: String

Measurement ID (format: "UA-XXXXXX-X"). Equivalent to { tid: 'UA-XXXXXX-X' }.

`properties` (GA Measurement Protocol)

Type: Object

Defaults:

Key	Default value
`v` (Protocol Version)	`1`
`tid` (Measurement ID)	`process.env.MEH_ACTIVITY_LOGGER_MEASUREMENT_ID` or `'UA-26548270-15'` (defaults to MEH property)
`uip` (IP Override)	`req.ip` (anonymized in GA)
`ua` (User Agent Override)	`req.get('User-Agent')` or `navigator.userAgent` or `'Mozilla/4.0 (compatible; MSIE 6.1; Windows XP; .NET CLR 1.1.4322; .NET CLR 2.0.50727)'` (defaults to IE6 user-agent for easy filtering)
`dr` (Document Referrer)	`req.get('Referer')` or `document.referrer`
`dh` (Document Host Name)	`req.hostname` or `location.hostname`
`dp` (Document Path)	`req.originalUrl` or `location.pathname`
`an` (Application Name)	`name` value from your project's `package.json`
`aid` (Application ID)	`name` value from your project's `package.json`
`av` (Application Version)	`version` value from your project's `package.json`
`cd1` (Custom Dimension)	`name` value from your project's `package.json`
`cd2` (Custom Dimension)	`version` value from your project's `package.json`

For all other GA properties, see Google Analytics Measurement Protocol.

`event(eventAction|properties)`

Returns: Promise[Response](https://www.npmjs.com/package/cross-fetch)

Overrides global properties, and fires a custom event to Google Analytics.

`eventAction`

Type: String

Event Action. Equivalent to { action: 'Example' } or { ea: 'Example' }.

`properties` (GA Measurement Protocol)

Type: Object

Defaults:

Key	Default value
`t` (Hit Type)	`"event"`
`ec` (Event Category)	`"Primary KPI"`

For all other GA properties, see Google Analytics Measurement Protocol.

Custom properties:

Key	Type	Description	Maps to
`clientId`	String	A unique representation of the user/session. Its value will be hashed/anonymized.	`cid` (Client ID)
`priority`	Integer (`1`\|`2`\|`3`)	Resolves to `"Primary KPI"`, `"Secondary KPI"` or `"Tertiary KPI"` respectively.	`ec` (Event Category)
`action`	String	Describes the event taking place.	`ea` (Event Action)
`label`	String	Labels the event.	`el` (Event Label)
`value`	Integer	Adds a metric to the label.	`ev` (Event Value)
`appName`	String	Identifies the app name.	`an` (Application Name), `aid` (Application ID), `cd1` (Custom Dimension)
`appVersion`	String	Identifies the app version.	`av` (Application Version), `cd2` (Custom Dimension)