Follow Jabber Voice Best Practices

There are a number of technical limitations imposed by working within a browser sandbox and adapting to its process model. Supporting a wide range of browsers and OSes adds more challenges. In this blog post I will try to outline the gotchas you may run into when developing your own application using the Cisco Jabber SDK.

Phone instances

The native plug-in supports a single login per machine. All Cisco Jabber SDK instances in the current browser process share the same registration. The native plug-in automatically unregisters when the last instance of an object tag in the current browser process is unloaded. This means that, to keep the phone registered, a phone object tag must exist on the page at all times - either in an iframe, or in a page that refreshes itself using AJAX, and does not reload.

Using Cisco Jabber SDK (phone) on multiple browsers at the same time and on the same machine.

This is not supported. Cisco Jabber SDK returns an error when you attempt to register with a code of 18 (LoggedInElseWhere) "Already logged in".

Using Cisco Jabber SDK (phone) on multiple tabs/windows at the same time within the same browser.

This is supported on browsers which load the plug-in in one process only.

Mozilla Firefox 3.x, 4.0.1+, Apple Safari 4.x, 5, Microsoft Internet Explorer 7, Google Chrome (all versions tested so far) work across multiple tabs.

Microsoft Internet Explorer 8 and 9 launch multiple processes each of which may own one or more tabs. A separate instance of the native plug-in is loaded into each process. Any tabs that share the same process as the first one to register will share the same phone; all other tabs return an error similar to the one in Using Cisco Jabber SDK (phone) on multiple browsers at the same time and on the same machine.

Using Cisco Jabber SDK (phone) on multiple machines at the same time with the same user and device.


This is not supported. Cisco Unified Communications Manager terminates any old connections and transfers the device to the newest connection. Note that the disconnected Jabber SDK native plug-in instances will try to re-establish connection and the connection ownership will move back and forth between machines possibly resulting in dropped/missed calls.

Notifications

If Cisco Jabber SDK is running in a tab that is not in focus or the browser is minimised, the native plug-in will start an audio ring and an event is sent to the JavaScript app to indicate an incoming phone call.
To make it easy to answer a call quickly, a visual notification to the user is required so they don't have to search for the tab that contains the phone.

Popup windows

The simplest, most flexible and most widely supported is a simple popup window (JavaScript window.open). The drawback is that the user may have popups blocked.

HTML5 web notifications


HTML5 has a draft for Web Notifications which are similar to single-purpose popup windows. The application has to ask permission from the user to allow these notifications and they only allow a single click event. There is no flexibility to allow answer, divert to voice-mail, escalate to IM, and so on from the notification alone.

HTML5 web notifications are only available on Google Chrome at present, but are at a W3C draft spec stage so should have broader support in the future.

Unloading page while on a call

The Cisco Jabber SDK browser plug-in automatically ends any softphone-based calls, and unregister itself shortly after the last tab containing a plug-in object is closed. If you require more fine-grained functionality than this, You can use the following JavaScript window events:

window.onbeforeunload

This is the window event handler to implement if you want to ask the user to continue or stop when closing a tab or navigating away from your app while on a call. Note that there can only be one onbeforeunload handler attached to the window. Also note that you cannot set the text of the message in Firefox 4 (by design). See this mozillaZine article for details.

window.onunload

Performing Cisco Jabber SDK operations (or indeed any JavaScript) in onunload can cause exceptions because part of the Document Object Model(DOM) (for example the browser native plug-in object) may be unloaded already and JavaScript variables may already be garbage collected.

jQuery

Cisco Jabber SDK is implemented as a jQuery plug-in. This means that jQuery is a prerequisite for using the API. ciscobase.js provides jQuery 1.4.2 by default, but does not conflict with any other versions of jQuery you may already have loaded.

Asynchronous calls


Cisco Jabber SDK is by nature asynchronous and event-driven. This means that SDK API calls complete and return quickly, but the results from them may be deferred to callbacks or separate event handlers.

One of the drawbacks of passing function references as callbacks is that you can lose the scope of the original function (that is, "this" is no longer what you expect it to be).

For inline anonymous functions the value of this can be assigned to a variable inside an outer closure and referenced inside your callback (for example "that" or "self").

 

1var that = this;
2jQuery('#anchor').cwic('operation',{callback: function(args) {
3    that.doSomething(args);
4}});


To pass member functions to callbacks and retain "this" scope when called a pattern such as the following helps:

1boundFunction = (function(scope, method) {
2    return function() {
3        var ret = method.apply(scope, arguments);
4        return ret;
5    }
6}(this, this.mymethod));
7
8jQuery(domNode).cwic('operation',{callback: boundFunction})