diff --git a/README.md b/README.md index 95c1431..ad9296f 100644 --- a/README.md +++ b/README.md @@ -48,22 +48,175 @@ You can then trigger events to channels. Channel and event names may only contain alphanumeric characters, `-` and `_`: ```python -pusher.trigger('a_channel', 'an_event', {'some': 'data'}) +pusher.trigger(u'a_channel', u'an_event', {u'some': u'data'}) +``` + +If you wish to trigger an event on multiple channels, pass in a list as the first parameter: + +```python +pusher.trigger([u'a_channel', u'another_channel'], u'an_event', {u'some': u'data'}) ``` You can also specify `socket_id` as a separate argument, as described in -: +. This will excluded the connection with that socket_id from receiving the event: + +```python +pusher.trigger(u'a_channel', u'an_event', {u'some': u'data'}, socket_id) +``` + +Querying Application State +----------------- + +### Getting Information For All Channels + + +#### `Pusher::channels_info` + +|Argument |Description | +|:-:|:-:| +|prefix_filter `String` |**Default: `None`**
Filter the channels returned by their prefix | +|attributes `Collection` | **Default: `[]`**
A collection of attributes which should be returned for each channel. If empty, an empty dictionary of attributes will be returned for each channel.
Available attributes: `"user_count"`. + +|Return Values |Description | +|:-:|:-:| +|channels `Dict` | A parsed response from the HTTP API. See example. | + +##### Example + +```python +channels = pusher.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 + +#### `Pusher::channel_info` + +|Argument |Description | +|:-:|:-:| +|channel `String` |**Required**
The name of the channel you wish to query| +|attributes `Collection` | **Default: `[]`**
A collection of attributes to be returned for the channel.

Available attributes:
`"user_count"` : Number of *distinct* users currently subscribed. **Applicable only to presence channels**.
`"subscription_count"`: [BETA]: Number of *connections* currently subscribed to the channel. Please [contact us](http://support.pusher.com) to enable this feature. + +|Return Values |Description | +|:-:|:-:| +|channel `Dict` | A parsed response from the HTTP API. See example. | + +##### Example + +```python +channel = pusher.channel_info(u'presence-chatroom', [u"user_count"]) +#=> {u'user_count': 42, u'occupied': True} +``` + +### Getting User Information For A Presence Channel + +#### `Pusher::users_info` + +|Argument |Description | +|:-:|:-:| +|channel `String` |**Required**
The name of the *presence* channel you wish to query | + +|Return Values |Description | +|:-:|:-:| +|users `Dict` | A parsed response from the HTTP API. See example. | + +##### Example + +```python +pusher.users_info(u'presence-chatroom') +#=> {u'users': [{u'id': u'1035'}, {u'id': u'4821'}]} +``` + +Authenticating Channel Subscription +----------------- + +#### `Config::authenticate_subscription` + +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 "/pusher/auth" or any which you specify) with a body consisting of the channel's name and socket_id. + +Using your `Config` instance, with which you initialized `Pusher`, you can generate an authentication signature. Having responded to the request with this signature, the subscription will be authenticated. + +|Argument |Description | +|:-:|:-:| +|channel `String` |**Required**
The name of the channel, sent to you in the POST request | +|socket_id `String` | **Required**
The channel's socket_id, also sent to you in the POST request | +|custom_data `Dict` |**Required for presence channels**
This will be a dictionary containing the data you want associated with a member of a presence channel. A `"user_id"` key is *required*, and you can optionally pass in a `"user_info"` key. See the example below. | + +|Return Values |Description | +|:-:|:-:| +|response `Dict` | A dictionary to send as a response to the authentication request.| + +##### Example + +###### Private Channels + +```python +config = pusher.config +auth = config.authenticate_subscription( + + channel=u"private-channel", + + socket_id=u"1234.12" +) +# return `auth` as a response +``` + +###### Presence Channels ```python -pusher.trigger('a_channel', 'an_event', {'some': 'data'}, socket_id) +config = pusher.config + +auth = config.authenticate_subscription( + + channel=u"presence-channel", + + socket_id=u"1234.12", + + custom_data={ + u'user_id': u'1', + u'user_info': { + u'twitter': '@pusher' + } + } +) +# return `auth` as a response ``` -### Additional options +Receiving Webhooks +----------------- -The Config and Pusher constructors supports more options. See the code -documentation to get all the details. +If you have webhooks set up to POST a payload to a specified endpoint, you may wish to validate that these are actually from Pusher. The `Config` object achieves this by checking the authentication signature in the request body using your application credentials. -TODO: Add link to code docs here +#### `Config::validate_webhook` + +|Argument |Description | +|:-:|:-:| +|key `String` | **Required**
Pass in the value sent in the request headers under the key "X-PUSHER-KEY". The method will check this matches your app key. | +|signature `String` | **Required**
This is the value in the request headers under the key "X-PUSHER-SIGNATURE". The method will verify that this is the result of signing the request body against your app secret. | +|body `String` | **Required**
The JSON string of the request body received. | + +|Return Values |Description | +|:-:|:-:| +|body_data `Dict` | If validation was successful, the return value will be the parsed payload. Otherwise, it will be `None`. | + +##### Example + +```python +webhook = pusher.config.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"] + +``` Running the tests ----------------- @@ -74,4 +227,3 @@ License ------- Copyright (c) 2014 Pusher Ltd. See LICENSE for details. -