Skip to content

Commit 36146e5

Browse files
jpatel531jpatel531
committed
Merge pull request #42 from pusher/adding_more_documentation_to_readme
Added more documentation to readme
2 parents 5d3248d + 02e5f69 commit 36146e5

File tree

1 file changed

+160
-8
lines changed

1 file changed

+160
-8
lines changed

‎README.md‎

Lines changed: 160 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -48,22 +48,175 @@ You can then trigger events to channels. Channel and event names may only
4848
contain alphanumeric characters, `-` and `_`:
4949

5050
```python
51-
pusher.trigger('a_channel', 'an_event', {'some': 'data'})
51+
pusher.trigger(u'a_channel', u'an_event', {u'some': u'data'})
52+
```
53+
54+
If you wish to trigger an event on multiple channels, pass in a list as the first parameter:
55+
56+
```python
57+
pusher.trigger([u'a_channel', u'another_channel'], u'an_event', {u'some': u'data'})
5258
```
5359

5460
You can also specify `socket_id` as a separate argument, as described in
55-
<http://pusher.com/docs/duplicates>:
61+
<http://pusher.com/docs/duplicates>. This will excluded the connection with that socket_id from receiving the event:
62+
63+
```python
64+
pusher.trigger(u'a_channel', u'an_event', {u'some': u'data'}, socket_id)
65+
```
66+
67+
Querying Application State
68+
-----------------
69+
70+
### Getting Information For All Channels
71+
72+
73+
#### `Pusher::channels_info`
74+
75+
|Argument |Description |
76+
|:-:|:-:|
77+
|prefix_filter `String` |**Default: `None`** <br> Filter the channels returned by their prefix |
78+
|attributes `Collection` | **Default: `[]`** <br> A collection of attributes which should be returned for each channel. If empty, an empty dictionary of attributes will be returned for each channel. <br> Available attributes: `"user_count"`.
79+
80+
|Return Values |Description |
81+
|:-:|:-:|
82+
|channels `Dict` | A parsed response from the HTTP API. See example. |
83+
84+
##### Example
85+
86+
```python
87+
channels = pusher.channels_info(u"presence-", [u'user_count'])
88+
89+
#=> {u'channels': {u'presence-chatroom': {u'user_count': 2}, u'presence-notifications': {u'user_count': 1}}}
90+
```
91+
92+
### Getting Information For A Specific Channel
93+
94+
#### `Pusher::channel_info`
95+
96+
|Argument |Description |
97+
|:-:|:-:|
98+
|channel `String` |**Required** <br> The name of the channel you wish to query|
99+
|attributes `Collection` | **Default: `[]`** <br> A collection of attributes to be returned for the channel. <br><br> Available attributes: <br> `"user_count"` : Number of *distinct* users currently subscribed. **Applicable only to presence channels**. <br> `"subscription_count"`: [BETA]: Number of *connections* currently subscribed to the channel. Please [contact us](http://support.pusher.com) to enable this feature.
100+
101+
|Return Values |Description |
102+
|:-:|:-:|
103+
|channel `Dict` | A parsed response from the HTTP API. See example. |
104+
105+
##### Example
106+
107+
```python
108+
channel = pusher.channel_info(u'presence-chatroom', [u"user_count"])
109+
#=> {u'user_count': 42, u'occupied': True}
110+
```
111+
112+
### Getting User Information For A Presence Channel
113+
114+
#### `Pusher::users_info`
115+
116+
|Argument |Description |
117+
|:-:|:-:|
118+
|channel `String` |**Required** <br> The name of the *presence* channel you wish to query |
119+
120+
|Return Values |Description |
121+
|:-:|:-:|
122+
|users `Dict` | A parsed response from the HTTP API. See example. |
123+
124+
##### Example
125+
126+
```python
127+
pusher.users_info(u'presence-chatroom')
128+
#=> {u'users': [{u'id': u'1035'}, {u'id': u'4821'}]}
129+
```
130+
131+
Authenticating Channel Subscription
132+
-----------------
133+
134+
#### `Config::authenticate_subscription`
135+
136+
In order for users to subscribe to a private- or presence-channel, they must be authenticated by your server.
137+
138+
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.
139+
140+
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.
141+
142+
|Argument |Description |
143+
|:-:|:-:|
144+
|channel `String` |**Required**<br> The name of the channel, sent to you in the POST request |
145+
|socket_id `String` | **Required**<br> The channel's socket_id, also sent to you in the POST request |
146+
|custom_data `Dict` |**Required for presence channels** <br> 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. |
147+
148+
|Return Values |Description |
149+
|:-:|:-:|
150+
|response `Dict` | A dictionary to send as a response to the authentication request.|
151+
152+
##### Example
153+
154+
###### Private Channels
155+
156+
```python
157+
config = pusher.config
158+
auth = config.authenticate_subscription(
159+
160+
channel=u"private-channel",
161+
162+
socket_id=u"1234.12"
163+
)
164+
# return `auth` as a response
165+
```
166+
167+
###### Presence Channels
56168

57169
```python
58-
pusher.trigger('a_channel', 'an_event', {'some': 'data'}, socket_id)
170+
config = pusher.config
171+
172+
auth = config.authenticate_subscription(
173+
174+
channel=u"presence-channel",
175+
176+
socket_id=u"1234.12",
177+
178+
custom_data={
179+
u'user_id': u'1',
180+
u'user_info': {
181+
u'twitter': '@pusher'
182+
}
183+
}
184+
)
185+
# return `auth` as a response
59186
```
60187

61-
### Additional options
188+
Receiving Webhooks
189+
-----------------
62190

63-
The Config and Pusher constructors supports more options. See the code
64-
documentation to get all the details.
191+
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.
65192

66-
TODO: Add link to code docs here
193+
#### `Config::validate_webhook`
194+
195+
|Argument |Description |
196+
|:-:|:-:|
197+
|key `String` | **Required**<br>Pass in the value sent in the request headers under the key "X-PUSHER-KEY". The method will check this matches your app key. |
198+
|signature `String` | **Required**<br>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. |
199+
|body `String` | **Required**<br>The JSON string of the request body received. |
200+
201+
|Return Values |Description |
202+
|:-:|:-:|
203+
|body_data `Dict` | If validation was successful, the return value will be the parsed payload. Otherwise, it will be `None`. |
204+
205+
##### Example
206+
207+
```python
208+
webhook = pusher.config.validate_webhook(
209+
210+
key="key_sent_in_header",
211+
212+
signature="signature_sent_in_header",
213+
214+
body="{ \"time_ms\": 1327078148132 \"events\": [ { \"name\": \"event_name\", \"some\": \"data\" } ]}"
215+
)
216+
217+
print webhook["events"]
218+
219+
```
67220

68221
Running the tests
69222
-----------------
@@ -74,4 +227,3 @@ License
74227
-------
75228

76229
Copyright (c) 2014 Pusher Ltd. See LICENSE for details.
77-

0 commit comments

Comments
 (0)