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 = analytics = var app = ; // app middleware //app;app; // 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
.
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.
//id: contact //id: reach_point_0 Contact us //id: read_section_0 in exchange for your marbles
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 = ;server; app;
Example use with socket.io server:
var server = ;server; var io = ;// OR:var io = ; app;
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';