ac-koa-hipchat-keenio/README.md

Simple Keen.io-based analytics capture for AC Koa HipChat

# What is this?

This is a simple Keen.io analytics wrapper for
[ac-koa-hipchat](https://bitbucket.org/atlassianlabs/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](https://github.com/keenlabs/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});
```