Our SVP of Product & Engineering, Mike Herrick, recently had a blog post about creating a Connect Bot to see Connect events in Slack. Towards the end of his post, he asked for feature ideas, including advice on which chat systems to integrate with next. At a previous job, I had used the excellent Hubot framework to connect some LED lights I had to an IRC system so that my coworkers could change how the office looked without getting up or asking me to change them. One of the first things I did when I started at UA was to hook them up to our preferred mode of communication, Slack.

The lights themselves aren’t important. The important bit is that Hubot makes interacting via any chat system trivial. After seeing that fellow engineer Jesse Keane had released a beautiful node client for connect, I figured that I could write a Hubot plugin that would allow you to interact with your Connect stream via chat commands. So, I present to you:

How to Get an Urban Airship Connect Bot in 9 8 Easy Steps

For starters, you’ll need to have git, node and redis installed.

The Urban Airship Connect bot is simply a plugin for the Hubot framework. Part of what makes it excellent is that you can connect to Slack, Hipchat, IRC or any of these other adapters.

Step 0. Get Hubot

Follow the instructions on their docs page for getting started with Hubot.

Step 1. Get the Connect Plugin for Hubot

We’ll install the Connect plugin using node’s package manager, npm:

$ npm install hubot-urban-airship-connect --save

Then edit the external-scripts.json file and add “hubot-urban-airship-connect” to the array of external scripts. Here’s what your external-scripts.json file should look like:

[
  "hubot-diagnostics",
  "hubot-help",
  "hubot-heroku-keepalive",
  "hubot-redis-brain",
  "hubot-urban-airship-connect"
]

Step 2. Get an Urban Airship Connect Token

Obtain a Connect token using these instructions. (If you’re an Urban Airship customer, you may start a complimentary trial of Connect for 30 days.)

Step 3. Configure the Connect Plugin and Other Adapter Settings

Hubot strongly encourages storing your configuration in environment variables instead of your repo. Never put your Connect token (or any other credentials) directly into the source of your project. Read them out of the environment.

The Connect bot needs the following environment variables:

• UA_CONNECT_APPKEY  - The app key for the app you’re interested in observing

• UA_CONNECT_TOKEN - The (very secret) Connect token you obtained in step 2

• UA_CONNECT_ROOMS - A comma separated list of rooms you’d like your Connect bot to output the stream into

A handy pattern I’ve picked up for this is to create a .env file in your Hubot directory, and export the environment variables you’ll need. Then, source that file in your terminal so that Hubot can read the necessary configuration out of the environment.

Here’s my .env file, with sensitive stuff redacted:

export HUBOT_SLACK_TOKEN=<REDACTED>
export UA_CONNECT_TOKEN=<REDACTED>
export UA_CONNECT_APPKEY=<APP KEY>
export UA_CONNECT_ROOMS=#cnct-bot-test

You’ll note here that there’s an extra environment variable that I hadn’t mentioned before: HUBOT_SLACK_TOKEN. This is the environment variable that the Hubot Slack adapter requires for the bot to send information to Slack. Each adapter will require a different configuration variable to be set. Check the documentation for the adapter you’ve chosen.

Step 4. Turn the Thing On

From your Hubot directory, source the environment variables, then start the bot.

$ source .env
$ bin/hubot --adaptor slack

Step 5. Interact

Invite your bot to a room you’re in, if necessary (this step will vary by adapter used). In the room, type:

!current

The bot should respond with which Connect filters are applied, and then with how each event will be displayed.

Now try sending a targeted push to just your device. Check the Hubot logs if your message doesn’t show up in a few seconds.

You can also ask the bot directly for help and it’ll tell you available commands. You’ll see that my bot can both work the lights on my desk and interact with the Connect stream, and do various other things. You can install as many cool hubot plugins as you like.

Here’s an example of setting the connect filters to show only 30% of IOS opens and no other connect events:

Step 6. Important Caveats

If your app is popular at all, your Connect stream is likely to be way, way, way too much data to present in a Slack room. Slack will (rightfully) disconnect your bot if you exceed more than 1 message per second for any extended duration. In general, sending one message to Slack per event in your app is a Bad Idea™.

There’s a couple ways to approach this problem:

• You can configure the bot to use Connect’s subset feature. This command will configure the Connect stream to only send 10% of the events to the bot:

!set subset sample 0.1

And the following command will remove that subset setting from your filter:

!clear subset

See the Connect API docs for various filters you can apply to your Connect stream to limit the output to a reasonable amount

• Use the provided script as a starting point, and modify it to aggregate the events in some way helps you understand how your customers are using the app. Perhaps listen for a particular tag change, or count the number of opens per hour.

7. A Note about Configuration Persistence

The bot uses redis to store whatever you’ve configured, so you can restart the bot without losing your settings. This ends up being extraordinarily helpful while debugging your new custom bot. Restarting redis will lose your current configuration.

8. Deploying your Bot

Running the bot on your local machine is nice for local development, but if you want your bot to continue running when your computer is off, I highly recommend deploying to heroku. You can get a free tier machine that will be up for 18 hours/day. Their service is a delight, and I cannot recommend it highly enough.

Critical Next Steps

For help:

• File issues or ask questions on the Github page for this project

• Contact me directly on Twitter

To learn more about the advantages that Connect can provide for your mobile analytics efforts, please contact us. And special thanks to Jesse Keane and Andrew Winterman for their contributions to this project.