meh-activity-logger

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>

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)

pageview([properties])

• Returns: Promise<Response>

Optionally overrides global properties, and fires a pageview event to Google Analytics.

properties (GA Measurement Protocol)

• Type: Object

Defaults:

Key	Default value
t (Hit Type)	"pageview"