MessageRocket is a SASS service add-on providing real time PubSub services to legacy applications.
MessageRocket enables realtime pub/sub communication between clients and server using WebSocket, Long-polling and JSONP. Using our client libraries for Ruby and JavaScript you can easily add broadcast, two-party or multi-party messaging to your app.
Provisioning the Add-on
MessageRocket can be added to your Heroku application using the Heroku Toolbelt CLI or the MessageRocket Add-on Page.
A list of all plans available can be found here.
Once MessageRocket has been added, several new configuration settings will be available in the app:
MESSAGEROCKET_URL
The HTTPS URL to our messaging engine.
MESSAGEROCKET_PKEY
Your public connection key; this is added to all connections to our service from your clients.
MESSAGEROCKET_SKEY
Your secret connection key; its used to identify your app for the purposes of authorizing your clients.
These can be confirmed using the heroku config:get command:
After installing MessageRocket, the application should be configured to fully integrate the add-on.
Local setup
After provisioning the add-on, it’s necessary to locally replicate the config vars so your development environment can operate against the service.
Although less portable, it’s also possible to set the local environment variables using your shell’s export command.
Use Foreman to configure, run and manage process types specified in your app’s Procfile. Foreman reads configuration variables from an .env file. Use the following command to add the MessageRocket variables retrieved from heroku config to .env.
Credentials and other sensitive configuration values should not be committed to source-control. In Git you can exclude the .env file with: echo .env >> .gitignore
Using with Ruby and Rails
Installing
Ruby or Rails applications will need to add the following entry into their Gemfile specifying the MessageRocket client library.
Update application dependencies with bundler.
Serving JavaScript
View Helpers
If you’re using Rails then the message_rocket gem will automatically wire up the MessageRocket helpers.
You can use the message_rocket_link_tag helper defined in the MessageRocket::Helpers module to add the needed meta and javascript link tags to your views.
Authorizing Subscriptions
By default MessageRocket denies all subscription requests you do not explicitly authorize - this is to prevent clients from being able to talk to each other without your app knowing about it.
We manage subscription requests using the MessageRocket.on method:
We provide an event to respond to (in this case :subscription_request) and a block to be called when this event is triggered.
The block is called with a single SubscriptionRequest object, which has the following useful methods:
channel
The name of the channel the client is attempting to subscribe to.
client_auth
An optional authentication token provided to the client.
client_id
A unique identifier for the requesting client connection.
id
A unique identifier for this request.
permit
Permits the client’s subscription request.
Defaults to a ‘read-write’ subscription meaning the client can publish and receive messages sent on this channel.
Optionally, you can specify the subscription type as a single symbol argument:
:read_write
The default, the client can publish and receive messages on this channel.
:read_only
This client receives messages sent to this channel, but cannot publish.
:write_only
This client can send, but will not receive any messages published on this channel.
deny
Denies the client’s subscription request.
Sending Messages
You can publish messages to your clients on any channel using MessageRocket.publish method:
Messages can be any object which can be serialized to JSON.
Subscribing to channels
You can subscribe to any channel using the MessageRocket.subscribe method:
When calling subscribe you need to provide the name of the channel to subscribe to and a block to call when a message is received. The message is a deserialized JSON object, so usually a Hash.
Unsubscribing from channels
You can unsubscribe from a channel by calling MessageRocket.unsubscribe and passing the channel name, after which you will not receive any further messages from that channel:
Using with Node.js
The Node.js client is currently under development.
Client-side JavaScript
Our JavaScript client library is available at https://messagerocket.co/messagerocket.js - we recommend that your clients load it from our site directly, rather than vendoring, as you may miss out on important bug fixes or improvements in our client.
Configuration
The client looks for two HTML meta tags for configuration:
The values for which can be set from the Heroku environment.
Creating a client
To create a new client instance, use the MessageRocket constructor. You can optionally provide a clientAuth argument, which is an arbitrary value you can use to uniquely identify this particular client. This could be something like the user’s ID or a secret stored in their session.
Subscribing to channels
You can send subscription requests to the server using the subscribe method. It takes two arguments:
channelName
The name of the channel to request subscription to.
messageHandler
A callback function which is called once with every incoming message.
When the promise resolves, it returns an instance of a MessageRocket.Channel object.
Sending messages
Once you have successfully subscribed to a channel, you can call the publish method on the channel object to publish messages.
Messages can be any object which can be serialized to JSON.
It takes a single argument:
message
The message to send to the channel.
Unsubscribing from channels
You can easily unsubscribe from a channel by calling the unsubscribe method on the channel object. This method takes no arguments.
Connecting & disconnecting
The client automatically, lazily connects and disconnects based on the currently active channel subscriptions. However, you can force connection or disconnection using the connect and disconnect methods:
Migrating between plans
Application owners should carefully manage the migration timing to ensure proper application function during the migration process.
Use the heroku add ons:upgrade command to migrate to a new plan.
Removing the Add-on
MessageRocket can be removed via the CLI or from your application’s dashboard.
This will destroy all associated data and cannot be undone!
Support
All MessageRocket support and runtime issues should be submitted via one of the Heroku Support channels. Any non-support related issues or product feedback is welcome at MessageRocket Support.