Platform

Custom Embedded Tabs

Custom embedded tabs display HTML content in the client interface. Learn how to create custom embedded tab definitions for Cisco Jabber.

Note

The Jabber embedded browser does not support cookie sharing with pop-ups from SSO enabled webpages. The content on the pop-up window may fail to load.

Custom Embedded Tab Definitions

The custom embedded tab can only be configured using the jabber-config.xml file. The following XML snippet shows the structure for custom tab definitions: 
<jabber-plugin-config>
	<browser-plugin>
		<page refresh="" preload="">
			<tooltip></tooltip>
			<icon></icon>
			<url></url>
		</page>
	</browser-plugin>
</jabber-plugin-config>

Cisco Jabber for Windows supports Internet Explorer version 9 or earlier. The client uses Internet Explorer in version 9 mode if a later version is on the workstation.

The following table describes the parameters for custom embedded tab definitions:
Parameter Description

browser-plugin

Contains all definitions for custom embedded tabs.

The value includes all custom tab definitions.

page

Contains one custom embedded tab definition.

refresh

Controls when the content refreshes.

  • true — Content refreshes each time users select the tab.

  • false (default) — Content refreshes when users restart the client or sign in.

This parameter is optional and is an attribute of the page element.

preload

Controls when the content loads.

  • true — Content loads when the client starts.

  • false (default) — Content loads when users select the tab.

This parameter is optional and is an attribute of the page element.

tooltip

Defines hover text for the custom embedded tab.

This parameter is optional. If you do not specify the hover text, the client will use Custom tab.

The value is string of unicode characters.

icon

Specifies an icon for the tab. You can specify a local or hosted icon as follows:

  • Local icon—Specify the URL as follows: file://file_path/icon_name

  • Hosted icon—Specify the URL as follows: http://path/icon_name

You can use any icon that the client browser can render can render, including .JPG, .PNG, and .GIF formats.

This parameter is optional. If you do not specify an icon, the client loads the favicon from the HTML page. If no favicon is available, the client loads the default icon.

url

Specifies the URL where the content for the embedded tab resides.

The client uses the browser rendering engine to display the content of the embedded tab. For this reason, you can specify any content that the browser supports.

This parameter is required.

User Custom Tabs

Users can create their own custom embedded tabs through the client user interface.

You must enable users to create custom embedded tabs. Set true as the value for the AllowUserCustomTabs parameter in your configuration file as follows: 
<Options>
  <AllowUserCustomTabs>true</AllowUserCustomTabs>
</Options>

Note

User custom embedded tabs are set to true by default.

Custom Icons

To achieve optimal results, your custom icon should conform to the following guidelines:

  • Dimensions: 20 x 20 pixels

  • Transparent background

  • PNG file format

Chats and Calls from Custom Tabs

You can use protocol handlers to start chats and calls from custom embedded tabs. Make sure the custom embedded tab is an HTML page.
  • Use the XMPP: or IM: protocol handler to start chats.
  • Use the TEL: protocol handler to start audio and video calls.

UserID Tokens

You can specify the ${UserID} token as part of the value for the url parameter. When users sign in, the client replaces the ${UserID} token with the username of the logged in user.


Tip

You can also specify the ${UserID} token in query strings; for example, www.cisco.com/mywebapp.op?url=${UserID}.

The following is an example of how you can use the ${UserID} token:

  1. You specify the following in your custom embedded tab:

    <url>www.cisco.com/${UserID}/profile</url>

  2. Mary Smith signs in. Her username is msmith.

  3. The client replaces the ${UserID} token with Mary's username as follows:

    <url>www.cisco.com/msmith/profile</url>

JavaScript Notifications

You can implement JavaScript notifications in custom embedded tabs. This topic describes the methods the client provides for JavaScript notifications. This topic also gives you an example JavaScript form that you can use to test notifications. It is beyond the scope of this documentation to describe how to implement JavaScript notifications for asynchronous server calls and other custom implementations. You should refer to the appropriate JavaScript documentation for more information.

Notification Methods

The client includes an interface that exposes the following methods for JavaScript notifications:
  • SetNotificationBadge — You call this method from the client in your JavaScript. This method takes a string value that can have any of the following values:

    • Empty — An empty value removes any existing notification badge.

    • A number from 1 to 999

    • Two digit alphanumeric combinations, for example, A1

  • onPageSelected() — The client invokes this method when users select the custom embedded tab.

  • onPageDeselected() — The client invokes this method when users select another tab.


Note

Not applicable for Jabber for iPhone and iPad

  • onHubResized() — The client invokes this method when users resize or move the client hub window.

  • onHubActivated() — The client invokes this method when the client hub windows is activated.

  • onHubDeActivated() — The client invokes this method when the client hub window is deactivated.

Subscribe to Presence in Custom Tabs

You can use the following JavaScript functions to subscribe to the presence of a contact and receive presence updates from the client:

  • SubscribePresence() — Specify a string value using the IM address of a user for this method.

  • OnPresenceStateChanged — This method enables users to receive updates from the client on the presence of a contact. You can specify one of the following values as the string:

    • IM address

    • Basic presence (Available, Away, Offline, Do Not Disturb)

    • Rich presence (In a meeting, On a call, or a custom presence state)


Note

  • If you subscribe to the presence of a person who is not on your contact list (also called temporary presence subscription), the subscription expires after 68 minutes. After the subscription expires, you must re-subscribe to the person’s presence in order to continue to receive presence updates.

  • Jabber for iPad and iPhone only supports OnPresenceStateChanged.

Get Locale Information in Custom Tabs

You can use the following JavaScript functions to retrieve the current locale information of a contact from the client:

  • GetUserLocale() — This method enables users to request locale information from the client.

  • OnLocaleInfoAvailable — This method enables users to receive locale information from client. You can use a string value that contains the client locale information.


Note

Jabber for iPad and iPhone only supports OnLocaleInfoAvailable.

Example JavaScript

The following code is an example of an HTML page that uses JavaScript to display a form into which you can input a number from 1 to 999: 
<html>
        <head>
                <script type="text/javascript">   
                                 function OnPresenceStateChanged(jid, basicPresence, localizedPresence) 
                                 {
                                          var cell = document.getElementById(jid);
                                          cell.innerText = basicPresence.concat(", ",localizedPresence);                                                   
                                 }              
                                                           
                                 function GetUserLocale()
                                 {
                                          window.external.GetUserLocale();
                                 }
                                                           
                                 function SubscribePresence() 
                                 {
                                          window.external.SubscribePresence('johndoe@example.com');
                                 }
                                                           
                                 function OnLocaleInfoAvailable(currentLocale)
                                 {
                                          var cell = document.getElementById("JabberLocale");
                                          cell.innerText = currentLocale;
                                 }
 
                                 function onHubActivated()
                                 {
                                          var cell = document.getElementById("hubActive");
                                          cell.innerText = "TRUE";
                                 }
                                                                
                                 function onHubDeActivated()
                                 {
                                          var cell = document.getElementById("hubActive");
                                          cell.innerText = "FALSE";
                                 }
 
                                 function onHubResized()
                                 {
                                          alert("Hub Resized or Moved");
                                 }                              
                                                                
                                 function OnLoadMethods()
                                 {
                                          SubscribePresence();
                                          GetUserLocale();
                                 }
                     </script>
               </head>
 
               <body onload="OnLoadMethods()">
                     <table>
                                 <tr>
                                             <td>John Doe</td>
                                             <td id="johndoe@example.com">unknown</td>
                                 </tr>
                    </table>
                    <table>
                                 <tr>
                                             <td>Jabber Locale: </td>
                                             <td id="JabberLocale">Null</td>
                                 </tr>
                                 <tr>
                                             <td>Hub Activated: </td>
                                             <td id="hubActive">---</td>
                                 </tr>     
                   </table>
               </body>
 
</html>

To test this example JavaScript form, copy the preceding example into an HTML page and then specify that page as a custom embedded tab.

Show Call Events in Custom Tabs

You can use the following JavaScript function to show call events in a custom tab:

OnTelephonyConversationStateChanged — An API in the telephony service enables the client to show call events in a custom embedded tab. Custom tabs can implement the OnTelephonyConversationStateChanged JavaScript function. The client calls this function every time a telephony conversation state changes. The function accepts a JSON string that the client parses to get call events.

The following snippet shows the JSON that holds the call events:

{
      "conversationId": string,
      "acceptanceState": "Pending" | "Accepted| | "Rejected",
      "state": "Started" | "Ending" | "Ended",
      "callType": "Missed" | "Placed" | "Received" | "Passive" | "Unknown",
      "remoteParticipants": [{participant1}, {participant2}, …, {participantN}],
      "localParticipant": {
      }
}

Each participant object in the JSON can have the following properties:

{
      "voiceMediaDisplayName": "<displayName>",
      "voiceMediaNumber": "<phoneNumber>",
      "translatedNumber": "<phoneNumber>",
      "voiceMediaPhoneType": "Business" | "Home" | "Mobile" | "Other" | "Unknown",
      "voiceMediaState": "Active" | "Inactive" | "Pending" | "Passive" | "Unknown",
}

The following is an example implementation of this function in a custom embedded tab. This example gets the values for the state and acceptanceState properties and shows them in the custom tab.

function OnTelephonyConversationStateChanged(json) {
      console.log("OnTelephonyConversationStateChanged");
      try {
        var conversation = JSON.parse(json);
        console.log("conversation id=" + conversation.conversationId);
        console.log("conversation state=" + conversation.state);
        console.log("conversation acceptanceState=" + conversation.acceptanceState);
        console.log("conversation callType=" + conversation.callType);        
      }
      catch(e) {
        console.log("cannot parse conversation:" + e.message);
      }
    }

The following is an example implementation of this function with all possible fields:

function OnTelephonyConversationStateChanged(json) {
      console.log("OnTelephonyConversationStateChanged");
      try {
        var conversation = JSON.parse(json);
        console.log("conversation state=" + conversation.state);
        console.log("conversation acceptanceState=" + conversation.acceptanceState);
        console.log("conversation callType=" + conversation.callType);
        for (var i=0; i<conversation.remoteParticipants.length; i++) {
          console.log("conversation remoteParticipants[" + i + "]=");
          console.log("voiceMediaDisplayName=" + conversation.remoteParticipants[i].voiceMediaDisplayName);
          console.log("voiceMediaNumber=" + conversation.remoteParticipants[i].voiceMediaNumber);
          console.log("translatedNumber=" + conversation.remoteParticipants[i].translatedNumber);
          console.log("voiceMediaPhoneType=" + conversation.remoteParticipants[i].voiceMediaPhoneType);
          console.log("voiceMediaState=" + conversation.remoteParticipants[i].voiceMediaState);
        }
        console.log("conversation localParticipant=");
        console.log("  voiceMediaDisplayName=" + conversation.localParticipant.voiceMediaDisplayName);
        console.log("  voiceMediaNumber=" + conversation.localParticipant.voiceMediaNumber);
        console.log("  translatedNumber=" + conversation.localParticipant.translatedNumber);
        console.log("  voiceMediaPhoneType=" + conversation.localParticipant.voiceMediaPhoneType);
        console.log("  voiceMediaState=" + conversation.localParticipant.voiceMediaState);
      }
      catch(e) {
        console.log("cannot parse conversation:" + e.message);
      }
    }

Custom Embedded Tab Example

The following is an example of a configuration file with one embedded tab: 
<?xml version="1.0" encoding="utf-8"?>
<config version="1.0">
 <Client>
  <jabber-plugin-config>
   <browser-plugin>
     <page refresh ="true" preload="true">
     <tooltip>Cisco</tooltip>
     <icon>https://www.cisco.com/web/fw/i/logo.gif</icon>
     <url>https://www.cisco.com</url>
    </page>
   </browser-plugin>
  </jabber-plugin-config>
 </Client>
</config>

Configure Automatic Updates

Applies to: Cisco Jabber for Windows, Cisco Jabber for Mac

To enable automatic updates, you create an XML file that contains the information for the most recent version, including the URL of the installation package on the HTTP server. The client retrieves the XML file when users sign in, resume their computer from sleep mode, or perform a manual update request from the Help menu.

Note

If you use the Cisco WebEx Messenger service for instant messaging and presence capabilities, you should use the Cisco WebEx Administration Tool to configure automatic updates.

XML File Structure

XML files for automatic updates have the following structure: 

<JabberUpdate>
          <App name=”JabberWin”>
               <LatestBuildNum>12345</LatestBuildNum>
               <LatestVersion>10.5.x</LatestVersion>
               <Mandatory>true</Mandatory>
               <Message>
                  <![CDATA[<b>This new version of Cisco Jabber lets you do the
                  following:</b><ul><li>Feature 1</li><li>Feature 2</li></ul>For
                  more information click <a target="_blank"
                  href="http://cisco.com/go/jabber">here</a>.]]>
               </Message>
               <DownloadURL>http://http_server_name/CiscoJabberSetup.msi</DownloadURL>
          </App>
        </JabberUpdate>
Example XML File 1

The following is example XML file for automatic updates: 

<JabberUpdate>
<App name="JabberWin">
  <LatestBuildNum>12345</LatestBuildNum>
  <LatestVersion>9.x</LatestVersion>
  <Message><![CDATA[<b>This new version of Cisco Jabber lets you do the following:</b><ul><li>Feature 1</li><li>Feature 2</li></ul>For 
  more information click <a target="_blank" href="http://cisco.com/go/jabber">here</a>.]]></Message>
  <DownloadURL>http://http_server_name/CiscoJabberSetup.msi</DownloadURL>
</App>
</JabberUpdate>
Example XML File 2

The following is an example XML file for automatic updates for both Cisco Jabber for Windows and Cisco Jabber for Mac: 

<JabberUpdate>
	<App name="JabberMac">
  <LatestBuildNum>12345</LatestBuildNum>
  <LatestVersion>9.6.1</LatestVersion>
  <Message><![CDATA[<b>This new version of Cisco Jabber lets you do the following:</b><ul><li>Feature 1</li><li>Feature 2</li>
  </ul>For more information click <a target="_blank" href="http://cisco.com/go/jabber">here</a>.]]>
  </Message>   
  <DownloadURL>http://http_server_name/Cisco-Jabber-Mac-9.6.1-12345-MrbCdd.zip</DownloadURL>
 </App>
	<App name="JabberWin">
  <LatestBuildNum>12345</LatestBuildNum>
  <LatestVersion>9.0</LatestVersion>
  <Message><![CDATA[<b>This new version of Cisco Jabber lets you do the following:</b><ul><li>Feature 1</li><li>Feature 2
  </li></ul>For more information click <a target="_blank" href="http://cisco.com/go/jabber">here</a>.]]>
  </Message> 
  <DownloadURL>http://http_server_name/CiscoJabberSetup.msi
  </DownloadURL>
</App>
</JabberUpdate>
Before You Begin

  • Install and configure an HTTP server to host the XML file and installation package.

  • Ensure users have permission to install software updates on their workstations.

    Microsoft Windows stops update installations if users do not have administrative rights on their workstations. You must be logged in with administrative rights to complete installation.

Procedure
    Step 1   Host the update installation program on your HTTP server.
    Step 2   Create an update XML file with any text editor.
    Step 3   Specify values in the XML as follows:
    • name—Specify the following ID as the value of the name attribute for the App element:

      • JabberWin—The update applies to Cisco Jabber for Windows.

      • JabberMac—The update applies to Cisco Jabber for Mac.

    • LatestBuildNum—Build number of the update.

    • LatestVersion—Version number of the update.

    • Mandatory—(Windows clients only) True or False. Determines whether users must upgrade their client version when prompted.

    • Message—HTML in the following format: 

      <![CDATA[your_html]]>

    • DownloadURL—URL of the installation package on your HTTP server.

      For Cisco Jabber for Mac the URL file must be in the following format: 
      Cisco-Jabber-Mac-version-size-dsaSignature.zip
    Step 4   Save and close your update XML file.
    Step 5   Host your update XML file on your HTTP server.
    Step 6   Specify the URL of your update XML file as the value of the UpdateUrl parameter in your configuration file.