README.textile

h1. Pusher module

This module lets you easily interact with the "Pusher":http://wwww.pusher.com REST API from your Play application.

h2. Usage

Using it is very simple :

bc. Pusher pusher = new Pusher(appId, key, secret)

Or if you prefer you can add your application API access information to the application.conf file

bc. #Pusher pusher.appId = APP_ID pusher.key = KEY pusher.secret = SECRET

and do the following:

bc. Pusher pusher = new Pusher();

h3. Triggering an event on a channel

You can trigger an event on a channel and deliver a message to all the connected sockets:

bc. HttpResponse response = pusher.trigger("my_channel", "event", "my_message");

This will return the following response if all goes well

bc. 202 ACCEPTED

You can also exclude a socket (usually the sender) from receiving the message by specifying its socket id:

bc. pusher.trigger("my_channel", "event", "my_message", "socket_id");

h3. Generating the authentication string

When a socket tries to connect to a private channel, it will make a POST request to /pusher/auth on your server. You will need to generate and return a JSON object containing the auth signature that allows the socket to connect to the private channel. That is really easy :

bc. pusher.createAuthString(socketId, channelName);

h4. Example

In your controller you can have something like this:

bc. String socketId = params.get("socket_id); String channelName = params.get("channel_name"); renderJSON(pusher.createAuthString(socketId, channelName));

You can also generate an auth signature to allow a socket to connect to a presence channel. In that case you will need to pass a PresenceChannelData object which has a userId field and a BasicUserInfo field.

h4. Example

bc. BasicUserInfo userInfo = new BasicUserInfo(); userInfo.setName("Joe"); PresenceChannelData channelData = new PresenceChannelData("userId", userInfo); renderJSON(pusher.createAuthString(socketId, channelName, channelData));

Check out the "Pusher Documentation":http://pusher.com/docs for more information.