What is this?

This is a simple Keen.io analytics wrapper for ac-koa-hipchat (ack) add-on projects. It lets you easily track standard ack webhook events, as well as capture custom events through a common interface.

This uses KeenClient-Node under the hood, though it is not meant to be a general-purpose wrapper for Keen.io -- if you need the full power of the Keen.io client, please use KeenClient-Node directly instead.

How do I set it up?

First, add it to your project like so:

$ npm install --save ac-koa-hipchat-keenio

For this module to work, you will need the following environment variables to be set, at a minimum: KEEN_PROJECT_ID and KEEN_WRITE_KEY. The optional environment variable LOG_ANALYTICS can be set to true to also add analytics logging to the target addon object's logger. If none of these variables are set, calls to the analytics module simply no-op.

How do I use it?

Usage in an ac-koa-hipchat app is simple -- just require and initialize in a typical app as follows:

// require this package
var analytics = require('ac-koa-hipchat-keenio');

// standard ac-koa-hipchat addon setup
var ack = require('ac-koa').require('hipchat');
var pkg = require('./package.json');
var app = ack(pkg);

var addon = app.addon()
  .hipchat()
  .allowRoom(true)
  .scopes('send_notification', 'view_group');

// create a tracker object for the given addon
var tracker = analytics.track(addon);

That much alone will start tracking analytics events for these standard addon webhooks:

• install
• uninstall
• room_enter
• room_exit
• room_message
• room_notification
• room_topic_change

If you'd like to use this module to capture additional data using the same keen.io client, the tracker object also exposes a basic capture method for doing so:

  // capture accepts an event name and an optional, JSON-compatible data object
  tracker.capture('email-received', {to: toAddress, from: fromAddress});