News

Announcing Channel Presence

6 min read • Stephen Blum on Aug 30, 2012

The launch of PubNub Channel Presence opens up a new world of possibilities when building apps and websites.  PubNub Channel Presence is a globally distributed “user presence” system that delivers real-time “occupancy analytics” to iPhones, Androids, tablets, web browsers, and desktops.   So, what does this really mean? For one, you can now create beautiful HTML5 chat apps on both mobile and web.

PubNub Channel Presence – Introduction from PubNub Video on Vimeo.

To answer that question, let’s quickly review the PubNub basics.  PubNub Galaxy is a service that gives developers the ability to broadcast data to millions of devices at the same time.  Every phone, tablet, or browser “subscribes” to a channel, and receives data published to the channel instantly.  PubNub Pulse maintains millions of connections to devices simultaneously, enables one-to-one real-time updates cost effectively to a large population of devices.  PubNub powers thousands of real-time apps, from multiplayer games, VoIP clients, Social TV apps, and real-time business and educational software.

But a common question is “who’s listening“?  Most real-time apps want to show their end-users who else is there (i.e. subscribing) to a channel.  This functionality is a common requirement in chat apps (think about the green icon that appears next to someone’s name), as well as within game room lobbies and many other similar apps.  As it turns out, without Channel Presence, this functionality is very hard to develop on your own, especially at scale and within a global infrastructure.

PubNub Channel Presence delivers a live real-time stream of information about who, and how many people are connected.  PubNub Channel Presence will also provide a list of every connected user, at any time, allowing you to enable new capabilities within your apps, such as User Events with Join/Leave Status Changes.  PubNub Channel Presence delivers a consumable stream of events, directly to every device. The number of active users connected to a PubNub channel is streamed to you automatically as the number of users connected to a channel changes over time.

As WebSockets, WebRTC, SPDY, and other protocols illustrate, real-time apps are the hot new trend.  With all the excitement, noise, and confusion about real-time protocols, including WebSockets, WebRTC, SPDY, etc, PubNub is the only solution to deliver global scale real-time messaging, that works across any browser, mobile phone, tablet or any other device with an IP address using a single API.  You won’t have to worry about writing code specific to a device or browser, PubNub will make sure it works even as standards change. And, now Channel Presence extends the real-time footprint to deliver real-time visibility about who’s currently using an app without having to consider technologies or transports as discussed in Are HTML5 WebSockets the Panacea for Real-Time Data Push.

How to use Channel Presence

First of all, be sure to check out our updated PubNub Developer Console.  Now you can monitor not only your PubNub messages as they’re sent, but also all the Channel Presence data in real-time.

Code Walk-Thru

Here we’ll discuss the important aspects pertinent to Channel Presence.  If you’re more of the video walk-thru type, check this out:  PubNub Channel Presence – Code Walkthrough. 

There are two aspects to obtaining Presence Events.  You can stream presence events as they occur directly to your target device with the PubNub Presence Callback located inside the PubNub Subscribe Function call.  You can also invoke a “Here Now” call which returns information about the current state.  Note that the “Here Now” function will give you the full state information of the channel where the Presence Callback would only stream new events to your mobile app or web app.

PubNub Channel Presence Callback

The Presence Callback is located inside the PubNub Subscribe Function as an optional parameter.  When included in the subscribe function, you will automatically receive presence events streamed to the specified callback.  Note, that we will be using JavaScript as the language to demonstrate PubNub Channel Presence; Channel Presence is available in many other languages.

JavaScript sample of Channel Presence:

// Open Bidirectional Socket Connection
PUBNUB.subscribe({
    channel  : "my_channel", // Channel Name
    connect  : connect, // OnConnect Callback
    callback : chat,  // Received Message Callback
    presence : presence // Presence Callback
});

As you can see the Presence Callback refers to a JavaScript Function Reference.  The event information will pass to you in the following Format when a User Joins the Channel:

{
   "action":"join",
   "timestamp":1345546797,
   "uuid":"175c2c67-b2a9-470d-8f4b-1db94f90e39e",
   "occupancy":2
}

Next you need to know about the format when a User Leaves a Channel:

{
   "action":"leave",
   "timestamp":1345549797,
   "uuid":"175c2c67-b2a9-470d-8f4b-1db94f90e39e",
   "occupancy":1
}

Notice that the occupancy number updates as expected.  The uuid section is a programmable ID that is associated with each user.  You can set this to whatever you need it to be in order to identify your user.  When you init the PubNub instance, you can set the UUID as an optional parameter.  The default value is a random UUID.

// Setup Connection Based on User Data
// This will provide Connectivity References
var PUBNUB = PUBNUB.init({
    publish_key   : 'demo',
    subscribe_key : 'demo',
    ssl           : false,
    cipher_key    : '',
    uuid          : "YOUR UNIQUE USER ID HERE!"
});

With this example you see that you can set the UUID to anything you need.  This UUID value will be transmitted on Join/Leave events; and also the here_now function.

Channel Presence Here Now Function

The Channel Presence Here Now function provides you the ability to answer the question: “Who is here right now?”.  You will receive a list of UUIDs as well as an occupancy number.  Here is an example of how to use the Here Now function:

// Get List of Occupants and Occupancy Count.
function connect() {
    p.here_now({
        channel  : channel,
        callback : presence
    });
}

You pass in the channel name and the callback function to be used to send the data to.  The here_now data response will look like this:

{
   "uuids":[
      "UUID1",
      "UUID2",
      "UUID3"
   ],
   "occupancy":0
}

As you can see you get a list of UUIDs of your users.  The UUIDs will either be randomly generated for anonymous users or will be the UUIDs you supplied when you initialized the PubNub instance.

Now you know the basics for the PubNub Channel Presence with JavaScript.  Note that other Language SDKs provide similar interfaces with easy copy/paste documentation on our GitHub Repository.  Checkout the PubNub API GitHub Repository.

0