Analytics for ostr.io

ostr.io provides lightweight and full-featured visitor's analytics for websites. Our solution fully compatible and works out of the box with Meteor, Vue, React, Angular, Backbone, Ember and other front-end JavaScript frameworks.

Why ostr.io analytics?:

👐 Open Source tracking code;
📦 Lightweight, less than 2.8KB;
🚀 Fast, all metrics are available in real-time;
😎 No DOM changes;
😎 No heavy CPU tasks;
😎 No extra scripts loading;
📡 Utilizes Beacon API when available;
🤝 Support for History API (HTML5 History Management);
🤝 Support most of JavaScript front-end based frameworks and routings;
⚡️ Track Accelerated Mobile Pages (AMP);
🛑 Detect and Track AdBlock usage;
🔍 Transparent data collection;
😎 Respect DNT policy;
👨‍⚖️ Follows latest GDPR recommendations;
🙆 Easy opt-out procedure for end-users;
🐞 Global Runtime Errors tracking - Whenever an error happens during runtime you will be reported to "Errors" section. This is super-useful as you never can test your client's code in all imaginable environments, but your website visitors do.

Analytics includes:

Real-time users;
Sessions;
Unique users;
Pageviews:
- Page title;
- Page URL.
Demographics:
- Country;
- City.
System:
- Mobile devices;
- Browsers;
- Operating System.
Behavior:
- Custom events (see below);
- Referrers.
Global Scripts Errors and Exceptions:
- Catch all JS-runtime errors and exceptions;
- Browser name and release;
- Operating System name and release;
- Device name and version;
- Script name and line number where the error occurred.

Installation

Installation options:

Include suggested script tag into head of your HTML page - The simplest way;
Include code from this repository into main website' script file;
Install via NPM;
Install via Atmosphere (Meteor).

To find installation instruction - go to 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).

Script tag:

1<script async defer type="text/javascript" src="https://analytics.ostr.io/{{trackingId}}.js"></script>

Meteor via Atmosphere:

meteor add ostrio:analytics

Meteor via NPM:

meteor npm install ostrio-analytics --save

NPM:

npm install ostrio-analytics --save

Usage

Constructor `new Analytics(trackingId [, auto])`

trackingId {String} - [Required] Website' identifier. To obtain trackingId go to Analytics section and select a domain name;
auto - {Boolean} - [Optional] Default - true. If set to false all visits and actions have to be tracked with .track() method, see below.

Script Tag:

1// After including script-tag
2// analytics automatically executes in 'auto' mode,
3// its instance is available in global scope as `OstrioTracker`
4// Example: OstrioTracker.pushEvent(foo, bar);

Meteor/ES6:

1import Analytics from 'meteor/ostrio:analytics';
2const analyticsTracker = new Analytics('trackingId');

Meteor/NPM:

1const analyticsTracker = new (require('ostrio-analytics'))('trackingId');

NPM (CommonJS/RequireJS/Module):

1const analyticsTracker = new (require('ostrio-analytics'))('trackingId');

Using minifed version:

1// After adding minified analytics code to your project
2// In global scope as `OstrioTrackerClass` and `OTC`
3// as a short (short name was used in initial release,
4// we keep it for compatibility reasons)
5
6// Example:
7const analyticsTracker = new OstrioTrackerClass('trackingId');
8// Example 2:
9const analyticsTracker = new window.OstrioTrackerClass('trackingId');
10// Example 3 (shorthand):
11const analyticsTracker = new OTC('trackingId');
12// Example 4 (shorthand):
13const analyticsTracker = new window.OTC('trackingId');
14// Example 5: Initiate class with disabled "auto" tracking
15// With disabled "auto" tracking you need to use
16// `.track()` method to track a "visit"
17const analyticsTracker = new window.OTC('trackingId', false);
18whenUserVisit(() => {
19  analyticsTracker.track();
20});

From this point, you're good to go. All visitor's actions will be collected by ostr.io analytics. For custom events - see below.

`.pushEvent(key, value)` method

Custom events are useful for tracking certain activity on your website, like clicks, form submits and others user's behaviors.

key {String} - [Required] The length of the event key must be between 1 and 24 symbols;
value {String} - [Required] The length of the event value must be between 1 and 64 symbols.

If the length of key or value is longer than limits, it will be truncated without throwing an exception.

Examples:

1// Various examples on tracking custom user's actions
2analyticsTracker.pushEvent('userAction', 'login');
3analyticsTracker.pushEvent('userAction', 'logout');
4analyticsTracker.pushEvent('userAction', 'signup');
5
6analyticsTracker.pushEvent('click', 'purchase');
7analyticsTracker.pushEvent('click', 'purchase-left');
8analyticsTracker.pushEvent('click', 'pricing - more info');

1<script type="text/javascript">
2  // make analyticsTracker global variable
3  window.analyticsTracker = analyticsTracker;
4</script>
5
6<form>
7  <h2>Buy Now</h2>
8  <select>
9    <option disabled>Select product</option>
10    <option>Blue</option>
11    <option>Red</option>
12    <option>Green</option>
13  </select>
14  <input name="qty" />
15  <!-- Example on tracking form submit -->
16  <button type="submit" onClick="analyticsTracker.pushEvent('checkout', 'buy-now-form')">Checkout</button>
17</form>

In a similar way using .pushEvent you can detect and track AdBlock usage and Accelerated Mobile Pages (AMP).

`.track()` method

Use to manually send tracking info. This method has no arguments.

Examples:

1const Analytics = require('ostrio-analytics');
2const analyticsTracker = new Analytics('trackingId', false);
3
4// jQuery or any other similar case:
5$(document).ready(() => {
6  analyticsTracker.track();
7});

`.onPushEvent()` method

Use to hook on .pushEvent() method. Read how to use this method for deep Google Analytics integration.

Examples:

1const Analytics = require('ostrio-analytics');
2const analyticsTracker = new Analytics('trackingId');
3
4analyticsTracker.onPushEvent((key, value) => {
5  console.log({ key, value });
6  // OUTPUT:
7  // { key: 'testKey', value: 'testValue' }
8});
9
10analyticsTracker.pushEvent('testKey', 'testValue');

`.onTrack()` method

Use to hook on .track() method and browser navigation. Read how to use this method for deep Google Analytics integration.

Examples:

1const Analytics = require('ostrio-analytics');
2const analyticsTracker = new Analytics('trackingId');
3
4analyticsTracker.onTrack(() => {
5  console.log('Tacking a session');
6  // OUTPUT :
7  // Tacking a session
8});
9
10// Callback will be executed on every browser navigation
11// or upon calling `.track()` method
12analyticsTracker.track();

Other examples

Deep router integration:

1const Analytics = require('ostrio-analytics');
2const analyticsTracker = new Analytics('trackingId', false);
3
4/*!pseudo code!*/
5router({
6  '/'() {
7    analyticsTracker.track();
8  },
9  '/two'() {
10    analyticsTracker.track();
11  },
12  '/three'() {
13    analyticsTracker.track();
14  }
15});

Deep History.js Integration

Although "History.js" and "History API" supported out-of-box, you may want to optimize tracking behavior to meet your needs.

1const Analytics = require('ostrio-analytics');
2const analyticsTracker = new Analytics('trackingId', false);
3
4History.Adapter.bind(window, 'statechange', () => {
5  analyticsTracker.track();
6});

Google Analytics integration

Using .onTrack() method and .onPushEvent() method we can send tracking-data to Google Analytics upon navigation or event.

In your <head> add Google Analytics as instructed:

1<script async src="https://www.google-analytics.com/analytics.js"></script>
2<script type='text/javascript'>
3  window.ga=window.ga||function(){(ga.q=ga.q||[]).push(arguments)};ga.l=+new Date;
4  ga('create', 'UA-XXXXXXXXX-X', 'auto');
5  if ('sendBeacon' in navigator) {
6    ga('set', 'transport', 'beacon');
7  }
8</script>

1const Analytics = require('ostrio-analytics');
2const analyticsTracker = new Analytics('trackingId');
3
4analyticsTracker.onTrack(() => {
5  // Track navigation with Google Analytics
6  ga('send', {
7    hitType: 'pageview',
8    page: document.location.pathname,
9    location: document.location.href,
10    title: document.title
11  });
12});
13
14analyticsTracker.onPushEvent((name, value) => {
15  // Send events to Google Analytics
16  ga('send', {
17    hitType: 'event',
18    eventCategory: name,
19    eventAction: value
20  });
21});

Google Tag Manager integration

Using .onTrack() method and .onPushEvent() method we can send tracking-data to Google Tag Manager upon navigation or event.

In your <head> add Google Tag Manager as instructed:

1<script async src="https://www.googletagmanager.com/gtag/js?id=UA-XXXXXXXXX-X"></script>
2<script type='text/javascript'>
3  window.dataLayer = window.dataLayer || [];
4  function gtag(){dataLayer.push(arguments);}
5  gtag('js', new Date());
6</script>

1const Analytics = require('ostrio-analytics');
2const analyticsTracker = new Analytics('trackingId', false);
3
4analyticsTracker.onTrack(() => {
5  // Track navigation with Google Analytics
6  gtag('config', 'UA-XXXXXXXXX-X', {
7    page_title: document.title,
8    page_path: document.location.pathname,
9    page_location: document.location.href
10  });
11});
12
13_app.OstrioTracker.onPushEvent((name, value) => {
14  // Send events to Google Analytics
15  gtag('event', name, { value });
16});

Opt-out for end-users

As our analytics solution fully respects DNT signals, to opt-out end-users need to activate DNT signals in a browser. To find out how to enable DNT and read more about "Do Not Track", visit - All About DNT homepage.

ostrio:analytics

Analytics for ostr.io

ToC:

Why ostr.io analytics?:

Analytics includes:

Installation

Script tag:

Meteor via Atmosphere:

Meteor via NPM:

NPM:

Usage

Constructor new Analytics(trackingId [, auto])

Script Tag:

Meteor/ES6:

Meteor/NPM:

NPM (CommonJS/RequireJS/Module):

Using minifed version:

.pushEvent(key, value) method

.track() method

.onPushEvent() method

.onTrack() method

Other examples

Deep router integration:

Deep History.js Integration

Google Analytics integration

Google Tag Manager integration

Opt-out for end-users

Constructor `new Analytics(trackingId [, auto])`

`.pushEvent(key, value)` method

`.track()` method

`.onPushEvent()` method

`.onTrack()` method