npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

usage-stats

v0.9.5

Published

A minimal, offline-friendly Google Analytics Measurement Protocol client for tracking statistics in shell and javascript applications

Downloads

19,735

Readme

view on npm npm module downloads Gihub repo dependents Gihub package dependents Node.js CI js-standard-style

usage-stats

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.

Synopsis

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

Protocol 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: Exported class

new UsageStats(trackingId, [options])

| 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'
})

usageStats.dir : string

Cache directory. Defaults to ~/.usage-stats.

Kind: instance property of UsageStats

usageStats.defaults : Map

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

usageStats.start([sessionParams]) ↩︎

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

usageStats.end([sessionParams]) ↩︎

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

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

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

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

| Param | Type | Description | | --- | --- | --- | | name | string | Screen name | | [options] | object | | | [options.hitParams] | Array.<map> | One or more additional params to set on the hit. |

usageStats.exception([options]) ⇒ Map

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

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

usageStats.debug() ⇒ Promise

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.

usageStats.abort() ↩︎

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

Kind: instance method of UsageStats
Chainable


© 2016-23 Lloyd Brookes <[email protected]>. Documented by jsdoc-to-markdown.