{"id":15013479,"url":"https://github.com/veliovgroup/ostrio-analytics","last_synced_at":"2025-07-18T10:08:06.200Z","repository":{"id":57316671,"uuid":"53820651","full_name":"veliovgroup/ostrio-analytics","owner":"veliovgroup","description":"📊 Visitor's analytics tracking code for ostr.io service","archived":false,"fork":false,"pushed_at":"2024-08-16T08:37:33.000Z","size":82,"stargazers_count":14,"open_issues_count":0,"forks_count":1,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-06-30T22:17:31.715Z","etag":null,"topics":["analytics","dnt","efficiency","history-api","lightweight","meteor","meteor-package","npm-package","web-analytics"],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/ostrio-analytics","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/veliovgroup.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2016-03-14T02:24:50.000Z","updated_at":"2024-08-16T08:37:37.000Z","dependencies_parsed_at":"2024-08-16T10:08:05.264Z","dependency_job_id":null,"html_url":"https://github.com/veliovgroup/ostrio-analytics","commit_stats":{"total_commits":58,"total_committers":2,"mean_commits":29.0,"dds":"0.017241379310344862","last_synced_commit":"73f0bf61a9795de9e2e2838924c4592542d15227"},"previous_names":[],"tags_count":16,"template":false,"template_full_name":null,"purl":"pkg:github/veliovgroup/ostrio-analytics","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/veliovgroup%2Fostrio-analytics","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/veliovgroup%2Fostrio-analytics/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/veliovgroup%2Fostrio-analytics/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/veliovgroup%2Fostrio-analytics/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/veliovgroup","download_url":"https://codeload.github.com/veliovgroup/ostrio-analytics/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/veliovgroup%2Fostrio-analytics/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":265738513,"owners_count":23820165,"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":["analytics","dnt","efficiency","history-api","lightweight","meteor","meteor-package","npm-package","web-analytics"],"created_at":"2024-09-24T19:44:20.262Z","updated_at":"2025-07-18T10:08:06.179Z","avatar_url":"https://github.com/veliovgroup.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Analytics for [ostr.io](https://ostr.io)\n\n[ostr.io](https://ostr.io) provides lightweight and full-featured [visitor's analytics](https://ostr.io/info/web-analytics) for websites. Our solution fully compatible and works *out of the box* with React.js, Next.js, Vue.js, Nuxt.js, Svelte.js, Meteor.js, Blaze.js, Angular.js, Backbone.js, Ember.js and other front-end JavaScript frameworks.\n\n## ToC:\n\n- [Why ostr.io analytics?](https://github.com/VeliovGroup/ostrio-analytics#why-ostrio-analytics)\n- [List of tracked data](https://github.com/VeliovGroup/ostrio-analytics#analytics-includes)\n- [Installation](https://github.com/VeliovGroup/ostrio-analytics#installation):\n  - [`\u003cscript\u003e` tag](https://github.com/VeliovGroup/ostrio-analytics#script-tag)\n  - [NPM](https://github.com/VeliovGroup/ostrio-analytics#npm)\n  - [Meteor (NPM)](https://github.com/VeliovGroup/ostrio-analytics#meteor-via-npm)\n  - [Meteor (Atmosphere)](https://github.com/VeliovGroup/ostrio-analytics#meteor-via-atmosphere)\n- [API](https://github.com/VeliovGroup/ostrio-analytics#usage):\n  - [`new Analytics(/*...*/)`](https://github.com/VeliovGroup/ostrio-analytics#constructor-new-analyticstrackingid--auto)\n  - [`Analytics#track()`](https://github.com/VeliovGroup/ostrio-analytics#track-method)\n  - [`Analytics#pushEvent()`](https://github.com/VeliovGroup/ostrio-analytics#pusheventkey-value-method)\n  - [`Analytics#onTrack()`](https://github.com/VeliovGroup/ostrio-analytics#ontrack-method)\n  - [`Analytics#onPushEvent()`](https://github.com/VeliovGroup/ostrio-analytics#onpushevent-method)\n- [Examples](https://github.com/VeliovGroup/ostrio-analytics#other-examples):\n  - [Router integration](https://github.com/VeliovGroup/ostrio-analytics#deep-router-integration)\n  - [History.js integration](https://github.com/VeliovGroup/ostrio-analytics#deep-historyjs-integration)\n  - [Google Analytics integration](https://github.com/VeliovGroup/ostrio-analytics#google-analytics-integration)\n  - [Google Tag Manager integration](https://github.com/VeliovGroup/ostrio-analytics#google-tag-manager-integration)\n- [__Opt-out for end-users__](https://github.com/VeliovGroup/ostrio-analytics#opt-out-for-end-users)\n\n## Why [ostr.io](https://ostr.io/info/web-analytics) analytics?:\n\n- 👐 Open Source tracking code;\n- 📦 Lightweight, less than 2.8KB;\n- 🚀 Fast, all metrics are available in real-time;\n- 😎 No DOM changes;\n- 😎 No heavy CPU tasks;\n- 😎 No extra scripts loading;\n- 📡 Utilizes [Beacon API](https://developer.mozilla.org/en-US/docs/Web/API/Beacon_API) when available;\n- 🤝 Support for History API (*HTML5 History Management*);\n- 🤝 Support most of JavaScript front-end based frameworks and routings;\n- ⚡️ [Track Accelerated Mobile Pages (AMP)](https://github.com/VeliovGroup/ostrio/blob/master/docs/analytics/track-amp.md);\n- 🛑 [Detect and Track AdBlock usage](https://github.com/VeliovGroup/ostrio/blob/master/docs/analytics/detect-adblock.md);\n- 🔍 Transparent data collection;\n- 👨‍⚖️ Follows latest GDPR recommendations;\n- 🙆 [Easy opt-out procedure for end-users](#opt-out-for-end-users);\n- 🐞 Global Runtime Errors tracking - *Whenever an error happens during runtime you will receive report to* \"Errors\" *section. This is super-useful as errors reported right from user's device allowing to website visitors participate in testing of all imaginable devices and software combinations*.\n\n## Analytics includes:\n\n- Real-time users;\n- Sessions;\n- Unique users;\n- Pageviews:\n  - Page title;\n  - Page URL.\n- Demographics:\n  - Country;\n  - City.\n- System:\n  - Mobile devices;\n  - Browsers;\n  - Operating System.\n- Behavior:\n  - Custom events (*see below*);\n  - Referrers.\n- Global Scripts Errors and Exceptions:\n  - Catch all JS-runtime errors and exceptions;\n  - Browser name and release;\n  - Operating System name and release;\n  - Device name and version;\n  - Script name and line number where the error occurred.\n\n## Installation\n\nInstallation options:\n\n- Include suggested `script` tag into `head` of your HTML page - The simplest way;\n- Include code from this repository into main website' script file;\n- Install via NPM;\n- Install via Atmosphere (Meteor).\n\nTo find installation instruction - go to [Analytics](https://ostr.io/service/analytics) section and select domain name for which you would like to install visitors metrics. To find \"Tracking ID\" click on \"Show integration guide\" and pick `{{trackingId}}` (*17 symbols*).\n\n### Script tag:\n\n```html\n\u003cscript async defer type=\"text/javascript\" src=\"https://analytics.ostr.io/{{trackingId}}.js\"\u003e\u003c/script\u003e\n```\n\n### Meteor via Atmosphere:\n\n```shell\nmeteor add ostrio:analytics\n```\n\n### Meteor via NPM:\n\n```shell\nmeteor npm install ostrio-analytics --save\n```\n\n### NPM:\n\n```shell\nnpm install ostrio-analytics --save\n```\n\n## Usage\n\n### Constructor `new Analytics(trackingId [, auto])`\n\n- `trackingId` {*String*} - [Required] Website' identifier. To obtain `trackingId` go to [Analytics](https://ostr.io/service/analytics) section and select a domain name;\n- `auto` - {*Boolean*} - [Optional] Default - `true`. If set to `false` all visits and actions have to be tracked with `.track()` method, see below.\n\n#### Script Tag:\n\n```js\n// After including script-tag\n// analytics automatically executes in 'auto' mode,\n// its instance is available in global scope as `OstrioTracker`\n// Example: OstrioTracker.pushEvent(foo, bar);\n```\n\n#### Meteor/ES6:\n\n```js\nimport Analytics from 'meteor/ostrio:analytics';\nconst analyticsTracker = new Analytics('trackingId');\n```\n\n#### Meteor/NPM:\n\n```js\nconst analyticsTracker = new (require('ostrio-analytics'))('trackingId');\n```\n\n#### NPM (CommonJS/RequireJS/Module):\n\n```js\nconst analyticsTracker = new (require('ostrio-analytics'))('trackingId');\n```\n\n#### Using minifed version:\n\n```js\n// After adding minified analytics code to your project\n// In global scope as `OstrioTrackerClass` and `OTC`\n// as a short (short name was used in initial release,\n// we keep it for compatibility reasons)\n\n// Example:\nconst analyticsTracker = new OstrioTrackerClass('trackingId');\n// Example 2:\nconst analyticsTracker = new window.OstrioTrackerClass('trackingId');\n// Example 3 (shorthand):\nconst analyticsTracker = new OTC('trackingId');\n// Example 4 (shorthand):\nconst analyticsTracker = new window.OTC('trackingId');\n// Example 5: Initiate class with disabled \"auto\" tracking\n// With disabled \"auto\" tracking you need to use\n// `.track()` method to track a \"visit\"\nconst analyticsTracker = new window.OTC('trackingId', false);\nwhenUserVisit(() =\u003e {\n  analyticsTracker.track();\n});\n```\n\n*From this point, you're good to go. All visitor's actions will be collected by ostr.io analytics. For custom events - see below.*\n\n### `.pushEvent(key, value)` method\n\nCustom events are useful for tracking certain activity on your website, like clicks, form submits and others user's behaviors.\n\n- `key` {*String*} - [Required] The length of the event key must be between 1 and 24 symbols;\n- `value` {*String*} - [Required] The length of the event value must be between 1 and 64 symbols.\n\nIf the length of `key` or `value` is longer than limits, it will be truncated without throwing an exception.\n\nExamples:\n\n```js\n// Various examples on tracking custom user's actions\nanalyticsTracker.pushEvent('userAction', 'login');\nanalyticsTracker.pushEvent('userAction', 'logout');\nanalyticsTracker.pushEvent('userAction', 'signup');\n\nanalyticsTracker.pushEvent('click', 'purchase');\nanalyticsTracker.pushEvent('click', 'purchase-left');\nanalyticsTracker.pushEvent('click', 'pricing - more info');\n```\n\n```html\n\u003cscript type=\"text/javascript\"\u003e\n  // make analyticsTracker global variable\n  window.analyticsTracker = analyticsTracker;\n\u003c/script\u003e\n\n\u003cform\u003e\n  \u003ch2\u003eBuy Now\u003c/h2\u003e\n  \u003cselect\u003e\n    \u003coption disabled\u003eSelect product\u003c/option\u003e\n    \u003coption\u003eBlue\u003c/option\u003e\n    \u003coption\u003eRed\u003c/option\u003e\n    \u003coption\u003eGreen\u003c/option\u003e\n  \u003c/select\u003e\n  \u003cinput name=\"qty\" /\u003e\n  \u003c!-- Example on tracking form submit --\u003e\n  \u003cbutton type=\"submit\" onClick=\"analyticsTracker.pushEvent('checkout', 'buy-now-form')\"\u003eCheckout\u003c/button\u003e\n\u003c/form\u003e\n```\n\nIn a similar way using `.pushEvent` you can detect and track [AdBlock usage](https://github.com/VeliovGroup/ostrio/blob/master/docs/analytics/detect-adblock.md) and [Accelerated Mobile Pages (AMP)](https://github.com/VeliovGroup/ostrio/blob/master/docs/analytics/track-amp.md).\n\n### `.track()` method\n\nUse to manually send tracking info. This method has no arguments.\n\nExamples:\n\n```js\nconst Analytics = require('ostrio-analytics');\nconst analyticsTracker = new Analytics('trackingId', false);\n\n// jQuery or any other similar case:\n$(document).ready(() =\u003e {\n  analyticsTracker.track();\n});\n```\n\n### `.onPushEvent()` method\n\nUse to hook on [`.pushEvent()` method](https://github.com/VeliovGroup/ostrio-analytics#pusheventkey-value-method). Read how to use this method for deep [Google Analytics integration](https://github.com/VeliovGroup/ostrio-analytics#google-analytics-integration).\n\nExamples:\n\n```js\nconst Analytics = require('ostrio-analytics');\nconst analyticsTracker = new Analytics('trackingId');\n\nanalyticsTracker.onPushEvent((key, value) =\u003e {\n  console.log({ key, value });\n  // OUTPUT:\n  // { key: 'testKey', value: 'testValue' }\n});\n\nanalyticsTracker.pushEvent('testKey', 'testValue');\n```\n\n### `.onTrack()` method\n\nUse to hook on [`.track()` method](https://github.com/VeliovGroup/ostrio-analytics#track-method) and browser navigation. Read how to use this method for deep [Google Analytics integration](https://github.com/VeliovGroup/ostrio-analytics#google-analytics-integration).\n\nExamples:\n\n```js\nconst Analytics = require('ostrio-analytics');\nconst analyticsTracker = new Analytics('trackingId');\n\nanalyticsTracker.onTrack(() =\u003e {\n  console.log('Tacking a session');\n  // OUTPUT :\n  // Tacking a session\n});\n\n// Callback will be executed on every browser navigation\n// or upon calling `.track()` method\nanalyticsTracker.track();\n```\n\n## Other examples\n\n### Deep router integration:\n\n```js\nconst Analytics = require('ostrio-analytics');\nconst analyticsTracker = new Analytics('trackingId', false);\n\n/* router definition */\nrouter({\n  '/'() {\n    analyticsTracker.track();\n  },\n  '/two'() {\n    analyticsTracker.track();\n  },\n  '/three'() {\n    analyticsTracker.track();\n  }\n});\n```\n\n### Deep History.js Integration\n\nAlthough \"History.js\" and \"History API\" supported out-of-box, you may want to optimize tracking behavior to meet your needs.\n\n```js\nconst Analytics = require('ostrio-analytics');\nconst analyticsTracker = new Analytics('trackingId', false);\n\nHistory.Adapter.bind(window, 'statechange', () =\u003e {\n  analyticsTracker.track();\n});\n```\n\n### Google Analytics integration\n\nUsing [`.onTrack()` method](https://github.com/VeliovGroup/ostrio-analytics#ontrack-method) and [`.onPushEvent()` method](https://github.com/VeliovGroup/ostrio-analytics#onpushevent-method) we can send tracking-data to Google Analytics upon navigation or event.\n\nIn your `\u003chead\u003e` add Google Analytics as instructed:\n\n```html\n\u003cscript async src=\"https://www.google-analytics.com/analytics.js\"\u003e\u003c/script\u003e\n\u003cscript type='text/javascript'\u003e\n  window.ga=window.ga||function(){(ga.q=ga.q||[]).push(arguments)};ga.l=+new Date;\n  ga('create', 'UA-XXXXXXXXX-X', 'auto');\n  if ('sendBeacon' in navigator) {\n    ga('set', 'transport', 'beacon');\n  }\n\u003c/script\u003e\n```\n\n```js\nconst Analytics = require('ostrio-analytics');\nconst analyticsTracker = new Analytics('trackingId');\n\nanalyticsTracker.onTrack(() =\u003e {\n  // Track navigation with Google Analytics\n  ga('send', {\n    hitType: 'pageview',\n    page: document.location.pathname,\n    location: document.location.href,\n    title: document.title\n  });\n});\n\nanalyticsTracker.onPushEvent((name, value) =\u003e {\n  // Send events to Google Analytics\n  ga('send', {\n    hitType: 'event',\n    eventCategory: name,\n    eventAction: value\n  });\n});\n```\n\n### Google Tag Manager integration\n\nUsing [`.onTrack()` method](https://github.com/VeliovGroup/ostrio-analytics#ontrack-method) and [`.onPushEvent()` method](https://github.com/VeliovGroup/ostrio-analytics#onpushevent-method) we can send tracking-data to Google Tag Manager upon navigation or event.\n\nIn your `\u003chead\u003e` add Google Tag Manager as instructed:\n\n```html\n\u003cscript async src=\"https://www.googletagmanager.com/gtag/js?id=UA-XXXXXXXXX-X\"\u003e\u003c/script\u003e\n\u003cscript type='text/javascript'\u003e\n  window.dataLayer = window.dataLayer || [];\n  function gtag(){dataLayer.push(arguments);}\n  gtag('js', new Date());\n\u003c/script\u003e\n```\n\n```js\nconst Analytics = require('ostrio-analytics');\nconst analyticsTracker = new Analytics('trackingId', false);\n\nanalyticsTracker.onTrack(() =\u003e {\n  // Track navigation with Google Analytics\n  gtag('config', 'UA-XXXXXXXXX-X', {\n    page_title: document.title,\n    page_path: document.location.pathname,\n    page_location: document.location.href\n  });\n});\n\n_app.OstrioTracker.onPushEvent((name, value) =\u003e {\n  // Send events to Google Analytics\n  gtag('event', name, { value });\n});\n```\n\n### Opt-out for end-users\n\n[One-click opt-out](https://analytics.ostr.io/settings/manage/opt-out/) procedure. Webmasters can add \"opt-out link\" to their legal documents and \"settings\" pages to follow the best privacy experience practices.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fveliovgroup%2Fostrio-analytics","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fveliovgroup%2Fostrio-analytics","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fveliovgroup%2Fostrio-analytics/lists"}