Skip to content
A node client for connecting to the Urban Airship Connect API.
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Type Name Latest commit message Commit time
Failed to load latest commit information.


Build Status npm install npm version License

A node library for Urban Airship's Connect

Example Usage

var connect = require('urban-airship-connect')

var connectStream = connect('appKey', 'authToken')

connectStream.on('data', function (data) {
  // will be called with each event

// write to the stream to set filters/offset/start
connectStream.write({start: 'LATEST'})


connect(appKey, authToken[, options]) -> duplexStream

  • appKey is your Urban Airship app key
  • authToken is your Connect auth token
  • options is an optional object accepting parameters:
    • uri to specify the URI to a running Connect instance
    • parser to specify a custom JSON parser of signature: parse(String) -> Object; defaults to JSON.parse

The returned duplex stream reads and writes plain JavaScript objects. Writes are posted to Connect, and the responding events are emitted as plain JavaScript objects over time.


If an error is encountered during a request, a bad status code is encountered, or JSON parsing of an event fails, an 'error' event will be emitted with the error attached. For JSON parse errors, the blob that caused the error will be available as the blob property of the error.

It is possible for a Custom Event value to be a number that cannot be parsed by JavaScript see docs. If you suspect you might encounter this issue, you may want to provide your own JSON parser, see API.

This module will handle connecting and maintaining a connection to Urban Airship's Connect service. If its connection is ever severed, it will do its best to resume at the last seen offset.

The resume_offset is not stored externally, so if the process using this module is killed, crashes, or otherwise exits it will be lost. In general it is advisable to track this offset yourself.

Writing offset to disk

var fs = require('fs')

var connect = require('urban-airship-connect')
var lookupStream = require('dotpath-stream')
var writeFile = require('file-replace-stream')

var connectStream = connect('appKey', 'authToken')
var filters = {}

// set up our pipeline for saving offsets
  // pull out just the `offset` property
  // write it to `last_offset.txt`

try {
  // try to read our offset file
  filters.resume_offset = fs.readFileSync('last_offset.txt', {encoding: 'utf8'})
} catch (err) {
  // fall back to starting at latest offset
  filters.start = 'LATEST'

// write the filters to Connect to start streaming events


  • writeFile could be swapped out for any writable stream for persistence.
  • If streams aren't your thing, you could alternatively listen to the data event of connectStream and persist the offset property from the passed event however you please.

Command-line Interface

A simple command-line utility ua-connect is bundled along with this module. It should be mostly used for testing your credentials or other aspects of your Connect setup, not for anything "mission-critical".


ua-connect <app-key> <token> [options]

Where options are:

  • --uri <uri> Use a custom uri for Connect
  • --offset <offset> Start at <offset>
  • --earliest Start at earliest offset
  • --key <app-key> Explicitly set app key
  • --token <token> Explicitly set token



You can’t perform that action at this time.