JavaScript Storage & Playback Tutorial for Realtime Apps

 

Requires that the Storage and Playback add-on is enabled for your key. How do I enable add-on features for my keys? - see http://www.pubnub.com/knowledge-base/discussion/644/how-do-i-enable-add-on-features-for-my-keys

PubNub's Storage and Playback feature enables developers to store messages as they are published, and retrieve them at a later time. Before using this feature it must be enabled in the PubNub Admin Console.

Being able to pull an archive of messages from storage has many applications:
  • Populate chat, collaboration and machine configuration on app load.
  • Store message streams with real-time data management.
  • Retrieve historical data streams for reporting, auditing and compliance (HIPAA, SOX, Data Protection Directive, and more).
  • Replay live events with delivery of real-time data during rebroadcasting.

As needed, specific messages can be marked "do not archive" when published to prevent archiving on a per-message basis, and storage retention time can range from 1 day to forever.

These code samples build off code defined in the Pub & Sub tutorial, so before proceeding, be sure you have completed the Pub & Sub tutorial first.

To begin, lets populate a new channel with some test publishes that we'll pull from storage using the history() method:

 function pub() {
    for (var i = 0; i < 500; i++)  {
       // publish 500 messages...
       pubnub.publish({
         channel: 'history_channel',
         message: "message: " + i
       });       
    };
 };

pubnub.subscribe({
    channel: 'history_channel',
    message: function(m){console.log(JSON.stringify(m))},
    connect: pub()
});

In the above example, we subscribe to history_channel, and onConnect, we'll publish a barrage of test messages to it. You should see these messages as they are published on the console.

Pulling from Storage with a simple :history: call Now that we've populated storage, we can pull from storage using the history() method call:

pubnub.history({
     channel: 'history_channel',
     callback: function(m){console.log(JSON.stringify(m))},
     count: 100, // 100 is the default
     reverse: false // false is the default
 });

The response format is

[["message1", "message2", "message3",... ],"Start Time Token","End Time Token"]

By default, history() returns the last 100 messages, first-in-first-out (FIFO). Although we specified 100 for the count, that is the default, and if we hadn't specified a count, we would have still received 100. Try this example again, but specify 5 for count to see what is returned.

Setting the reverse attribute to true will return the first 100 messages, first-in-first-out (FIFO). Try this example again, but specify true for reverse to see what is returned.

Given this example, you will get the last two messages published to the channel:

pubnub.history({
    channel: 'history_channel',
    callback: function(m){console.log(JSON.stringify(m))},
    count: 2,
    reverse: false
});
[[498,499],14272454823679518,14272454845442942]

To page for the next 2, use the set the start attribute to start timetoken value, and request again with all other settings the same:

[[496,497],14272454791882580,14272454823679518]

As illustrated, paging with the default reverse as true pages 2 at-a-time starting from newest, in FIFO order. If you repeat these Paging example steps with reverse as false, you will page 2 at-a-time as well, starting instead from the oldest messages, but still in FIFO order. You will know you are at the end of history when the returned start timetoken is 0.

To pull from a slice of time, just include both start and end attributes:

pubnub.history({
    channel: 'history_channel',
    count: 100,
    start: 13827485876355504,
    end: 13827475876355504,
    callback: function(m){console.log(JSON.stringify(m))}
});

The timetoken response value is a string, representing 17-digit precision unix time (UTC). To convert PubNub's timetoken to Unix timestamp (seconds), divide the timetoken number by 10,000,000 (10^7).


Check out PubNub's other JavaScript-based SDKs, such as AngularJS, NodeJS, Titanium, Sencha, PhoneGap, CommonJS, Web, WebWorker, SmartTV, WebOS, ImpactJS, QooxDoo, WebRTC, Parse.