usage-stats

usage-stats

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

Synopsis

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

// start a new session
usageStats.start()

// user set an option..
usageStats.event('option', 'verbose-level', 'infinite')

// app is running in 'encoding' mode..
usageStats.screenView('encoding')

try {
  beginEncoding(options)
} catch (err) {
  // exception tracking
  usageStats.exception(err.message, true)
}

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

List of stats sent

Beside tracking events, exceptions and screenviews, the follow stats are collected each session.

• App name
• App version
• Node.js version (sent as App ID)
• User ID (a random UUID, generated once per OS user and stored)
• Language (process.env.LANG, if set)
• OS version (sent as App Installer ID)
• Terminal resolution (rows by columns)

API Reference

Example

const UsageStats = require('usage-stats')

• usage-stats
  • UsageStats ⏏
    • new UsageStats(trackingId, [options])
    • .dir : string
    • ._queuePath : string
    • .start() ↩︎
    • .end() ↩︎
    • .disable() ↩︎
    • .enable() ↩︎
    • .event(category, action, [label], [value]) ↩︎
    • .screenView(name) ↩︎
    • .exception(description, isFatal) ↩︎
    • .send([options]) ⇒ Promise
    • ._getClientId() ⇒ string
    • ._request(reqOptions, [data]) ⇒ Promise
    • ._dequeue([count]) ⇒ Array.<string>
    • ._enqueue(hits)

UsageStats ⏏

Kind: Exported class

new UsageStats(trackingId, [options])

Param	Type	Description
trackingId	string	Google Analytics tracking ID (required).
[options]	object
[options.name]	string	App name
[options.version]	string	App version
[options.lang]	string	Language. Defaults to process.env.LANG.
[options.sr]	string	Screen resolution. Defaults to ${process.stdout.rows}x${process.stdout.columns}.
[options.dir]	string	Path of the directory used for persisting clientID and queue.

Example

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

usageStats.dir : string

Absolute path of the temporary directory used for persisting clientID and queue.

Kind: instance property of UsageStats

usageStats._queuePath : string

The absolute path of the queue.

Kind: instance property of UsageStats

usageStats.start() ↩︎

Starts the session.

Kind: instance method of UsageStats
Chainable

usageStats.end() ↩︎

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, [label], [value]) ↩︎

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

Kind: instance method of UsageStats
Chainable

Param	Type	Description
category	string	Event category (required).
action	string	Event action (required).
[label]	string	Event label
[value]	string	Event value

usageStats.screenView(name) ↩︎

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

Kind: instance method of UsageStats
Chainable

Param	Type	Description
name	string	Screen name

usageStats.exception(description, isFatal) ↩︎

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

Kind: instance method of UsageStats
Chainable

Param	Type	Description
description	string	Error message
isFatal	boolean	Set true if the exception was fatal

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: debug mode: { hits: {hits}, result: {validation result} }
Fulfil: live mode: { res: {res}, data: {Buffer} }

Param	Type	Description
[options]	object
[options.debug]	boolean	Validates hits, fulfilling with the result.

usageStats._getClientId() ⇒ string

Must return a v4 UUID.

Kind: instance method of UsageStats

usageStats._request(reqOptions, [data]) ⇒ Promise

The request method used internally, can be overridden for testing or other purpose. Takes a node-style request options object in. Must return a promise.

Kind: instance method of UsageStats
Fulfil: { res: <node response object>, data: <Buffer payload> }

Param	Type
reqOptions	object
[data]	*

usageStats._dequeue([count]) ⇒ Array.<string>

Returns hits queued.

Kind: instance method of UsageStats

Param	Type	Description
[count]	number	Number of hits to dequeue. Defaults to "all hits".

usageStats._enqueue(hits)

Kind: instance method of UsageStats

Param	Type
hits	Array.<string>

---

© 2016 Lloyd Brookes <[e-mail]>. Documented by jsdoc-to-markdown.