ostrio:analytics

v1.2.8Published 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.

Why ostr.io analytics?:

  • 👐 Open Source tracking code;
  • 🚀 Lightweight, less than 2.5KB;
  • 😎 No DOM changes;
  • 😎 No heavy CPU tasks;
  • 😎 No extra scripts loading;
  • 🤝 Support for History API (HTML5 History Management);
  • 🤝 Support most of JavaScript front-end based frameworks and routings;
  • 📈🚀 Fast, all metrics are available in real-time;
  • ⚡️ 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:

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 see "Installation" section above;
  • 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:

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

Meteor via NPM:

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

NPM (CommonJS/RequireJS/Module):

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

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});

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});

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.