urban-airship-connect
A node library for Airship's Real Time Data Streaming (formerly 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'})
API
connect(appKey, authToken[, options]) -> duplexStream
-
appKey
is your Airship app key -
authToken
is your RTDS auth token -
options
is an optional object accepting parameters:-
uri
to specify the URI to a running RTDS instance -
parser
to specify a custom JSON parser of signature:parse(String) -> Object
; defaults toJSON.parse
-
The returned duplex stream reads and writes plain JavaScript objects. Writes are posted to RTDS (Real Time Data Streaming), and the responding events are emitted as plain JavaScript objects over time.
Notes
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 Airship's Real Time Data Streaming 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
connectStream
// pull out just the `offset` property
.pipe(lookupStream('offset'))
// write it to `last_offset.txt`
.pipe(writeFile('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 RTDS to start streaming events
connectStream.write(filters)
Notes
-
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 ofconnectStream
and persist theoffset
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
RTDS setup, not for anything "mission-critical".
Usage
ua-connect <app-key> <token> [options]
Where options are:
-
--uri <uri>
Use a custom uri for RTDS -
--offset <offset>
Start at<offset>
-
--earliest
Start at earliest offset -
--key <app-key>
Explicitly set app key -
--token <token>
Explicitly set token
License
Apache-2.0