Heroku Add-on

Using EventSource HQ with Heroku couldn't be easier.

The simplest possible way to get started is to type these 5 lines in your terminal.

make sure you have the heroku gem installed first

Now you have your very own personal EventSource powered chat-room where you can spend hours and hours chatting with yourself!

git clone git://github.com/eshq/chat.git
cd chat
heroku create
heroku addons:add eshq
git push heroku master
Install the eshq add-on in your app
$ heroku addons:add eshq
Add the "eshq" gem to your Gemfile and run bundle install
gem "eshq"

When adding the add-on to your heroku app, 3 config variables will be added to your heroku config vars.

The eshq gem uses these to authorize you with the EventSource HQ service.

ESHQ_URL=http://app.eventsourcehq.com
ESHQ_KEY=<your api key>
ESHQ_SECRET=<your api secret>

EventSource HQ comes with a tiny javascript library that makes it easy to connect to a channel from the browser and bind to events.

<script src="http://app.eventsourcehq.com/es.js"></script>

JavaScript API

The EventSource HQ API is very close to the HTML5 EventSource API, but instead of using an EventSource object you use the ESHQ object.

To start binding to event, create a new ESHQ channel.

var eshq = new ESHQ("my-channel");
    
eshq.onopen = function(e) {
    // callback called when the connection is made
};
    
eshq.onmessage = function(e) {
    // called when a new message with no specific type has been received
    console.log("Message type: %s, message data: %s", e.type, e.data);
};
    
eshq.onerror = function(e) {
   // callback called on errror
};

You can also bind to different types of event with addEventListener

eshq.addEventListener("my-event", function(e) {
    console.log("Got an event with the type 'my-event'");
});

Serverside API

When openening a channel by calling `new ESHQ("channel-name"), the script will make a post request to /eshq/socket on your app. You should respond to this request by using the eshq gem to create a new connection and return the "socket id" to the client. Here's a simple Sinatra example.

post "/eshq/socket" do
  socket = ESHQ.open(:channel => params[:channel])
    
  content_type :json
  {:socket => socket}.to_json
end

Posting events from the server is straight forward. Just use the ESHQ.send method

The type parameter is optional and set to "message" by default.

ESHQ.send(
  :channel => "my-channel",
  :data => "Raw Message Data",
  :type => "message"
)

To use EventSourceHQ from your local machine during development you'll need to set a few environment variables.

Run heroku config from your app after installing the eshq addon. Then export the ESHQ related variables to your environment.

export ESHQ_KEY=<your eshq key>
export ESHQ_SECRET=<your eshq secret>
export ESHQ_URL=http://app.eventsourcehq.com