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" |