Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/yeoman/insight

Node.js module to help you understand how your tool is being used by anonymously reporting usage metrics to Google Analytics
https://github.com/yeoman/insight

Last synced: 12 days ago
JSON representation

Node.js module to help you understand how your tool is being used by anonymously reporting usage metrics to Google Analytics

Host: GitHub
URL: https://github.com/yeoman/insight
Owner: yeoman
License: bsd-2-clause
Created: 2012-12-12T21:05:21.000Z (almost 12 years ago)
Default Branch: main
Last Pushed: 2023-01-27T16:13:11.000Z (almost 2 years ago)
Last Synced: 2024-09-17T06:12:53.354Z (about 2 months ago)
Language: JavaScript
Size: 417 KB
Stars: 557
Watchers: 26
Forks: 53
Open Issues: 17
Metadata Files:
- Readme: readme.md
- Contributing: contributing.md
- License: license

Awesome Lists containing this project

awesome-nodejs-cn - insight - 使用 metrics 向 Google Analytics 发送匿名报告来帮助你理解你的工具是怎样被使用的 (包 / 命令行工具)
awesome-github-star - insight
awesome-nodejs - insight - Helps you understand how your tool is being used by anonymously reporting usage metrics to Google Analytics. (Packages / Command-line utilities)
awesome-nodejs - insight - Node.js module to help you understand how your tool is being used by anonymously reporting usage metrics to Google Analytics - ★ 437 (Command-line utilities)
awesome-node - insight - Helps you understand how your tool is being used by anonymously reporting usage metrics to Google Analytics. (Packages / Command-line utilities)
awesome-nodejs-cn - insight - 通过向Google Analytics（分析）匿名报告使用情况指标来帮助您了解工具的使用情况. (目录 / 命令行工具)
awesome-nodejs-cn - insight - **star:555** 帮助了解匿名向Google Analytics报告使用指标时如何使用您的工具 (包 / 命令行实用工具)

README

        # Insight [![Build Status](https://secure.travis-ci.org/yeoman/insight.svg?branch=master)](https://travis-ci.org/yeoman/insight)

> Understand how your tool is being used by anonymously reporting usage metrics to [Google Analytics](https://www.google.com/analytics/) or [Yandex.Metrica](https://metrica.yandex.com)

## Install

```

$ npm install insight

```

## Access data / generate dashboards

### Google Analytics (GA)

- Use [Embed API](https://developers.google.com/analytics/devguides/reporting/embed/v1/) to embed charts

- Use [Core Reporting API](https://developers.google.com/analytics/devguides/reporting/core/v3/) or [Real Time Reporting API](https://developers.google.com/analytics/devguides/reporting/realtime/v3/) to access raw data, then build custom visualization, e.g. [metrics from Bower](https://bower.io/stats/)

- Use GA's dashboards directly, e.g. metrics from [Yeoman](https://yeoman.io):

![analytics screenshot](screenshot-ga-dashboard.png)

## 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](https://developers.google.com/analytics/devguides/collection/protocol/v1/).

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.

![GA custom dimensions screenshot](screenshot-ga-custom-dimensions.png)

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

```js

const Insight = require('insight');

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

const insight = new Insight({

	// Google Analytics tracking code

	trackingCode: 'UA-XXXXXXXX-X',

	pkg

});

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

```js

const Insight = require('insight');

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

const insight = new Insight({

	// Yandex.Metrica counter id

	trackingCode: 'XXXXXXXXX'

	trackingProvider: 'yandex',

	pkg

});

// Ask for permission the first time

if (insight.optOut === undefined) {

	insight.askPermission();

}

insight.track('foo', 'bar');

// Recorded in Yandex.Metrica as `http://.insight/foo/bar`

```

## API

### Insight(options)

#### trackingCode

**Required**\

Type: `string`

Your Google Analytics [trackingCode](https://support.google.com/analytics/bin/answer.py?hl=en&answer=1008080) or Yandex.Metrica [counter id](https://help.yandex.com/metrika/?id=1121963).

#### 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`](https://github.com/sindresorhus/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](https://developers.google.com/analytics/devguides/collection/analyticsjs/events) documentation via the options object. Note: Does not work with Yandex.Metrica.

```js

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

![askPermission screenshot](screenshot-askpermission.png)

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.