RTDS Python Library

Resources

• Github Repo 
• Python Package Index (PyPI) 
• RTDS API Reference

Installation

Install using pip:

pip install uaconnect

Usage

The following sections describe various usage information for the Real-Time Data StreamingA service that delivers engagement events in real time via the Data Streaming API or an Airship partner integration. (RTDS) API.

RTDS Event Consumer

To consume standard events from the RTDS API, instantiate an EventConsumer object with the application key, access token, and an offset recorder. You can then open the connection and start reading events.

>>> import uaconnect
>>> consumer = uaconnect.EventConsumer(
...     app_key='application_key',
...     access_token='access_token',
...     recorder=uaconnect.FileRecorder('.offset'))
>>> consumer.connect()
>>> for event in consumer.read():
...     if event is None:
...        continue
>>>     print("Got event: {}".format(event))
>>>     consumer.ack(event)

RTDS Compliance Event Consumer

To consume compliance events from the RTDS API, instantiate a ComplianceConsumer object with the application key, master secret and an offset recorder. You can then open the connection and start reading events.

 >>> import uaconnect
 >>> consumer = uaconnect.EventConsumer(
...     app_key='application_key',
...     master_secret='master_secret',
...     recorder=uaconnect.FileRecorder('.offset'))
>>> consumer.connect()
>>> for event in consumer.read():
...     if event is None:
...        continue
>>>     print("Got event: {}".format(event))
 >>>     consumer.ack(event)

Alternate Data Center Support

When instantiating an EventConsumer or ComplianceConsumer, you can pass the optional url argument to explicitly specify the data center your project is located in. Possible values are US, EU, or an arbitrary base URL in the form of http://domain.xyz/. The library will build the URL path properly from there. If no url is specified, US is used.

>>> import uaconnect
>>> consumer = uaconnect.EventConsumer(
...     app_key='application_key',
...     master_secret='master_secret',
...     url='EU',
...     recorder=uaconnect.FileRecorder('.offset'))

Offset Recorders

Offset recorders inherit from the abstract base class uaconnect.Recorder, implementing read_offset and write_offset methods. One recorder is included in the library, FileRecorder, which stores the offset on disk. In the uaconnect.ext.redisrecorder package there is an example implementation of using a Redis instance to store the offset.

ack calls should be placed depending on whether in a failure scenario your app wishes to possibly replay an already handled event or risk dropping one. For the latter, call ack as soon as the event is read. For the former, call ack only after the event has been fully handled.

Advanced Options When Connecting

Airship Real-Time Data Streaming supports a variety of options when connecting to make sure that you’re only consuming the data that you want. uaconnect makes it easy to use these connection parameters and filters.

Specifying Offsets

One of the advantages of RTDS is that you can resume from a specific place in the stream. This is done by specifying the offset that’s associated with the event. While uaconnect automatically tracks offsets for you with uaconnect.FileRecorder, you can also explicitly set an offset.

>>> import uaconnect
>>> recorder = uaconnect.FileRecorder(".offset") # or wherever you would like the file to exist
>>> recorder.write_offset("8865499359") # a randomly chosen offset
>>> recorder.read_offset()
'8865499359'

An alternative here is to just write the offset explicitly into the file or whatever Recorder subclass you’re using to track offsets.

cat .offset
886549935

Now, the next time you connect, it will pick up from that last offset.

If you’d like to manually set the offset for a connection to a known value instead of the recorder’s offset, set resume_offset like so:

>>> consumer.connect(resume_offset='123456789')

Using filters

Filters are a powerful way of filtering what specific information you’d like to see from the RTDS stream. You can filter by event type, device type, latency on an event, or even specific devices or notifications.

Here’s a brief example on how to use filters with uaconnect:

>>> import uaconnect
>>> consumer = uaconnect.EventConsumer(
...     app_key='application_key',
...     access_token='access_token',
...     recorder=uaconnect.FileRecorder('.offset')
...     )
>>> f = uaconnect.Filter()
>>> f.types("PUSH_BODY", "SEND") # only receive PUSH_BODY and SEND events.
>>> consumer.add_filter(f)
>>> consumer.connect()