insight

What is insight?

The 'insight' npm package is used for tracking and reporting anonymous usage metrics for your Node.js applications. It helps developers understand how their tools are being used by collecting data such as command usage, version information, and other relevant metrics.

What are insight's main functionalities?

Tracking Usage

This feature allows you to track usage events in your application. The code sample demonstrates how to initialize the Insight instance, ask for user permission, and track an event.

const Insight = require('insight');
const pkg = require('./package.json');

const insight = new Insight({
  trackingCode: 'UA-000000-01',
  pkg
});

// Ask for permission the first time
if (insight.optOut === undefined) {
  insight.askPermission();
}

// Track an event
insight.track('event', 'category', 'action', 'label', 'value');

Opt-in/Opt-out Management

This feature allows you to manage user consent for tracking. The code sample shows how to check if the user has opted out of tracking.

const Insight = require('insight');
const pkg = require('./package.json');

const insight = new Insight({
  trackingCode: 'UA-000000-01',
  pkg
});

// Check if the user has opted out
if (insight.optOut) {
  console.log('User has opted out of tracking');
} else {
  console.log('User has opted in to tracking');
}

Custom Event Tracking

This feature allows you to track custom events specific to your application. The code sample demonstrates how to track a custom event with specific parameters.

const Insight = require('insight');
const pkg = require('./package.json');

const insight = new Insight({
  trackingCode: 'UA-000000-01',
  pkg
});

// Track a custom event
insight.track('customEvent', 'customCategory', 'customAction', 'customLabel', 'customValue');

Other packages similar to insight

analytics-node

The 'analytics-node' package is a client for Segment's analytics service. It allows you to track events and send them to various analytics services. Compared to 'insight', 'analytics-node' offers more integrations and is part of a larger analytics ecosystem.

universal-analytics

The 'universal-analytics' package is a Node.js module for Google's Universal Analytics. It allows you to send data to Google Analytics from your server-side applications. Unlike 'insight', which is more focused on anonymous usage tracking, 'universal-analytics' is specifically designed for Google Analytics.

mixpanel

The 'mixpanel' package is a client for Mixpanel's analytics service. It provides robust event tracking and user analytics capabilities. Compared to 'insight', 'mixpanel' offers more advanced features like user segmentation and funnel analysis.

README

Insight

Understand how your tool is being used by anonymously reporting usage metrics to Google Analytics or Yandex.Metrica

This package is in maintenance mode. No new features will be added.

Install

npm install insight

Access data / generate dashboards

Google Analytics (GA)

• Use Embed API to embed charts
• Use Core Reporting API or Real Time Reporting API to access raw data, then build custom visualization, e.g. metrics from Bower
• Use GA's dashboards directly, e.g. metrics from Yeoman:

Provider Setup

Google Analytics (GA)

Currently, Insight should be used with GA set up as web tracking due to use of URLs. Future plans include refactoring to work with GA set up for app-based tracking and the Measurement Protocol.

For debugging, Insight can track OS version, Node.js version, and version of the app that implements Insight. Please set up custom dimensions per below screenshot. This is a temporary solution until Insight is refactored into app-based tracking.

Collected Data

Insight cares deeply about the security of your user's data and strives to be fully transparent with what it tracks. All data is sent via HTTPS secure connections. Insight provides API to offer an easy way for users to opt-out at any time.

Below is what Insight is capable of tracking. Individual implementation can choose to not track some items.

• The version of the module that implements Insight
• Module commands/events (e.g. install / search)
• Name and version of packages involved with command used
• Version of node.js & OS for developer debugging
• A random & absolutely anonymous ID

Usage

Google Analytics

import Insight from 'insight';
import packageJson from './package.json' with {type: 'json'};

const insight = new Insight({
	// Google Analytics tracking code
	trackingCode: 'UA-XXXXXXXX-X',
	pkg: packageJson
});

// Ask for permission the first time
if (insight.optOut === undefined) {
	insight.askPermission();
}

insight.track('foo', 'bar');
// Recorded in Analytics as `/foo/bar`

insight.trackEvent({
	category: 'eventCategory',
	action: 'eventAction',
	label: 'eventLabel',
	value: 'eventValue'
});
// Recorded in Analytics behavior/events section

Yandex.Metrica

import Insight from 'insight';
import packageJson from './package.json' with {type: 'json'};

const insight = new Insight({
	// Yandex.Metrica counter id
	trackingCode: 'XXXXXXXXX'
	trackingProvider: 'yandex',
	pkg: packageJson
});

// Ask for permission the first time
if (insight.optOut === undefined) {
	insight.askPermission();
}

insight.track('foo', 'bar');
// Recorded in Yandex.Metrica as `http://<package-name>.insight/foo/bar`

API

Insight(options)

trackingCode

Required
Type: string

Your Google Analytics trackingCode or Yandex.Metrica counter id.

trackingProvider

Type: string
Default: 'google'
Values: 'google' | 'yandex'

Tracking provider to use.

pkg

Type: object

name

Required
Type: string

version

Type: string
Default: 'undefined'

config

Type: object
Default: An instance of conf

If you want to use your own configuration mechanism instead of the default conf-based one, you can provide an object that has to implement two synchronous methods:

• get(key)
• set(key, value)

Instance methods

.track(keyword, ...keyword?)

Accepts keywords which ends up as a path in Analytics.

.track('init', 'backbone') becomes /init/backbone

.trackEvent(options)

Accepts event category, action, label and value as described in the GA event tracking documentation via the options object. Note: Does not work with Yandex.Metrica.

.trackEvent({
	category: 'download',
	action: 'image',
	label: 'logo-image'
});

category

Required
Type: string

Event category: Typically the object that was interacted with (e.g. 'Video').

action

Required
Type: string

Event action: The type of interaction (e.g. 'play').

label

Type: string

Event label: Useful for categorizing events (e.g. 'Fall Campaign').

value

Type: integer

Event value: A numeric value associated with the event (e.g. 42).

.askPermission(message?)

Asks the user permission to opt-in to tracking and sets the optOut property in config. You can also choose to set optOut property in config manually.

Optionally supply your own message. If message is null, default message will be used. This also resolves with the new value of optIn when the prompt is done and is useful for when you want to continue the execution while the prompt is running.

.optOut

Returns a boolean whether the user has opted out of tracking. Should preferably only be set by a user action, eg. a prompt.