usage-stats

A minimal, offline-friendly Google Analytics Measurement Protocol client for tracking usage statistics in node.js applications.

This is only a low-level client API, it doesn't hold any opinion of how usage tracking should be done. If you're looking for a convention which leverages the power and flexibility of Custom Metrics and Dimensions, take a look at track-usage.

Synopsis

Simple

The most trivial example.

const UsageStats = require('usage-stats')
const usageStats = new UsageStats('UA-98765432-1')

// track a hit on the 'main' screen with 'simple' mode set.
usageStats
  .screenView('main')
  .event('option', 'mode', 'simple')
  .send()

Typical

More realistic usage in an example video encoding app.

const UsageStats = require('usage-stats')
const usageStats = new UsageStats('UA-98765432-1', {
  name: 'enocode-video',
  version: '1.0.0'
})

// start a new session
usageStats.start()

// user set two options..
usageStats.event('option', 'verbose-level', 'infinite')
usageStats.event('option', 'preset', 'iPod')

try {
  // Begin. Track as a screenView.
  usageStats.screenView('encoding')
  beginEncoding(options)
} catch (err) {
  // Exception tracking
  usageStats.exception(err.message, true)
}

// finished - mark the session as complete
// and send stats (or store if offline).
usageStats.end().send()

Parameters

See here for the full list of Google Analytics Measurement Protocol parameters.

Sent by default

All parameters are send on demand, beside this list.

• Operating System version (sent in the UserAgent)
• Client ID (a random UUID, generated once per OS user and stored)
• Language (process.env.LANG, if set)
• Screen resolution (terminal rows by columns, by default)

API Reference

Kind: inner class of UsageStats
Extends: usage-stats

• ~UsageStatsAbortable ⇐ usage-stats
  • .send([options])
  • .abort() ↩︎
  • .start([sessionParams]) ↩︎
  • .end([sessionParams]) ↩︎
  • .disable() ↩︎
  • .enable() ↩︎
  • .event(category, action, [options]) ⇒ Map
  • .screenView(name, [options]) ⇒ Map
  • .exception(description, isFatal) ⇒ Map
  • .debug() ⇒ Promise

usage.send([options])

Kind: instance method of UsageStatsAbortable
Overrides: send

usage.abort() ↩︎

Aborts the in-progress .send() operation, queuing any unsent hits.

Kind: instance method of UsageStatsAbortable
Chainable

usage.start([sessionParams]) ↩︎

Starts the session.

Kind: instance method of UsageStatsAbortable
Chainable

usage.end([sessionParams]) ↩︎

Ends the session.

Kind: instance method of UsageStatsAbortable
Chainable

usage.disable() ↩︎

Disable the module. While disabled, all operations are no-ops.

Kind: instance method of UsageStatsAbortable
Chainable

usage.enable() ↩︎

Re-enable the module.

Kind: instance method of UsageStatsAbortable
Chainable

usage.event(category, action, [options]) ⇒ Map

Track an event. All event hits are queued until .send() is called.

Kind: instance method of UsageStatsAbortable

usage.screenView(name, [options]) ⇒ Map

Track a screenview. All screenview hits are queued until .send() is called. Returns the hit instance.

Kind: instance method of UsageStatsAbortable

usage.exception(description, isFatal) ⇒ Map

Track a exception. All exception hits are queued until .send() is called.

Kind: instance method of UsageStatsAbortable

usage.debug() ⇒ Promise

Send any hits (including queued) to the GA validation server, fulfilling with the result.

Kind: instance method of UsageStatsAbortable
Fulfil: Response[]
Reject: Error - Error instance includes hits.

© 2016 Lloyd Brookes <75pound@gmail.com>. Documented by jsdoc-to-markdown.