Skip to content

Commit f15bab9

Browse files
WillSewellWillSewell
authored
Merge pull request #74 from pusher/publish-info
Support fetching channel info on trigger
2 parents 25b27ae + 9b07a47 commit f15bab9

File tree

9 files changed

+649
-198
lines changed

9 files changed

+649
-198
lines changed

‎README.md‎

Lines changed: 132 additions & 34 deletions
Original file line numberDiff line numberDiff line change
@@ -21,7 +21,6 @@ Register for free at <https://pusher.com/channels> and use the application crede
2121
- [Google App Engine](#google-app-engine)
2222
- [Usage](#usage)
2323
- [Triggering events](#triggering-events)
24-
- [Excluding event recipients](#excluding-event-recipients)
2524
- [Authenticating Channels](#authenticating-channels)
2625
- [Application state](#application-state)
2726
- [Webhook validation](#webhook-validation)
@@ -219,21 +218,65 @@ func handler(w http.ResponseWriter, r *http.Request) {
219218

220219
It is possible to trigger an event on one or more channels. Channel names can contain only characters which are alphanumeric, `_` or `-` and have to be at most 200 characters long. Event name can be at most 200 characters long too.
221220

221+
#### Custom Types
222+
223+
**pusher.Event**
224+
225+
```go
226+
type TriggerParams struct {
227+
SocketID *string
228+
Info *string
229+
}
230+
```
231+
232+
Note: `Info` is part of an [experimental feature](https://pusher.com/docs/lab#experimental-program).
233+
222234
#### Single channel
223235

224236
##### `func (c *Client) Trigger`
225237

226238
| Argument |Description |
227239
| :-: | :-: |
228240
| channel `string` | The name of the channel you wish to trigger on. |
229-
| event `string` | The name of the event you wish to trigger |
241+
| event `string` | The name of the event you wish to trigger. |
230242
| data `interface{}` | The payload you wish to send. Must be marshallable into JSON. |
231243

244+
###### Example
245+
232246
```go
233247
data := map[string]string{"hello": "world"}
234248
pusherClient.Trigger("greeting_channel", "say_hello", data)
235249
```
236250

251+
##### `func (c *Client) TriggerWithParams`
252+
253+
Allows additional parameters to be included as part of the request body.
254+
The complete list of parameters are documented [here](https://pusher.com/docs/channels/library_auth_reference/rest-api#request).
255+
256+
| Argument |Description |
257+
| :-: | :-: |
258+
| channel `string` | The name of the channel you wish to trigger on. |
259+
| event `string` | The name of the event you wish to trigger. |
260+
| data `interface{}` | The payload you wish to send. Must be marshallable into JSON. |
261+
| params `TriggerParams` | Any additional parameters. |
262+
263+
| Return Value | Description |
264+
| :-: | :-: |
265+
| channels `TriggerChannelsList` | A struct representing channel attributes for the requested `TriggerParams.Info` |
266+
| err `error` | Any errors encountered|
267+
268+
###### Example
269+
270+
```go
271+
data := map[string]string{"hello": "world"}
272+
socketID := "1234.12"
273+
attributes := "user_count"
274+
params := pusher.TriggerParams{SocketID: &socketID, Info: &attributes}
275+
channels, err := pusherClient.TriggerWithParams("presence-chatroom", "say_hello", data, params)
276+
277+
// channels => &{Channels:map[presence-chatroom:{UserCount:4}]}
278+
```
279+
237280
#### Multiple channels
238281

239282
##### `func (c. *Client) TriggerMulti`
@@ -250,24 +293,30 @@ pusherClient.Trigger("greeting_channel", "say_hello", data)
250293
pusherClient.TriggerMulti([]string{"a_channel", "another_channel"}, "event", data)
251294
```
252295

253-
#### Excluding event recipients
254-
255-
`func (c *Client) TriggerExclusive` and `func (c *Client) TriggerMultiExclusive` follow the patterns above, except a `socket_id` is given as the last parameter.
296+
##### `func (c. *Client) TriggerMultiWithParams`
256297

257-
These methods allow you to exclude a recipient whose connection has that `socket_id` from receiving the event. You can read more [here](http://pusher.com/docs/duplicates).
298+
| Argument | Description |
299+
| :-: | :-: |
300+
| channels `[]string` | A slice of channel names you wish to send an event on. The maximum length is 10. |
301+
| event `string` | As above. |
302+
| data `interface{}` | As above. |
303+
| params `TriggerParams` | As above. |
258304

259-
##### Examples
305+
| Return Value | Description |
306+
| :-: | :-: |
307+
| channels `TriggerChannelsList` | A struct representing channel attributes for the requested `TriggerParams.Info` |
308+
| err `error` | Any errors encountered|
260309

261-
**On one channel**:
310+
###### Example
262311

263312
```go
264-
pusherClient.TriggerExclusive("a_channel", "event", data, "123.12")
265-
```
266-
267-
**On multiple channels**:
313+
data := map[string]string{"hello": "world"}
314+
socketID := "1234.12"
315+
attributes := "user_count"
316+
params := pusher.TriggerParams{SocketID: &socketID, Info: &attributes}
317+
channels, err := pusherClient.TriggerMultiWithParams([]string{"presence-chatroom", "presence-notifications"}, "event", data, params)
268318

269-
```go
270-
pusherClient.TriggerMultiExclusive([]string{"a_channel", "another_channel"}, "event", data, "123.12")
319+
// channels => &{Channels:map[presence-chatroom:{UserCount:4} presence-notifications:{UserCount:31}]}
271320
```
272321

273322
#### Batches
@@ -278,13 +327,48 @@ pusherClient.TriggerMultiExclusive([]string{"a_channel", "another_channel"}, "ev
278327
| :-: | :-: |
279328
| batch `[]Event` | A list of events to publish |
280329

330+
| Return Value | Description |
331+
| :-: | :-: |
332+
| batch `TriggerBatchChannelsList` | A struct representing channel attributes for the requested `TriggerParams.Info` |
333+
| err `error` | Any errors encountered|
334+
335+
###### Custom Types
336+
337+
**pusher.Event**
338+
339+
```go
340+
type Event struct {
341+
Channel string
342+
Name string
343+
Data interface{}
344+
SocketID *string
345+
Info *string
346+
}
347+
```
348+
349+
Note: `Info` is part of an [experimental feature](https://pusher.com/docs/lab#experimental-program).
350+
281351
###### Example
282352

283353
```go
284-
pusherClient.TriggerBatch([]pusher.Event{
285-
{ Channel: "a_channel", Name: "event", Data: "hello world", nil },
286-
{ Channel: "a_channel", Name: "event", Data: "hi my name is bob", nil },
287-
})
354+
socketID := "1234.12"
355+
attributes := "user_count"
356+
batch := []pusher.Event{
357+
{ Channel: "a-channel", Name: "event", Data: "hello world" },
358+
{ Channel: "presence-b-channel", Name: "event", Data: "hi my name is bob", SocketID: &socketID, Info: &attributes },
359+
}
360+
response, err := pusherClient.TriggerBatch(batch)
361+
362+
for i, attributes := range response.Batch {
363+
if attributes.UserCount != nil {
364+
fmt.Printf("channel: %s, name: %s, user_count: %d\n", batch[i].Channel, batch[i].Name, *attributes.UserCount)
365+
} else {
366+
fmt.Printf("channel: %s, name: %s\n", batch[i].Channel, batch[i].Name)
367+
}
368+
}
369+
370+
// channel: a-channel, name: event
371+
// channel: presence-b-channel, name: event, user_count: 4
288372
```
289373

290374
### Authenticating Channels
@@ -415,15 +499,24 @@ This library allows you to query our API to retrieve information about your appl
415499

416500
| Argument | Description |
417501
| :-: | :-: |
418-
| additionalQueries `map[string]string` | A map with query options. A key with `"filter_by_prefix"` will filter the returned channels. To get number of users subscribed to a presence-channel, specify an `"info"` key with value `"user_count"`. <br><br>Pass in `nil` if you do not wish to specify any query attributes. |
502+
| params `ChannelsParams` | The query options. The field `FilterByPrefix` will filter the returned channels. To get the number of users subscribed to a presence-channel, specify an the `Info` field with value `"user_count"`. Pass in `nil` if you do not wish to specify any query attributes. |
419503

420504
| Return Value | Description |
421505
| :-: | :-: |
422-
| channels `*pusher.ChannelsList` | A struct representing the list of channels. See below. |
506+
| channels `ChannelsList` | A struct representing the list of channels. See below. |
423507
| err `error` | Any errors encountered|
424508

425509
###### Custom Types
426510

511+
**pusher.ChannelsParams**
512+
513+
```go
514+
type ChannelsParams struct {
515+
FilterByPrefix *string
516+
Info *string
517+
}
518+
```
519+
427520
**pusher.ChannelsList**
428521

429522
```go
@@ -443,12 +536,10 @@ type ChannelListItem struct {
443536
###### Example
444537

445538
```go
446-
channelsParams := map[string]string{
447-
"filter_by_prefix": "presence-",
448-
"info": "user_count",
449-
}
450-
451-
channels, err := pusherClient.Channels(channelsParams)
539+
prefixFilter := "presence-"
540+
attributes := "user_count"
541+
params := pusher.ChannelsParams{FilterByPrefix: &prefixFilter, Info: &attributes}
542+
channels, err := pusherClient.Channels(params)
452543

453544
// channels => &{Channels:map[presence-chatroom:{UserCount:4} presence-notifications:{UserCount:31}]}
454545
```
@@ -460,15 +551,23 @@ channels, err := pusherClient.Channels(channelsParams)
460551
| Argument | Description |
461552
| :-: | :-: |
462553
| name `string` | The name of the channel |
463-
| additionalQueries `map[string]string` | A map with query options. An `"info"` key can have comma-separated values of `"user_count"`, for presence-channels, and `"subscription_count"`, for all-channels. To use the `"subscription_count"` value, first check the "Enable subscription counting" checkbox in your App Settings on [your Pusher Channels dashboard](https://dashboard.pusher.com).<br><br>Pass in `nil` if you do not wish to specify any query attributes. |
554+
| params `ChannelParams` | The query options. The field `Info` can have comma-separated values of `"user_count"`, for presence-channels, and `"subscription_count"`, for all-channels. To use the `"subscription_count"` value, first check the "Enable subscription counting" checkbox in your App Settings on [your Pusher Channels dashboard](https://dashboard.pusher.com). Pass in `nil` if you do not wish to specify any query attributes. |
464555

465556
| Return Value | Description |
466557
| :-: | :-: |
467-
| channel `*pusher.Channel` | A struct representing a channel. See below. |
558+
| channel `Channel` | A struct representing a channel. See below. |
468559
| err `error` | Any errors encountered |
469560

470561
###### Custom Types
471562

563+
**pusher.ChannelParams**
564+
565+
```go
566+
type Channel struct {
567+
Info *string
568+
}
569+
```
570+
472571
**pusher.Channel**
473572

474573
```go
@@ -483,11 +582,9 @@ type Channel struct {
483582
###### Example
484583

485584
```go
486-
channelParams := map[string]string{
487-
"info": "user_count,subscription_count",
488-
}
489-
490-
channel, err := pusherClient.Channel("presence-chatroom", channelParams)
585+
attributes := "user_count,subscription_count"
586+
params := pusher.ChannelParams{Info: &attributes}
587+
channel, err := client.Channel("presence-chatroom", params)
491588

492589
// channel => &{Name:presence-chatroom Occupied:true UserCount:42 SubscriptionCount:42}
493590
```
@@ -502,7 +599,7 @@ channel, err := pusherClient.Channel("presence-chatroom", channelParams)
502599

503600
| Return Value | Description |
504601
| :-: | :-: |
505-
| users `*pusher.Users` | A struct representing a list of the users subscribed to the presence-channel. See below |
602+
| users `Users` | A struct representing a list of the users subscribed to the presence-channel. See below |
506603
| err `error` | Any errors encountered. |
507604

508605
###### Custom Types
@@ -594,6 +691,7 @@ Trigger event on single channel | *&#10004;*
594691
Trigger event on multiple channels | *&#10004;*
595692
Trigger events in batches | *&#10004;*
596693
Excluding recipients from events | *&#10004;*
694+
Fetching info on trigger | *&#10004;*
597695
Authenticating private channels | *&#10004;*
598696
Authenticating presence channels | *&#10004;*
599697
Get the list of channels in an application | *&#10004;*

0 commit comments

Comments
 (0)