#node-analytics

node-analytics is an ExpressJS visitor analytic middleware.

Installation

$ npm install --save node-analytics

Prerequisites

Complete node-analytics functionality relies upon the following:

• MongoDB: a mongod instance must be running on the server for data storage
• a MaxMind GeoIP database for location data; the free GeoLite2 City database is available here
• an open WebSocket for client behaviour data collection; ensure port is open (default is 8080) or pass in server object

Though it will function without one, some, or all of the above.

Basic usage

app.js

In its current iteration node-analytics will process every server request, including static files. To restrict it to page loads call the middleware after the express.static middleware.

var express = require('express')
,   analytics = require('node-analytics')

var app = express();

// app middleware //
app.use(express.static(path.join(__dirname, 'public')));
app.use(analytics());   // beneath express.static

Client

The client script node-analytics-client.js must be included on the served webpage beneath the socket.io client script. Specify the client JS directory client_dir as an option and the file will be automatically copied, or disable this behaviour by client_copy: false.

<script type='text/javascript' src="https://cdn.socket.io/socket.io-1.4.5.js"></script>
<script type='text/javascript' src='/path/to/node-analytics-client.js'></script>

User behaviour

On the client side, node-analytics logs clicks, reaches, and reads of elements, each assigned their own class:

Event | Logged when element | Element class | Note --- | --- | --- | --- click | clicked (e.g. link) | na_click | Emits for every click reach | scrolled to | na_reach | Emits once per page load read | paused at and, presumptively, read | na_read | Tallies time spent paused within element bounds

Events will be associated with an element's id property, or will otherwise be assigned an index.

<section id="contact" class="na_read">      //id: contact
  
  <a href="mailto:me" class="na_click">     //id: reach_point_0
    Contact us
  </a>
  
  <span="fine_print" class="na_reach">      //id: read_section_0
    in exchange for your marbles
  </span>
  
</section>

Options

node-analytics may be adapted by the following options:

app.js

Key | Description | Default --- | --- | --- db_host | MongoDB host | 'localhost' db_port | MongoDB port | 27017 db_name | MongoDB database name | 'node_analytics_db' ws_port | WebSocket port; disabled if ws_server or s_io is set | 8080 ws_server | Express server object; disabled if s_io is set | null s_io | socket.io server object | null geo_ip | Use GeoIP boolean | true mmdb | MaxMind DB path | 'GeoLite2-City.mmdb' log | Output log boolean | true error_log | Error log boolean | true secure | Cookies: HTTPS only boolean | true secret | Cookies: AES encryption key | 'changeMe'

Example use with WebSocket server instead of port (see necessary client edit below):

var server = require('http').createServer(app);
server.listen(80);

app.use(analytics({
  ws_server:  server
}));

Example use with socket.io server:

var server = require('http').createServer(app);
server.listen(80);

var io = require('socket.io').listen(server);
// OR:
var io = require('socket.io').listen(8080);

app.use(analytics({
  s_io: io
}));

Client

Key | Description | Default --- | --- | --- ws_host | Websocket host | location.hostname ws_port | Websocket port; disable if using ws_server or s_io in app.js | 8080 click_class | Click-log class | 'na_click' reach_class | Reach-log class | 'na_reach' read_class | Read-log class | 'na_read' force_protocol | Force 'http' or 'https' socket connection | null

Example use including server support (editing node-analytics-client.js):

var na_obj = {
    ws_port:        null          // must be disabled if server object is being used
  , click_class:    'clicked_me'
  , reach_class:    'reached_me'
  , read_class:     'read_me'
};