Skip to content

Commit 0997e46

Browse files
jpatel531jpatel531
committed
Added more documentation to readme
1 parent 218f299 commit 0997e46

File tree

1 file changed

+154
-8
lines changed

1 file changed

+154
-8
lines changed

‎README.md‎

Lines changed: 154 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -48,22 +48,169 @@ 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'})
5252
```
5353

5454
You can also specify `socket_id` as a separate argument, as described in
55-
<http://pusher.com/docs/duplicates>:
55+
<http://pusher.com/docs/duplicates>. This will excluded the connection with that socket_id from receiving the event:
5656

5757
```python
58-
pusher.trigger('a_channel', 'an_event', {'some': 'data'}, socket_id)
58+
pusher.trigger(u'a_channel', u'an_event', {u'some': u'data'}, socket_id)
5959
```
6060

61-
### Additional options
61+
Querying Application State
62+
-----------------
63+
64+
### Getting Information For All Channels
65+
66+
67+
#### `Pusher::channels_info`
68+
69+
|Argument |Description |
70+
|:-:|:-:|
71+
|prefix_filter `String` |**Default: `None`** <br> Filter the channels returned by their prefix |
72+
|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"`.
73+
74+
|Return Values |Description |
75+
|:-:|:-:|
76+
|channels `Dict` | A parsed response from the HTTP API. See example. |
77+
78+
##### Example
79+
80+
```python
81+
channels = pusher.channels_info(u"presence-", [u"user_count"])
82+
83+
#=> {u'channels': {u'presence-chatroom': {u'user_count': 2}, u'presence-notifications': {u'user_count': 1}}}
84+
```
85+
86+
### Getting Information For A Specific Channel
87+
88+
#### `Pusher::channel_info`
89+
90+
|Argument |Description |
91+
|:-:|:-:|
92+
|channel `String` |**Required** <br> The name of the channel you wish to query|
93+
|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.
94+
95+
|Return Values |Description |
96+
|:-:|:-:|
97+
|channel `Dict` | A parsed response from the HTTP API. See example. |
98+
99+
##### Example
100+
101+
```python
102+
channel = pusher.channel_info(u'presence-chatroom', [u"user_count"])
103+
#=> {u'user_count': 42, u'occupied': True}
104+
```
105+
106+
### Getting User Information For A Presence Channel
107+
108+
#### `Pusher::users_info`
109+
110+
|Argument |Description |
111+
|:-:|:-:|
112+
|channel `String` |**Required** <br> The name of the *presence* channel you wish to query |
113+
114+
|Return Values |Description |
115+
|:-:|:-:|
116+
|users `Dict` | A parsed response from the HTTP API. See example. |
117+
118+
##### Example
119+
120+
```python
121+
pusher.users_info(u'presence-chatroom')
122+
#=> {u'users': [{u'id': u'1035'}, {u'id': u'4821'}]}
123+
```
124+
125+
Authenticating Channel Subscription
126+
-----------------
127+
128+
#### `Config::authenticate_subscription`
129+
130+
In order for users to subscribe to a private- or presence-channel, they must be authenticated by your server.
131+
132+
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.
62133

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

66-
TODO: Add link to code docs here
136+
|Argument |Description |
137+
|:-:|:-:|
138+
|channel `String` |**Required**<br> The name of the channel, sent to you in the POST request |
139+
|socket_id `String` | **Required**<br> The channel's socket_id, also sent to you in the POST request |
140+
|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. |
141+
142+
|Return Values |Description |
143+
|:-:|:-:|
144+
|response `dict` | A dictionary to send as a response to the authentication request.|
145+
146+
##### Example
147+
148+
###### Private Channels
149+
150+
```python
151+
config = pusher.config
152+
auth = config.authenticate_subscription(
153+
154+
channel=u"private-channel",
155+
156+
socket_id=u"1234.12"
157+
)
158+
# return `auth` as a response
159+
```
160+
161+
###### Presence Channels
162+
163+
```python
164+
config = pusher.config
165+
166+
auth = config.authenticate_subscription(
167+
168+
channel=u"presence-channel",
169+
170+
socket_id=u"1234.12",
171+
172+
custom_data={
173+
u'user_id': u'1',
174+
u'user_info': {
175+
u'twitter': '@pusher'
176+
}
177+
}
178+
)
179+
# return `auth` as a response
180+
```
181+
182+
Receiving Webhooks
183+
-----------------
184+
185+
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.
186+
187+
#### `Config::validate_webhook`
188+
189+
|Argument |Description |
190+
|:-:|:-:|
191+
|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. |
192+
|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. |
193+
|body `String` | **Required**<br>The JSON string of the request body received. |
194+
195+
|Return Values |Description |
196+
|:-:|:-:|
197+
|body_data `Dict` | If validation was successful, the return value will be the parsed payload. Otherwise, it will be `None`. |
198+
199+
##### Example
200+
201+
```python
202+
webhook = pusher.config.validate_webhook(
203+
204+
key="key_sent_in_header",
205+
206+
signature="signature_sent_in_header",
207+
208+
body="{ \"time_ms\": 1327078148132 \"events\": [ { \"name\": \"event_name\", \"some\": \"data\" } ]}"
209+
)
210+
211+
print webhook["events"]
212+
213+
```
67214

68215
Running the tests
69216
-----------------
@@ -74,4 +221,3 @@ License
74221
-------
75222

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

0 commit comments

Comments
 (0)