SelectWebOS Configuration API Reference for Realtime Apps

These docs are for version 3.16.5 of the WebOS SDK. To check out the docs for the latest version Click Here.
 

PubNub 4.0 for JavaScript is our latest and greatest! Please click here for our PubNub 4.0 for JavaScript docs and SDK.

PubNub 3.x for WebOS will encounter End Of Life (EOL) July 1st, 2017. All users currently on 3.x should begin migrating to 4.x. The 3.x SDK will continue to work. We will no longer support it and if you run into an issue, we will request that you upgrade to the latest version before solving the issue.

If you have questions about the PubNub for JavaScript SDK, please contact us at support@pubnub.com.

WebOS complete API reference for building Realtime Applications on PubNub, including basic usage and sample code.

You must include the PubNub JavaScript SDK in your code before initializing the client.


<html>
    <body>
        <script src="http://cdn.pubnub.com/pubnub-3.16.5.min.js"></script>
    </body>
</html>
This function is used for initializing the PubNub Client API context. This function must be called before attempting to utilize any API functionality in order to establish account level credentials such as publish_key and subscribe_key.
To Initialize Pubnub you can use the following method(s) in the WebOS SDK:
  1. ParameterTypeRequiredDescription
    origin String OptionalSpecifies the fully qualified domain name of the PubNub origin. By default this value is set to ps.pndsn.com but it should be set to the appropriate origin specified in the PubNub Admin Portal.
    publish_key String OptionalSpecifies the publish_key to be used for publishing messages to a channel. This key can be specified at initialization or along with a publish().
    subscribe_key String YesSpecifies the subscribe_key to be used for subscribing to a channel. This key can be specified at initialization or along with a subscribe().
    uuid String Yes

    UUID to use. You should set a unique UUID to identify the user or the device that connects to PubNub.

    Allowing the SDK to generate a random UUID can result in significant billing impacts, particularly on an MAU pricing plan.

    cipher_key String OptionalSpecifies a cryptographic key to use for message level encryption with AES. The cipher_key specifies the particular transformation of plain text into cipher text, or vice versa during decryption.
    auth_key String OptionalSpecifies auth_key to use to determine User-Level Access Manager permissions.
    noleave Boolean OptionalExplicitly disables presence leave events.
    keepalive Number OptionalSpecifies the interval between keepalive pings. The default value is 60 seconds. See keepalive example for more info.
    secret_key String OptionalThe secret_key is a super-secret private key used only to sign Access Manager API messages. Signatures are computed using HMAC + SHA256 with the application’s secret key as the signing key and the request string as the message. This signature is then Base64 encoded.
    ssl Boolean OptionalSetting a value of true enables transport layer encryption with SSL/TLS. Default is false.
    windowing Number OptionalSpecifies the time interval in milliseconds that PubNub will use to optimize message delivery by bundling them into a single compressed payload. The Default is 10 milliseconds. See windowing example for more info.
    jsonp Boolean OptionalThe JavaScript SDK automatically selects the appropriate transport method during run-time. Setting jsonp to true explicitly enforces JSON(P) as the data transport method.
    restore Boolean OptionalIf restore is set to true , when a client is disconnected and then reconnects to a channel, it will automatically attempt to retrieve any missed messages since it was last connected.
    heartbeat Number OptionalUsed to set the Presence heartbeat value (in seconds). If no presence heartbeat is received within this interval the client subscription will be timed-out
    heartbeat_interval Number OptionalUsed to set the Presence heartbeat interval value (in seconds). The SDK will send a heartbeat ping to the server after this time is elapsed. Recommended value (heartbeat-1)/2
 Always set the UUID to uniquely identify the user or device that connects to PubNub. This UUID should be persisted, and should remain unchanged for the lifetime of the user or the device. Not setting the UUID can significantly impact your billing if your account uses the Monthly Active Users (MAUs) based pricing model, and can also lead to unexpected behavior if you have Presence enabled.
var pubnub = PUBNUB({
    subscribe_key: 'my_subkey',
    publish_key: 'my_pubkey',
    ssl: true
});
It returns the Pubnub instance for invoking PubNub APIs like publish(), subscribe(), history(), here_now(), etc.
  1.  Always set the UUID to uniquely identify the user or device that connects to PubNub. This UUID should be persisted, and should remain unchanged for the lifetime of the user or the device. Not setting the UUID can significantly impact your billing if your account uses the Monthly Active Users (MAUs) based pricing model, and can also lead to unexpected behavior if you have Presence enabled.
    // Initialize the instance
    
    var pubnub = PUBNUB.init({
        publish_key: 'demo',
        subscribe_key: 'demo',
        error: function (error) {
            console.log('Error:', error);
        }
    })
  2. In the case where a client will only read messages and never publish to a channel, you can simply omit the publish_key when initializing the client:
     Always set the UUID to uniquely identify the user or device that connects to PubNub. This UUID should be persisted, and should remain unchanged for the lifetime of the user or the device. Not setting the UUID can significantly impact your billing if your account uses the Monthly Active Users (MAUs) based pricing model, and can also lead to unexpected behavior if you have Presence enabled.
    // Initialize for Read Only Client
     
    var pubnub = PUBNUB({
        subscribe_key: 'demo'
    });
  3. Set a custom UUID to identify your users.
     Always set the UUID to uniquely identify the user or device that connects to PubNub. This UUID should be persisted, and should remain unchanged for the lifetime of the user or the device. Not setting the UUID can significantly impact your billing if your account uses the Monthly Active Users (MAUs) based pricing model, and can also lead to unexpected behavior if you have Presence enabled.
    var pubnub = PUBNUB({
    	publish_key: 'myPublishKey',
    	subscribe_key: 'mySubscribeKey',
    	uuid: 'myUniqueUUID'
    });
  4. It is possible to define custom logging and actions through the use of callbacks:
     Always set the UUID to uniquely identify the user or device that connects to PubNub. This UUID should be persisted, and should remain unchanged for the lifetime of the user or the device. Not setting the UUID can significantly impact your billing if your account uses the Monthly Active Users (MAUs) based pricing model, and can also lead to unexpected behavior if you have Presence enabled.
    // Initialize the instance
    
    var pubnub = PUBNUB.init({
        publish_key: 'demo',
        subscribe_key: 'demo',
        error: function (error) {
            console.log('Error:', error);
        }
    })
    // Subscribe with messages
     
    pubnub.subscribe({
    	channel : 'my_channel',
    	message : function( message, env, channel ){
    		// RECEIVED A MESSAGE.
    		console.log(message)
    	},
    	connect : function(){
    		console.log("Connected")
    	},
    	disconnect : function(){
    		console.log("Disconnected")
    	},
    	reconnect : function(){
    		console.log("Reconnected")
    	},
    	error : function(){
    		console.log("Network Error")
    	}, 
    })
  5. This examples demonstrates how to enable PubNub Transport Layer Encryption with SSL. Just initialize the client with ssl set to true. The hard work is done, now the PubNub API takes care of the rest. Just subscribe and publish as usual and you are good to go.

     Always set the UUID to uniquely identify the user or device that connects to PubNub. This UUID should be persisted, and should remain unchanged for the lifetime of the user or the device. Not setting the UUID can significantly impact your billing if your account uses the Monthly Active Users (MAUs) based pricing model, and can also lead to unexpected behavior if you have Presence enabled.
    var pubnub = PUBNUB({
        subscribe_key: 'my_subkey',
        publish_key: 'my_pubkey',
        ssl: true
    });
  6. When working with any non-web JavaScript-based client (such as a mobileJS-based client, like PhoneGap, Titanium, etc), you must use this slightly-modified method of instantiation:
    
    var pubnub = PUBNUB({
    	publish_key: 'demo',
    	subscribe_key: 'demo'
    });
    
    Now you then access PubNub methods via pubnub’s Global class methods:
    
    // Publish a welcome message
    
    pubnub.publish({
    	channel: 'my_channel',
    	message: 'Hello from the PubNub Javascript SDK',
    	callback : function(m){
    		console.log(m)
    	}
    });
    
  7. Sometimes you are using a lot of Multiplexed channels which when combined with SSL will cause slowdowns on page changes. If you have the following combination of scenarios, then you will want to use noleave option:
    • SSL or JSONP transports are used.
    • Client subscribes to more than 5 multiplexed channels.
    • Multi-Page Application
    For single page apps, the noleave option is not required.
    Disabling Presence Leave Events
     
    Disabling leaves will have the side-affect of faster page unload times. If this feature is enabled, the Presence system may take up to 5 minutes (default) to detect if a client has left a channel. Set the heartbeat higher to adjust this time down.
    // Initialize w/ leave events disabled
    
    var pubnub = PUBNUB({
    	noleave       : true,
    	publish_key   : 'demo',
    	subscribe_key : 'demo'
    })
  8. Windowing improves battery savings and throughput. Messages are bundled and compressed yielding faster response times. Enabling windowing will allow the PubNub Real Time Network the time needed to bundle, compress and optimize messages for high-throughput.
    Windowing 1000 ms will allow 100 messages in a second to be bundled and compressed at optimal speeds.
    By specifying a longer window, you receive significant performance improvements and optimized performance. For high throughput applications (Applications that send many messages per second) a long enough window will benefit in performance.
    // Init w/ optimized connection
     
    var pubnub = PUBNUB({
        windowing     : 1000,    // MILLISECONDS
        publish_key   : 'demo',
        subscribe_key : 'demo'
    });
  9. The JavaScript library will automatically detect disconnects in near real-time regardless of keepalive value. The Default keepalive is 60 seconds.
    However, in rare cases keepalive has been used to detect disconnections of the network connection; situations where a network cable was unplugged for example. By reducing the keepalive interval you can receive greater precision to detect rare edge-case drops, at the expense of higher bandwidth and reduced battery life. It is not recommended to reduce this value lower than 30 seconds.
    Specifying keepalive value
    // Init w/ shorter keepalive interval
    
    var pubnub = PUBNUB({
    	keepalive     : 30,
    	publish_key   : 'demo',
    	subscribe_key : 'demo'
    });
  10. Requires Access Manager add-on XRequires that the Access Manager add-on is enabled for your key. See this page on enabling add-on features on your keys:

    http://www.pubnub.com/knowledge-base/discussion/644/how-do-i-enable-add-on-features-for-my-keys.
     

    Anyone with the secret_key can grant and revoke permissions to your app. Never let your secret key be discovered, and to only exchange it / deliver it securely. Only use the secret_key on secure environments such as Node.js application or other server-side platforms.

    When you init with secret_key, you get root permissions for the Access Manager. With this feature you don't have to grant access to your servers to access channel data. The servers get all access on all channels.

    For applications that will administer PAM permissions, the API is initialized with the secret_key as in the following example:
     Always set the UUID to uniquely identify the user or device that connects to PubNub. This UUID should be persisted, and should remain unchanged for the lifetime of the user or the device. Not setting the UUID can significantly impact your billing if your account uses the Monthly Active Users (MAUs) based pricing model, and can also lead to unexpected behavior if you have Presence enabled.
    var pubnub = PUBNUB({
        subscribe_key: 'my_subkey',
        secret_key: 'my_secretkey'
    });
    Now that the pubnub object is instantiated the client will be able to access the PAM functions. The pubnub object will use the secret_key to sign all PAM messages to the PubNub Network.
These functions are used to set/get a user ID on the fly.
To set/get UUID you can use the following method(s) in WebOS SDK
  1. ParameterTypeRequiredDescription
    uuidStringYesUUID to set.
  2. This method doesn't have any parameters.

 Always set the UUID to uniquely identify the user or device that connects to PubNub. This UUID should be persisted, and should remain unchanged for the lifetime of the user or the device. Not setting the UUID can significantly impact your billing if your account uses the Monthly Active Users (MAUs) based pricing model, and can also lead to unexpected behavior if you have Presence enabled.
pubnub.set_uuid("myUniqueUUID")
pubnub.get_uuid()
  1. var unique_channel = PUBNUB.uuid();
     
    // initialize
     
    var pubnub = PUBNUB ({
    	subscribe_key : 'sub_key',
    	publish_key : 'pub_key'
    });
     
    //subscribe to unique channel
     
    pubnub.subscribe ({
    	channel : unique_channel,
    	message : function(m){
    		console.log(m)
    	}
    });
  2.  Always set the UUID to uniquely identify the user or device that connects to PubNub. This UUID should be persisted, and should remain unchanged for the lifetime of the user or the device. Not setting the UUID can significantly impact your billing if your account uses the Monthly Active Users (MAUs) based pricing model, and can also lead to unexpected behavior if you have Presence enabled.
     var custom_uuid = PUBNUB.uuid();
     
     var pubnub = PUBNUB({
         subscribe_key: 'my_subkey',
         publish_key: 'my_pubkey',
         uuid: custom_uuid
     });
    
  3.  var auth_key = PUBNUB.uuid();
     
     var pubnub = PUBNUB({
         subscribe_key: 'my_subkey',
         publish_key: 'my_pubkey',
         auth_key: auth_key
     });
This function provides the capability to reset a user's auth_key.
Typically auth_key is specified during initialization for PubNub Access Manager enabled applications. In the event that auth_key has expired or a new auth_key is issued to the client from a Security Authority, the new auth_key can be sent using auth().
To Set Authentication Key you can use the following method(s) in the WebOS SDK
  1. ParameterTypeRequiredDescription
    auth_keyStringYesSpecifies auth_key to use to determine User-Level Access Manager permissions.
pubnub.auth(auth_key='my_new_authkey')
None.