{"id":16644220,"url":"https://github.com/75lb/usage-stats","last_synced_at":"2025-03-21T15:32:41.089Z","repository":{"id":57387803,"uuid":"65243134","full_name":"75lb/usage-stats","owner":"75lb","description":"A minimal Google Analytics Measurement Protocol client for tracking statistics in shell and javascript applications","archived":false,"fork":false,"pushed_at":"2023-01-16T21:29:43.000Z","size":217,"stargazers_count":12,"open_issues_count":0,"forks_count":2,"subscribers_count":5,"default_branch":"master","last_synced_at":"2024-04-24T13:36:10.882Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/75lb.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2016-08-08T22:11:57.000Z","updated_at":"2023-01-16T21:23:32.000Z","dependencies_parsed_at":"2023-02-10T06:31:22.623Z","dependency_job_id":null,"html_url":"https://github.com/75lb/usage-stats","commit_stats":null,"previous_names":[],"tags_count":34,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/75lb%2Fusage-stats","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/75lb%2Fusage-stats/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/75lb%2Fusage-stats/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/75lb%2Fusage-stats/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/75lb","download_url":"https://codeload.github.com/75lb/usage-stats/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":244822753,"owners_count":20516159,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-10-12T08:10:49.071Z","updated_at":"2025-03-21T15:32:40.813Z","avatar_url":"https://github.com/75lb.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![view on npm](https://badgen.net/npm/v/usage-stats)](https://www.npmjs.org/package/usage-stats)\n[![npm module downloads](https://badgen.net/npm/dt/usage-stats)](https://www.npmjs.org/package/usage-stats)\n[![Gihub repo dependents](https://badgen.net/github/dependents-repo/75lb/usage-stats)](https://github.com/75lb/usage-stats/network/dependents?dependent_type=REPOSITORY)\n[![Gihub package dependents](https://badgen.net/github/dependents-pkg/75lb/usage-stats)](https://github.com/75lb/usage-stats/network/dependents?dependent_type=PACKAGE)\n[![Node.js CI](https://github.com/75lb/usage-stats/actions/workflows/node.js.yml/badge.svg)](https://github.com/75lb/usage-stats/actions/workflows/node.js.yml)\n[![js-standard-style](https://img.shields.io/badge/code%20style-standard-brightgreen.svg)](https://github.com/feross/standard)\n\n# usage-stats\n\nA minimal, offline-friendly [Google Analytics Measurement Protocol](https://developers.google.com/analytics/devguides/collection/protocol/v1/) client for tracking usage statistics in shell and javascript applications.\n\nThis 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](https://support.google.com/analytics/answer/2709828?hl=en\u0026ref_topic=2709827), take a look at [app-usage-stats](https://github.com/75lb/app-usage-stats). For the command line client see [usage-stats-cli](https://github.com/75lb/usage-stats-cli).\n\n## Synopsis\n\nThe most trivial example.\n\n```js\nconst UsageStats = require('usage-stats')\nconst usageStats = new UsageStats('UA-98765432-1', { an: 'example' })\n\nusageStats.screenView('screen name')\nusageStats.event('category', 'action')\nusageStats.send()\n```\n\nMore realistic usage in a server application:\n\n```js\nconst UsageStats = require('usage-stats')\nconst usageStats = new UsageStats('UA-98765432-1', {\n  an: 'encode-video',\n  av: '1.0.0'\n})\n\n// start a new session\nusageStats.start()\n\n// user set two options..\nusageStats.event('option', 'verbose-level', 'infinite')\nusageStats.event('option', 'preset', 'iPod')\n\ntry {\n  // Begin. Track as a screenView.\n  usageStats.screenView('encoding')\n  beginEncoding(options)\n} catch (err) {\n  // Exception tracking\n  usageStats.exception(err.message, true)\n}\n\n// finished - mark the session as complete\n// and send stats (or store if offline).\nusageStats.end().send()\n```\n\n## Protocol Parameters\n\nSee [here](https://developers.google.com/analytics/devguides/collection/protocol/v1/parameters) for the full list of Google Analytics Measurement Protocol parameters.\n\n### Sent by default\n\nAll parameters are send on demand, beside this list.\n\n* Operating System version (sent in the UserAgent)\n* [Client ID](https://developers.google.com/analytics/devguides/collection/protocol/v1/parameters#cid) (a random UUID, generated once per OS user and stored)\n* [Language](https://developers.google.com/analytics/devguides/collection/protocol/v1/parameters#ul) (`process.env.LANG`, if set)\n* [Screen resolution](https://developers.google.com/analytics/devguides/collection/protocol/v1/parameters#sr) (terminal rows by columns, by default)\n\n## API Reference\n\n**Kind**: Exported class  \n* [UsageStats](#exp_module_usage-stats--UsageStats) ⏏\n    * [new UsageStats(trackingId, [options])](#new_module_usage-stats--UsageStats_new)\n    * [.dir](#module_usage-stats--UsageStats.UsageStats+dir) : \u003ccode\u003estring\u003c/code\u003e\n    * [.defaults](#module_usage-stats--UsageStats.UsageStats+defaults) : \u003ccode\u003eMap\u003c/code\u003e\n    * [.start([sessionParams])](#module_usage-stats--UsageStats+start) ↩︎\n    * [.end([sessionParams])](#module_usage-stats--UsageStats+end) ↩︎\n    * [.disable()](#module_usage-stats--UsageStats+disable) ↩︎\n    * [.enable()](#module_usage-stats--UsageStats+enable) ↩︎\n    * [.event(category, action, [options])](#module_usage-stats--UsageStats+event) ⇒ \u003ccode\u003eMap\u003c/code\u003e\n    * [.screenView(name, [options])](#module_usage-stats--UsageStats+screenView) ⇒ \u003ccode\u003eMap\u003c/code\u003e\n    * [.exception([options])](#module_usage-stats--UsageStats+exception) ⇒ \u003ccode\u003eMap\u003c/code\u003e\n    * [.send([options])](#module_usage-stats--UsageStats+send) ⇒ \u003ccode\u003ePromise\u003c/code\u003e\n    * [.debug()](#module_usage-stats--UsageStats+debug) ⇒ \u003ccode\u003ePromise\u003c/code\u003e\n    * [.abort()](#module_usage-stats--UsageStats+abort) ↩︎\n\n\u003ca name=\"new_module_usage-stats--UsageStats_new\"\u003e\u003c/a\u003e\n\n### new UsageStats(trackingId, [options])\n\n| Param | Type | Description |\n| --- | --- | --- |\n| trackingId | \u003ccode\u003estring\u003c/code\u003e | Google Analytics tracking ID (required). |\n| [options] | \u003ccode\u003eobject\u003c/code\u003e |  |\n| [options.an] | \u003ccode\u003estring\u003c/code\u003e | App name |\n| [options.av] | \u003ccode\u003estring\u003c/code\u003e | App version |\n| [options.lang] | \u003ccode\u003estring\u003c/code\u003e | Language. Defaults to `process.env.LANG`. |\n| [options.sr] | \u003ccode\u003estring\u003c/code\u003e | Screen resolution. Defaults to `${process.stdout.rows}x${process.stdout.columns}`. |\n| [options.ua] | \u003ccode\u003estring\u003c/code\u003e | User Agent string to use. |\n| [options.dir] | \u003ccode\u003estring\u003c/code\u003e | Path of the directory used for persisting clientID and queue. Defaults to `~/.usage-stats`. |\n| [options.url] | \u003ccode\u003estring\u003c/code\u003e | Defaults to `'https://www.google-analytics.com/batch'`. |\n| [options.debugUrl] | \u003ccode\u003estring\u003c/code\u003e | Defaults to `'https://www.google-analytics.com/debug/collect'`. |\n\n**Example**  \n```js\nconst usageStats = new UsageStats('UA-98765432-1', {\n  an: 'sick app',\n  av: '1.0.0'\n})\n```\n\u003ca name=\"module_usage-stats--UsageStats.UsageStats+dir\"\u003e\u003c/a\u003e\n\n### usageStats.dir : \u003ccode\u003estring\u003c/code\u003e\nCache directory. Defaults to `~/.usage-stats`.\n\n**Kind**: instance property of [\u003ccode\u003eUsageStats\u003c/code\u003e](#exp_module_usage-stats--UsageStats)  \n\u003ca name=\"module_usage-stats--UsageStats.UsageStats+defaults\"\u003e\u003c/a\u003e\n\n### usageStats.defaults : \u003ccode\u003eMap\u003c/code\u003e\nA list of parameters to be to sent with every hit.\n\n**Kind**: instance property of [\u003ccode\u003eUsageStats\u003c/code\u003e](#exp_module_usage-stats--UsageStats)  \n**Example**  \n```js\nusageStats.defaults\n  .set('cd1', process.version)\n  .set('cd2', os.type())\n  .set('cd3', os.release())\n  .set('cd4', 'api')\n```\n\u003ca name=\"module_usage-stats--UsageStats+start\"\u003e\u003c/a\u003e\n\n### usageStats.start([sessionParams]) ↩︎\nStarts the [session](https://developers.google.com/analytics/devguides/collection/protocol/v1/parameters#sc).\n\n**Kind**: instance method of [\u003ccode\u003eUsageStats\u003c/code\u003e](#exp_module_usage-stats--UsageStats)  \n**Chainable**  \n\n| Param | Type | Description |\n| --- | --- | --- |\n| [sessionParams] | \u003ccode\u003eArray.\u0026lt;Map\u0026gt;\u003c/code\u003e | An optional map of paramaters to send with each hit in the sesison. |\n\n\u003ca name=\"module_usage-stats--UsageStats+end\"\u003e\u003c/a\u003e\n\n### usageStats.end([sessionParams]) ↩︎\nEnds the [session](https://developers.google.com/analytics/devguides/collection/protocol/v1/parameters#sc).\n\n**Kind**: instance method of [\u003ccode\u003eUsageStats\u003c/code\u003e](#exp_module_usage-stats--UsageStats)  \n**Chainable**  \n\n| Param | Type | Description |\n| --- | --- | --- |\n| [sessionParams] | \u003ccode\u003eArray.\u0026lt;Map\u0026gt;\u003c/code\u003e | An optional map of paramaters to send with the final hit of this sesison. |\n\n\u003ca name=\"module_usage-stats--UsageStats+disable\"\u003e\u003c/a\u003e\n\n### usageStats.disable() ↩︎\nDisable the module. While disabled, all operations are no-ops.\n\n**Kind**: instance method of [\u003ccode\u003eUsageStats\u003c/code\u003e](#exp_module_usage-stats--UsageStats)  \n**Chainable**  \n\u003ca name=\"module_usage-stats--UsageStats+enable\"\u003e\u003c/a\u003e\n\n### usageStats.enable() ↩︎\nRe-enable the module.\n\n**Kind**: instance method of [\u003ccode\u003eUsageStats\u003c/code\u003e](#exp_module_usage-stats--UsageStats)  \n**Chainable**  \n\u003ca name=\"module_usage-stats--UsageStats+event\"\u003e\u003c/a\u003e\n\n### usageStats.event(category, action, [options]) ⇒ \u003ccode\u003eMap\u003c/code\u003e\nTrack an event. All event hits are queued until `.send()` is called.\n\n**Kind**: instance method of [\u003ccode\u003eUsageStats\u003c/code\u003e](#exp_module_usage-stats--UsageStats)  \n\n| Param | Type | Description |\n| --- | --- | --- |\n| category | \u003ccode\u003estring\u003c/code\u003e | Event category (required). |\n| action | \u003ccode\u003estring\u003c/code\u003e | Event action (required). |\n| [options] | \u003ccode\u003eoption\u003c/code\u003e |  |\n| [options.el] | \u003ccode\u003estring\u003c/code\u003e | Event label |\n| [options.ev] | \u003ccode\u003estring\u003c/code\u003e | Event value |\n| [options.hitParams] | \u003ccode\u003eArray.\u0026lt;map\u0026gt;\u003c/code\u003e | One or more additional params to send with the hit. |\n\n\u003ca name=\"module_usage-stats--UsageStats+screenView\"\u003e\u003c/a\u003e\n\n### usageStats.screenView(name, [options]) ⇒ \u003ccode\u003eMap\u003c/code\u003e\nTrack a screenview. All screenview hits are queued until `.send()` is called. Returns the hit instance.\n\n**Kind**: instance method of [\u003ccode\u003eUsageStats\u003c/code\u003e](#exp_module_usage-stats--UsageStats)  \n\n| Param | Type | Description |\n| --- | --- | --- |\n| name | \u003ccode\u003estring\u003c/code\u003e | Screen name |\n| [options] | \u003ccode\u003eobject\u003c/code\u003e |  |\n| [options.hitParams] | \u003ccode\u003eArray.\u0026lt;map\u0026gt;\u003c/code\u003e | One or more additional params to set on the hit. |\n\n\u003ca name=\"module_usage-stats--UsageStats+exception\"\u003e\u003c/a\u003e\n\n### usageStats.exception([options]) ⇒ \u003ccode\u003eMap\u003c/code\u003e\nTrack a exception. All exception hits are queued until `.send()` is called.\n\n**Kind**: instance method of [\u003ccode\u003eUsageStats\u003c/code\u003e](#exp_module_usage-stats--UsageStats)  \n\n| Param | Type | Description |\n| --- | --- | --- |\n| [options] | \u003ccode\u003eobject\u003c/code\u003e | optional params |\n| [options.exd] | \u003ccode\u003estring\u003c/code\u003e | Error message |\n| [options.exf] | \u003ccode\u003eboolean\u003c/code\u003e | Set true if the exception was fatal |\n| [options.hitParams] | \u003ccode\u003eArray.\u0026lt;map\u0026gt;\u003c/code\u003e | One or more additional params to set on the hit. |\n\n\u003ca name=\"module_usage-stats--UsageStats+send\"\u003e\u003c/a\u003e\n\n### usageStats.send([options]) ⇒ \u003ccode\u003ePromise\u003c/code\u003e\nSend 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.\n\n**Kind**: instance method of [\u003ccode\u003eUsageStats\u003c/code\u003e](#exp_module_usage-stats--UsageStats)  \n**Fulfil**: \u003ccode\u003eresponse[]\u003c/code\u003e - array of responses. Each response has `data` and the original node `res`.  \n**Reject**: \u003ccode\u003eError\u003c/code\u003e - 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.  \n\n| Param | Type |\n| --- | --- |\n| [options] | \u003ccode\u003eobject\u003c/code\u003e | \n| [options.timeout] | \u003ccode\u003enumber\u003c/code\u003e | \n\n\u003ca name=\"module_usage-stats--UsageStats+debug\"\u003e\u003c/a\u003e\n\n### usageStats.debug() ⇒ \u003ccode\u003ePromise\u003c/code\u003e\nSend any hits (including queued) to the GA [validation server](https://developers.google.com/analytics/devguides/collection/protocol/v1/validating-hits), fulfilling with the result.\n\n**Kind**: instance method of [\u003ccode\u003eUsageStats\u003c/code\u003e](#exp_module_usage-stats--UsageStats)  \n**Fulfil**: \u003ccode\u003eResponse[]\u003c/code\u003e  \n**Reject**: \u003ccode\u003eError\u003c/code\u003e - Error instance includes `hits`.  \n\u003ca name=\"module_usage-stats--UsageStats+abort\"\u003e\u003c/a\u003e\n\n### usageStats.abort() ↩︎\nAborts the in-progress .send() operation, queuing any unsent hits.\n\n**Kind**: instance method of [\u003ccode\u003eUsageStats\u003c/code\u003e](#exp_module_usage-stats--UsageStats)  \n**Chainable**  \n\n* * *\n\n\u0026copy; 2016-23 Lloyd Brookes \\\u003c75pound@gmail.com\\\u003e. Documented by [jsdoc-to-markdown](https://github.com/jsdoc2md/jsdoc-to-markdown).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2F75lb%2Fusage-stats","html_url":"https://awesome.ecosyste.ms/projects/github.com%2F75lb%2Fusage-stats","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2F75lb%2Fusage-stats/lists"}