Welcome! We’re here to get you started quickly with your integration between PubNub and Ember.js. Ember.js the leading framework for creating ambitious web applications. PubNub makes it easy to integrate real-time bidirectional communication into your app.

If you’re interested in the SDK internals, please check out the annotated source code!

The Easiest Way Possible

Using Bower:

bower install pubnub-ember

Integrating PubNub Ember.js SDK into Your App

Your HTML page will include 3 key libraries:

  • The core PubNub JS Library (generally from the CDN)

  • Ember.js (usually as a Bower component), which also needs jQuery and Handlebars

  • PubNub Ember (as a Bower component or copy&paste)

The HTML code looks like this:

<script src="http://code.jquery.com/jquery-1.10.1.min.js"></script>
<script src="http://cdn.pubnub.com/pubnub.min.js"></script>
<script src="http://builds.handlebarsjs.com.s3.amazonaws.com/handlebars-1.0.0.js"></script>
<script src="http://builds.emberjs.com/release/ember.js"></script>
<script src="components/pubnub-ember/pubnub-ember.js"></script>
<link rel="stylesheet" href="//netdna.bootstrapcdn.com/bootstrap/3.0.2/css/bootstrap.min.css">

We presume your application is already Ember.js-enabled using an Ember.Application.create() call or the equivalent:

window.MyApp = Ember.Application.create();

Where MyApp is the name of the Ember.js application we are presently working with.

We presume the code for the app lives in:

<script src="scripts/app.js"></script>

Inside app.js, add this extra tiny bit of code to initialize the PubNub service:

MyApp.PubNub = PubNubEmber.extend({
  cfg: {
    subscribe_key: 'demo',
    publish_key: 'demo',
    uuid: user_id
  }
});

Of course, for your application, you should initialize the service with your own publish and subscribe keys from your PubNub account.

This will make sure that the main:pubnub object is fully initialized and available to get injected into your controllers and routers.

We presume the code for your controllers also lives in:

<script src="scripts/app.js"></script>

The Ember.js PubNub service is injected into the controller as follows:

MyApp.ApplicationController = Ember.Controller.extend({
  needs:['pubnub:main'],
  ...

This allows you to access the PubNub service anywhere in your controller using this.get('pubnub'). Sometimes you may need some extra tricks to use this inside nested closures (AKA "var self = this;" outside the closure).

That’s it - you’re ready to start using the Ember.js PubNub SDK!

Here’s How to Use It

PubNub has a wide feature set, including:

  • Publish/Subscribe Messaging

  • Message Playback and Storage

  • Presence

  • Storage and History

  • Multiplexing

  • Security, Access Management & Encryption

Getting Started with the Publish / Subscribe API

Publishing to channels is trivial. In this case, we presume the controller has properties for user_id and channel, an input box bound to the new_message property, and a submit button bound to action publish. Here’s how to create an Ember.js action in your controller that publishes a message:

MyApp.ApplicationController = Ember.Controller.extend({
  ...
  actions: {
    // set up an Ember Action to publish a message
    publish: function() {
      this.get('pubnub').emPublish({
        channel: this.get('channel'),
        message: "[" + this.get('user_id') + "] " + this.get('new_message')
      });
      this.set('new_message', ''); // resets the view to empty string (optional)
    }
  }
  ...

We call the PubNub emPublish method passing in the selected channel and the message to transmit. You can also transmit structured data as JSON objects which will be automatically serialized & deserialized by the PubNub library.

Subscribing to channels is accomplished by calling the PubNub emSubscribe method. After the channel is subscribed, the app can register root scope message events by calling PubNub.on with the event string returned by PubNub.emMsgEv(channel).

var pn = this.get('pubnub');
var theChannel = this.get('channel');

// Subscribe to the Channel
pn.emSubscribe({ channel: theChannel })

Note - if you’d like, you can also provide callbacks to receive message and presence events as part of your emSubscribe call using message and/or presence handlers as follows:

var pn = this.get('pubnub');
var theChannel = this.get('channel');

pn.emSubscribe({
  channel: theChannel,
  message: function() { console.log('msg', arguments); }, // optional
  presence: function() { console.log('prs', arguments); } // optional
})

Under the hood, the PubNub Ember.js SDK will wrap your callback and invoke it. Why do we wrap it? So that we can provide all the goodness of the Presence API - see the next sections for more info!

This is the core of the PubNub API - allowing clients to subscribe and publish to channels, and have those events propagate in real-time to other applications connected to the same channels.

Integrating Presence Events

It’s also easy to integrate presence events using the Ember.js API. In the example above, we just add an additional couple lines of code to call the PubNub.emHereNow() method (retrieve current users), and register for presence events by calling PubNub.on with the event string returned by PubNub.emPrsEv(channel).

var pn = this.get('pubnub');
var theChannel = this.get('channel');

// subscribe to the channel
pn.emSubscribe({ channel: theChannel })

// handle message events
pn.on(pn.emMsgEv(theChannel), function(payload) { ... })

// handle presence events
pn.on(pn.emPrsEv(theChannel), function(payload) {
  // payload contains message, channel, env...
  console.log('got a presence event:', payload);
})

// obtain the list of current channel subscribers
pn.emHereNow({ channel: theChannel })

Using the presence event as a trigger, we retrieve the Presence list for a channel using the PubNub.emListPresence() function.

var pn = this.get('pubnub');
var theChannel = this.get('channel');

pn.on(pn.emPrsEv(theChannel), function(payload) {
  var users = pn.emListPresence(theChannel);
  // do stuff with 'users'...
});

Retrieving History

It can be super-handy to gather the previous several hundred messages from the PubNub channel history. The PubNub Ember.js API makes this easy by bridging the event model of the PubNub JS history API and the Ember.js Evented event publish/subscribe model so that historical messages come through the same event interface.

var pn = this.get('pubnub');
var theChannel = this.get('channel');

pn.emHistory({channel: theChannel, count:500});
// message events will be sent out via Ember.Evented.trigger() to the 'on' handlers ...

Listing & Unsubscribing from Channels

The PubNub Ember.js API takes care of keeping track of currently subscribed channels. Call the PubNub.emListChannels() method to return a list of presently subscribed channels.

var pn = this.get('pubnub');

var channels = pn.emListChannels();

Unsubscribing is as easy as calling the PubNub.emUnsubscribe() method. The library even takes care of removing the Ember.js event handlers for you to prevent memory leaks!

var pn = this.get('pubnub');
var theChannel = this.get('channel');

pn.emUnsubscribe({channel: theChannel })