A minimal, offline-friendly Google Analytics Measurement Protocol client for tracking usage statistics in shell and javascript applications.
This is a low-level API client, 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 app-usage-stats. For the command line client see usage-stats-cli.
The most trivial example.
const UsageStats = require('usage-stats')
const usageStats = new UsageStats('UA-98765432-1', { an: 'example' })
usageStats.screenView('screen name')
usageStats.event('category', 'action')
usageStats.send()
More realistic usage in a server application:
const UsageStats = require('usage-stats')
const usageStats = new UsageStats('UA-98765432-1', {
an: 'encode-video',
av: '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()
See here for the full list of Google Analytics Measurement Protocol parameters.
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)
Kind: Exported class
- 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([options]) ⇒
Map
- .send([options]) ⇒
Promise
- .debug() ⇒
Promise
- .abort() ↩︎
Param | Type | Description |
---|---|---|
trackingId | string |
Google Analytics tracking ID (required). |
[options] | object |
|
[options.an] | string |
App name |
[options.av] | 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.ua] | string |
User Agent string to use. |
[options.dir] | string |
Path of the directory used for persisting clientID and queue. Defaults to ~/.usage-stats . |
[options.url] | string |
Defaults to 'https://www.google-analytics.com/batch' . |
[options.debugUrl] | string |
Defaults to 'https://www.google-analytics.com/debug/collect' . |
Example
const usageStats = new UsageStats('UA-98765432-1', {
an: 'sick app',
av: '1.0.0'
})
Cache directory. Defaults to ~/.usage-stats
.
Kind: instance property of UsageStats
A list of parameters to be to sent 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')
Starts the session.
Kind: instance method of UsageStats
Chainable
Param | Type | Description |
---|---|---|
[sessionParams] | Array.<Map> |
An optional map of paramaters to send with each hit in the sesison. |
Ends the session.
Kind: instance method of UsageStats
Chainable
Param | Type | Description |
---|---|---|
[sessionParams] | Array.<Map> |
An optional map of paramaters to send with the final hit of this sesison. |
Disable the module. While disabled, all operations are no-ops.
Kind: instance method of UsageStats
Chainable
Re-enable the module.
Kind: instance method of UsageStats
Chainable
Track an event. All event hits are queued until .send()
is called.
Kind: instance method of UsageStats
Param | Type | Description |
---|---|---|
category | string |
Event category (required). |
action | string |
Event action (required). |
[options] | option |
|
[options.el] | string |
Event label |
[options.ev] | string |
Event value |
[options.hitParams] | Array.<map> |
One or more additional params to send with the hit. |
Track a screenview. All screenview hits are queued until .send()
is called. Returns the hit instance.
Kind: instance method of UsageStats
Param | Type | Description |
---|---|---|
name | string |
Screen name |
[options] | object |
|
[options.hitParams] | Array.<map> |
One or more additional params to set on the hit. |
Track a exception. All exception hits are queued until .send()
is called.
Kind: instance method of UsageStats
Param | Type | Description |
---|---|---|
[options] | object |
optional params |
[options.exd] | string |
Error message |
[options.exf] | boolean |
Set true if the exception was fatal |
[options.hitParams] | Array.<map> |
One or more additional params to set on the hit. |
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. Each response has data
and the original node res
.
Reject: Error
- Rejects with the first error encountered. The error is a standard node http error with a name
of request-fail
and a hits
property showing what failed to send.
Param | Type |
---|---|
[options] | object |
[options.timeout] | number |
Send any hits (including queued) to the GA validation server, fulfilling with the result.
Kind: instance method of UsageStats
Fulfil: Response[]
Reject: Error
- Error instance includes hits
.
Aborts the in-progress .send() operation, queuing any unsent hits.
Kind: instance method of UsageStats
Chainable
© 2016-23 Lloyd Brookes <75pound@gmail.com>. Documented by jsdoc-to-markdown.