In this blogpost, I will present to you the best way, in my opinion, to integrate Pusher with a Rails application. Moreover, this is also an introduction to ember-pusher-guru, which we recently open-sourced as our recommended way to integrate Pusher with your Ember applications.
Let's make the following assumptions about your requirements: you need a ready-to-use websockets solution which is easy to set up. It can handle public, private and client events with or without authorization. It is paid, and you can check out pricing here.
Setting up Your Rails Backend
What You Will Need
pushergem - a server gem that is responsible for triggering events to clients (events may also be triggered between clients excluding the server, but it requires more configuration, which will be handled later)
Set up the Initialiser
Pusher will be available as a global singleton object, set up as an initialiser. You need to add pusher.rb to your initialisers, which will simply define app credentials and enable encryption. See this commit as an example.
Create Pusher::Dispatcher Service to Trigger Events
This step depends on your architecture of choice. I chose to have a Pusher::Dispatcher class that will just trigger the Pusher singleton. It might look like overkill, but it's a good place to, say, calculate your channel name based on some variables (like user ID).
Notice that your channel name can be whatever you want - it’s created and handled by Pusher on demand, so there is no need to define it earlier. You only send events on channels via the server, and everybody who connects to your channel will get these particular events.See this commit as an example.
Add an Authorisation Endpoint
Authorization in Pusher is very simple. The authentication flow is as follows:
You provide an endpoint for authorisation to every client (e.g. on the frontend side or in the iOS app).
When the client wants to connect, it hits the endpoint with client-side defined params.
Your endpoint should somehow validate these params (e.g. by checking the authorisation token) and authenticate the connection via a Pusher singleton object with params of your choice - e.g. more data about the currently authorised user.
Each client can define its authorisation endpoint during initialisation. For example, in a frontend or iOS app you can initialize Pusher with the authorisation endpoint pointed at https://myapp.com/api/pusher/auth.
Clients can also configure the params that they are sending to that endpoint. So, you can send the current user ID and the auth token that is being used in the frontend application to your /api/pusher/auth endpoint.
You can easily debug and validate your Pusher implementation without any frontend at all. In my app, where there is basically no business logic, I created a simple endpoint that will trigger Pusher events on demand for testing. Take a look this example commit.
Now I can simply trigger Pusher events by using CURL:
What is cool about Pusher is that it has an excellent debug console available on the web. What this means is that you don't need to have a frontend-ready solution - just work on the backend until it’s good to go!
Open your app’s debug console in the Pusher dashboard, restart your server and then check if Pusher is getting the necessary data!
Summary of Backend Setup
You have set up everything you need to fully utilise Pusher’s basic functionality. You can handle public, private and presence channels (private and presence channels require authorisation). You can easily trigger events, and you have the reusable Pusher::Dispatcher class. And you learned about the Pusher Debug console, which is a must-have in your toolbelt. Good job!
Setting up Your Ember Application
What You Will Use
ember-pusher-guruaddon - I did mention that we just released our ember wrapper for Pusher, didn't I?
The above addon covers public, private and presence channels. We don't support client events yet, but would love to do so - we just don't have a project right now that can make use of client events. Do you? If so, drop me a line on Twitter or in the comments and we can code it for you!
Installation is easy and you can find the details in the README. Let's focus on a couple of internals here. Basically, what happens when you install this addon by executing ember install ember-pusher-guru is:
it’s added to your package.json
two pusher-js packages are added to your bower.json
your included hook is plugged into the ember cli and the pusher-js package is imported from bower straight to your app window
That's the installation process. Enter your app id in the pusherKey entry in the config file and let's move on to implementation.
Now, we will create a service in your frontend application that will listen globally for Pusher events. This service can then be injected into any other Ember.Object you would like to use it in - Route, Controller or Component.
ember-pusher-guru provides you with the service object, which must be extended with a bit of configuration.
Ok, so how can we plug Pusher events after we’ve bound to them? With ember-pusher-guru it's simple! Just extend your Ember.Object with the pusher-initializer mixin and define your pusherActions property - an object mapping a key event name to a function name in your object in the key's value.
Some simple configuration allows you to use Pusher in any Ember.Object you want. Be it route, controller or component. Moreover, you don't have to handle all the events in one place - only those that you are currently interested in!
It was simple, wasn't it? This very quick approach allows you to take advantage of real-time notifications in less than an hour, including Rails and Ember setup. Isn't it a great speed boost for your work?
Thanks to Michał Olejniczak who did an excellent job as the main contributor to our addon!