Ostrio-analytics NPM

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:

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

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

Meteor/ES6:

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

Meteor/NPM:

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

NPM (CommonJS/RequireJS/Module):

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

Using minifed version:

// After adding minified analytics code to your project
// In global scope as `OstrioTrackerClass` and `OTC`
// as a short (short name was used in initial release,
// we keep it for compatibility reasons)

// Example:
const analyticsTracker = new OstrioTrackerClass('trackingId');
// Example 2:
const analyticsTracker = new window.OstrioTrackerClass('trackingId');
// Example 3 (shorthand):
const analyticsTracker = new OTC('trackingId');
// Example 4 (shorthand):
const analyticsTracker = new window.OTC('trackingId');
// Example 5: Initiate class with disabled "auto" tracking
// With disabled "auto" tracking you need to use
// `.track()` method to track a "visit"
const analyticsTracker = new window.OTC('trackingId', false);
whenUserVisit(() => {
  analyticsTracker.track();
});

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:

// Various examples on tracking custom user's actions
analyticsTracker.pushEvent('userAction', 'login');
analyticsTracker.pushEvent('userAction', 'logout');
analyticsTracker.pushEvent('userAction', 'signup');

analyticsTracker.pushEvent('click', 'purchase');
analyticsTracker.pushEvent('click', 'purchase-left');
analyticsTracker.pushEvent('click', 'pricing - more info');

<script type="text/javascript">
  // make analyticsTracker global variable
  window.analyticsTracker = analyticsTracker;
</script>

<form>
  <h2>Buy Now</h2>
  <select>
    <option disabled>Select product</option>
    <option>Blue</option>
    <option>Red</option>
    <option>Green</option>
  </select>
  <input name="qty" />
  <!-- Example on tracking form submit -->
  <button type="submit" onClick="analyticsTracker.pushEvent('checkout', 'buy-now-form')">Checkout</button>
</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:

const Analytics = require('ostrio-analytics');
const analyticsTracker = new Analytics('trackingId', false);

// jQuery or any other similar case:
$(document).ready(() => {
  analyticsTracker.track();
});

`.onPushEvent()` method

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

Examples:

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

analyticsTracker.onPushEvent((key, value) => {
  console.log({ key, value });
  // OUTPUT:
  // { key: 'testKey', value: 'testValue' }
});

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

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

analyticsTracker.onTrack(() => {
  console.log('Tacking a session');
  // OUTPUT :
  // Tacking a session
});

// Callback will be executed on every browser navigation
// or upon calling `.track()` method
analyticsTracker.track();

Other examples

Deep router integration:

const Analytics = require('ostrio-analytics');
const analyticsTracker = new Analytics('trackingId', false);

/*!pseudo code!*/
router({
  '/'() {
    analyticsTracker.track();
  },
  '/two'() {
    analyticsTracker.track();
  },
  '/three'() {
    analyticsTracker.track();
  }
});

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.

const Analytics = require('ostrio-analytics');
const analyticsTracker = new Analytics('trackingId', false);

History.Adapter.bind(window, 'statechange', () => {
  analyticsTracker.track();
});

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:

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

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

analyticsTracker.onTrack(() => {
  // Track navigation with Google Analytics
  ga('send', {
    hitType: 'pageview',
    page: document.location.pathname,
    location: document.location.href,
    title: document.title
  });
});

analyticsTracker.onPushEvent((name, value) => {
  // Send events to Google Analytics
  ga('send', {
    hitType: 'event',
    eventCategory: name,
    eventAction: value
  });
});

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:

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

const Analytics = require('ostrio-analytics');
const analyticsTracker = new Analytics('trackingId', false);

analyticsTracker.onTrack(() => {
  // Track navigation with Google Analytics
  gtag('config', 'UA-XXXXXXXXX-X', {
    page_title: document.title,
    page_path: document.location.pathname,
    page_location: document.location.href
  });
});

_app.OstrioTracker.onPushEvent((name, value) => {
  // Send events to Google Analytics
  gtag('event', name, { value });
});

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.