h1. Pusher module

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

h2. Prerequisites

First, you will need to install the module. From the command line:

bc. play install pusher

Then add the module in your dependencies.yml file:

bc. - play -> pusher 0.1

Finally make sure you sign up and add an application on "Pusher":http://www.pusher.com

That's it! You are ready to use it.

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.auth(channelName, socketId);

h4. Example
In your controller you can have something like this:

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


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 an **user id** and some **user info**. The **user info** can be any object, it will automatically be serialized.

h4. Example
bc.
HashMap<String, String> userInfo = new HashMap();
userInfo.put("name","John Doe");
userInfo.put("email","john@example.com")

renderJSON(pusher.auth(channelName, socketId, userId, userInfo));


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