ostrio:analytics

v1.3.1Published 5 years ago

This package has not had recent updates. Please investigate it's current state before committing to using it in your project.

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.

ToC:

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.