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

• 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)

Sent on demand

• App name
• App version

API Reference

Example

const UsageStats = require('usage-stats')

• usage-stats
  • UsageStats ⏏
    • new UsageStats(trackingId, [options])
    • .dir : string
    • .defaults : Map
    • .start([sessionParams]) ↩︎
    • .end([sessionParams]) ↩︎
    • .disable() ↩︎
    • .enable() ↩︎
    • .event(category, action, [options]) ⇒ Map
    • .screenView(name, [options]) ⇒ Map
    • .exception(description, isFatal) ⇒ Map
    • .send([options]) ⇒ Promise
    • .abort() ↩︎
    • .load() ↩︎
    • .save() ↩︎
    • .queueLength() ⇒ number

UsageStats ⏏

Kind: Exported class

new UsageStats(trackingId, [options])

Example

const usageStats = new UsageStats('UA-98765432-1', {
  name: 'sick app',
  version: '1.0.0'
})

usageStats.dir : string

Cache directory where the queue and client ID is kept. Defaults to ~/.usage-stats.

Kind: instance property of UsageStats

usageStats.defaults : Map

Set parameters on this map to send them with every hit.

Kind: instance property of UsageStats
Example

usageStats.defaults
  .set('cd1', process.version)
  .set('cd2', os.type())
  .set('cd3', os.release())
  .set('cd4', 'api')

usageStats.start([sessionParams]) ↩︎

Starts the session.

Kind: instance method of UsageStats
Chainable

usageStats.end([sessionParams]) ↩︎

Ends the session.

Kind: instance method of UsageStats
Chainable

usageStats.disable() ↩︎

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

Kind: instance method of UsageStats
Chainable

usageStats.enable() ↩︎

Re-enable the module.

Kind: instance method of UsageStats
Chainable

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

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

Kind: instance method of UsageStats

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

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

Kind: instance method of UsageStats

usageStats.exception(description, isFatal) ⇒ Map

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

Kind: instance method of UsageStats

usageStats.send([options]) ⇒ Promise

Send queued stats using as few requests as possible (typically a single request - a max of 20 events/screenviews may be sent per request). If offline, the stats will be stored and re-tried on next invocation.

Kind: instance method of UsageStats
Fulfil: response[] - array of responses

usageStats.abort() ↩︎

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

Kind: instance method of UsageStats
Chainable

usageStats.load() ↩︎

Dumps unsent hits to the queue. They will dequeued and sent on next invocation of .send().

Kind: instance method of UsageStats
Chainable

usageStats.save() ↩︎

Dumps unsent hits to the queue. They will dequeued and sent on next invocation of .send().

Kind: instance method of UsageStats
Chainable

usageStats.queueLength() ⇒ number

Return the total hits stored on the queue.

Kind: instance method of UsageStats

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