Eventflit HTTP Python Library

The Python library for interacting with the Eventflit HTTP API. This package lets you trigger events to your client and query the state of your Eventflit channels. When used with a server, you can validate Eventflit webhooks and authenticate private- or presence-channels.

In order to use this library, you need to have a free account on http://eventflit.com. After registering, you will need the application credentials for your app.

Features

• Python 2.6, 2.7 and 3.3 support
• Adapters for various http libraries like requests, urlfetch, aiohttp and tornado.
• WebHook validation
• Signature generation for socket subscriptions

Table of Contents

• Installation
• Getting started
• Configuration
• Triggering Events
• Push Notifications (BETA)
• Querying Application State
  • Getting Information For All Channels
  • Getting Information For A Specific Channel
  • Getting User Information For A Presence Channel
• Authenticating Channel Subscription
• Receiving Webhooks
• Request Library Configuration
  • Google App Engine
• Feature Support
• Running the tests
• License

Installation

You can install this module using your package management method or choice, normally easy_install or pip. For example:

pip install eventflit

Users on Python 2.x and older versions of pip may get a warning, due to pip compiling the optional eventflit.aiohttp module, which uses Python 3 syntax. However, as eventflit.aiohttp is not used by default, this does not affect the library's functionality. See our Github issue, as well as this issue from Gunicorn for more details.

Getting started

The minimum configuration required to use the Eventflit object are the three constructor arguments which identify your Eventflit app. You can find them by going to "API Keys" on your app at https://panel.eventflit.com.

from eventflit import Eventflit
eventflit = Eventflit(app_id=u'4', key=u'key', secret=u'secret', cluster=u'cluster')

You can then trigger events to channels. Channel and event names may only contain alphanumeric characters, - and _:

eventflit.trigger(u'a_channel', u'an_event', {u'some': u'data'})

Configuration

from eventflit import Eventflit
eventflit = Eventflit(app_id, key, secret, cluster=u'cluster')

The constructor will throw a TypeError if it is called with parameters that don’t match the types listed above.

Example

from eventflit import Eventflit
eventflit = Eventflit(app_id=u'4', key=u'key', secret=u'secret', ssl=True, cluster=u'cluster')

Triggering Events

To trigger an event on one or more channels, use the trigger method on the Eventflit object.

Eventflit::trigger

Eventflit::trigger will throw a TypeError if called with parameters of the wrong type; or a ValueError if called on more than 100 channels, with an event name longer than 200 characters, or with more than 10240 characters of data (post JSON serialisation).

Example

This call will trigger to 'a_channel' and 'another_channel', and exclude the recipient with socket_id "1234.12".

eventflit.trigger([u'a_channel', u'another_channel'], u'an_event', {u'some': u'data'}, "1234.12")

Eventflit::trigger_batch

It's also possible to send distinct messages in batches to limit the overhead of HTTP headers. There is a current limit of 10 events per batch on our multi-tenant clusters.

Events are a Dict with keys:

Eventflit::trigger_batch will throw a TypeError if the data parameter is not JSONable.

Example

eventflit.trigger_batch([
  { u'channel': u'a_channel', u'name': u'an_event', u'data': {u'some': u'data'}, u'socket_id': '1234.12'},
  { u'channel': u'a_channel', u'name': u'an_event', u'data': {u'some': u'other data'}}
])

Push Notifications (BETA)

Eventflit now allows sending native notifications to iOS and Android devices. Check out the documentation for information on how to set up push notifications on Android and iOS. There is no additional setup required to use it with this library. It works out of the box with the same Eventflit instance. All you need are the same eventflit credentials.

Sending native pushes

The native notifications API is hosted at push.eventflit.com and only accepts https requests.

You can send pushes by using the notify method, either globally or on the instance. The method takes two parameters:

• interests: An Array of strings which represents the interests your devices are subscribed to. These are akin to channels in the DDN with less of an ephemeral nature. Note that currently, you can only publish to, at most, ten interests.
• data: The content of the notification represented by a Hash. You must supply either the gcm or apns key. For a detailed list of the acceptable keys, take a look at the docs.

Example:

data = {
  'apns': {
    'priority': 5,
    'aps': {
      'alert': {
        'body': 'tada'
      }
    }
  }
}

eventflit.notify(["my-favourite-interest"], data)

Errors

Push notification requests, once submitted to the service are executed asynchronously. To make reporting errors easier, you can supply a webhook_url field in the body of the request. This will be used by the service to send a webhook to the supplied URL if there are errors.

For example:

data = {
  "apns": {
    "aps": {
      "alert": {
        "body": "hello"
      }
    }
  },
  'gcm': {
    'notification': {
      "title": "hello",
      "icon": "icon"
    }
  },
  "webhook_url": "http://yolo.com"
}

NOTE: This is currently a BETA feature and there might be minor bugs and issues. Changes to the API will be kept to a minimum, but changes are expected. If you come across any bugs or issues, please do get in touch via support or create an issue here.

Querying Application State

Getting Information For All Channels

Eventflit::channels_info

Eventflit::channels_info will throw a TypeError if prefix_filter is not a String.

Example

channels = eventflit.channels_info(u"presence-", [u'user_count'])

#=> {u'channels': {u'presence-chatroom': {u'user_count': 2}, u'presence-notifications': {u'user_count': 1}}}

Getting Information For A Specific Channel

Eventflit::channel_info

Eventflit::channel_info will throw a ValueError if channel is not a valid channel.

Example

channel = eventflit.channel_info(u'presence-chatroom', [u"user_count"])
#=> {u'user_count': 42, u'occupied': True}

Getting User Information For A Presence Channel

Eventflit::users_info

Eventflit::users_info will throw a ValueError if channel is not a valid channel.

Example

eventflit.users_info(u'presence-chatroom')
#=> {u'users': [{u'id': u'1035'}, {u'id': u'4821'}]}

Authenticating Channel Subscription

Eventflit::authenticate

In order for users to subscribe to a private- or presence-channel, they must be authenticated by your server.

The client will make a POST request to an endpoint (either "/eventflit/auth" or any which you specify) with a body consisting of the channel's name and socket_id.

Using your Eventflit instance, with which you initialized Eventflit, you can generate an authentication signature. Having responded to the request with this signature, the subscription will be authenticated.

Eventflit::authenticate will throw a ValueError if the channel or socket_id that it’s called with are invalid.

Example

Private Channels

auth = eventflit.authenticate(

  channel=u"private-channel",

  socket_id=u"1234.12"
)
# return `auth` as a response

Presence Channels

auth = eventflit.authenticate(

  channel=u"presence-channel",

  socket_id=u"1234.12",

  custom_data={
    u'user_id': u'1',
    u'user_info': {
      u'twitter': '@eventflit'
    }
  }
)
# return `auth` as a response

Receiving Webhooks

If you have webhooks set up to POST a payload to a specified endpoint, you may wish to validate that these are actually from Eventflit. The Eventflit object achieves this by checking the authentication signature in the request body using your application credentials.

Eventflit::validate_webhook

Eventflit::validate_webhook will raise a TypeError if it is called with any parameters of the wrong type.

Example

webhook = eventflit.validate_webhook(

  key="key_sent_in_header",

  signature="signature_sent_in_header",

  body="{ \"time_ms\": 1327078148132  \"events\": [ { \"name\": \"event_name\", \"some\": \"data\" }  ]}"
)

print webhook["events"]

Request Library Configuration

Users can configure the library to use different backends to send calls to our API. The HTTP libraries we support are:

• Requests (eventflit.requests.RequestsBackend). This is used by default.
• Tornado (eventflit.tornado.TornadoBackend).
• AsyncIO (eventflit.aiohttp.AsyncIOBackend).
• Google App Engine (eventflit.gae.GAEBackend).

Upon initializing a Eventflit instance, pass in any of these options to the backend keyword argument.

Google App Engine

GAE users are advised to use the eventflit.gae.GAEBackend backend to ensure compatbility.

Feature Support

Helper Functionality

These are helpers that have been implemented to to ensure interactions with the HTTP API only occur if they will not be rejected e.g. channel naming conventions.

Running the tests

To run the tests run python setup.py test

Making a release

• Update the CHANGELOG.md file. git changelog from the git-extras package can be useful to pull commits from the release.
• Update the setup.py version
• git tag v$VERSION
• git push && git push --tags
• make - publishes to pypi

If you get the error: invalid command 'bdist_wheel' message on the last step pip install wheel and re-run make.

License

Copyright (c) 2017 Eventflit Ltd. See LICENSE for details.