Ruby Push API

This website is dedicated to Publish() + Subscribe() Realtime Notifications Framework. The concept of Publish + Subscribe is simple. Subscribers are people with phones and browsers. Subscribers receive updates instantly when a message is Published.

Computers can be subscribers too, like a web server or your laptop. This is where the Ruby Push API is helpful.

Download the Pubnub.rb Ruby Push API Client Library on GitHub to follow along if desired.

In the same directory are fun Ruby Push API Examples to play with.

Publish() with Ruby Push API

To send a message to all subscribers, call the publish() function. This function needs a channel and a message. The message is automatically converted to JSON, though you don't need to worry about that because the transport encodes and decodes JSON when necessary. The following code snippet shows how to publish a message.

## Create PubNub Instance
pubnub = Pubnub.new( 'publish_key', 'subscribe_key' )

## Publish (Send Message)
pubnub.publish({
    'channel' => 'my_channel',
    'message' => { 'my_var' => 'my text data' }
})

The above function sends a JSON message to all subscribers. The structure of the message is maintained along the way; no need to worry about encoding or decoding:

{ 'my_var' : ... }

The message structure is portable across all environments (Ruby, JavaScript, PHP, etc.)

You will need to have your API keys from PubNub. Grab your API Keys with the link below. Get API Keys You only need the Publish and Subscribe keys for now. Ignore the Secret Key.

Subscribe with Ruby Push API

To listen for published messages, call the subscribe function. It is important to note: the subscribe function is blocking. You will want to run this function in a separate process. The following code snippet will show how to listen for published messages.

## Subscribe (Listen for Messages)
pubnub.subscribe({
    'channel ' => 'my_channel',
    'callback' => lambda do |message|
        ## Message Received!!!
        puts(message['my_var']) ## print message
        return true             ## keep listening?
    end
})

Once you call this function, it turns your Ruby Script into a mini server which listens for publish events. This function is more involved than publish(), yet remains simple. You must specify a channel and specify a callback function to execute when a message is received. The callback can be a lambda or proc depending on your scope needs. This function will stay connected, forever listening for published messages. This works even behind a firewall! For full reference of functions, visit the following link. Ruby Push API Tutorial Next let's see what we can do inside the Subscribe Callback.

What to do Inside a Subscribe Callback

Your Callback is executed once for each message received. Note there is no enforced schema/format for messges. The structure is up to you and can be any JSON Serializable Ruby Object.

So what do you do with the message? When the callback executes, you may decide to save the message to a database for persistence. Also you may publish this message to other channels by calling pubnub.publish() inside your subscribe callback. These other channels, you can decide, may have JavaScript subscribers on browsers. Totally up to you. Here is a fun dual Ruby and JavaScript example:

Ruby
## Ruby Subscribe (Listen for Messages)
pubnub.subscribe({
    'channel ' => 'my_hidden_channel',
    'callback' => lambda do |message|
        ## Message Received!!!
        ## maybe save to database?
        save_to_database(message['text'])

        ## do logic which validates message
        if message['text']
            ## Relay Message to Browsers
            publish.publish({
                'channel' => 'my_javascript_channel',
                'message' => message
            })
        end
    end
})

JavaScript
// JavaScript Subscribe (Listen for Messages)
PUBNUB.subscribe({
    channel : 'my_javascript_channel'
}, function(message) {
    // Show Message
    alert(message['text']);
} );

The above two boxes show communication between a Ruby script on a server, and a JavaScript in a web browser. The Ruby Script listens for messages published on a hidden channel. If the message is validated it will re-publish the message to browser subscribers for instantaneous updates. More details on the JavaScript Push API can be read in the following tutorial link. JavaScript Push API Tutorial There are many recipes with server and client push APIs. Note that the Ruby and JavaScirpt Push APIs are independent and can be used separately. For example you may Publish and Subscribe directly in a web browser without a server! This works on mobile as well (such as iPhone/Android). If you are interested in a fully functional JavaScript Push API which requires no back-end server, read the JavaScript Push API Tutorial

History API Call

To peak at previously published messages on a specific channel you'll use the pubnub.history() function. This function allows you to recall up to 100 previously published messages within the past few days. The messages expire. Make sure not to depend on this API for persetent storage.

## Load Previously Published Messages
messages = pubnub.history({
    'channel' => 'hello_world',
    'limit'   => 100
})

To improve network performance, especially on mobile JavaScript, request fewer messages with by lowering the limit. Visit the link below for a simple reference of the history() function. Ruby Push API Tutorial Ruby Push API Examples on GitHub