<jabber-plugin-config>
	<browser-plugin>
		<page refresh="" preload="" internal="">
			<tooltip></tooltip>
			<icon></icon>
			<url></url>
		</page>
	</browser-plugin>
</jabber-plugin-config>

Cisco Jabber for Windows uses the Chromium Embedded Framework to display the content on the custom embedded tabs.

Cisco Jabber for Mac uses the Safari WebKit rendering engine to display the content of the embedded tab.

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

You can allow users to specify a tab name and URL for a custom embedded tab through the client user interface. Users cannot set the other parameters for a custom embedded tab.

Set AllowUserCustomTabs to true before users can customize their tabs:

<Options>
  <AllowUserCustomTabs>true</AllowUserCustomTabs>
</Options>

Note	The default value for AllowUserCustomTabs is true.

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

• Dimensions: 20 x 20 pixels

• Transparent background

• PNG file format

You can include different versions of icons to match specific themes. See the description of the icon parameter for details.

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}.

You can use JavaScript notifications in custom embedded tabs. Jabber provides methods for JavaScript notifications. It’s beyond this guide's scope to describe how to use JavaScript notifications for asynchronous server calls and other custom implementations. See your JavaScript documentation for more information.

Important

Apple replaced their WebView object. You must use different methods on Windows and Mac now. See the example JavaScript sections for details.

Notification methods

The client includes an interface that exposes these 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 1–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 window activates.

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

Subscribe to presence in custom tabs

You can use these JavaScript methods to subscribe to a contact's presence 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	Subscriptions for people not on your contact list expire after 68 minutes. After the subscription expires, you must resubscribe to see their presence data. Jabber for iPad and iPhone only supports OnPresenceStateChanged.

Get locale information in custom tabs

You can use these JavaScript methods 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 the client. You can use a string value that contains the client locale information.

Note	Jabber for iPad and iPhone only supports OnLocaleInfoAvailable.

Adjust custom tabs to match the client theme

You can use these JavaScript methods to return the current client theme:

• QueryCurrentTheme()—This method enables you to get the current Jabber theme.

• OnThemeChanged(theme)—This method passively receives the new theme when the theme changes in Jabber.

The possible values for the theme are:

• default—The default Jabber theme

• dark—The Jabber "Dark" theme

• distinct—The Jabber "High Contrast" theme

• highcontrast—A Windows high-contrast theme

Example JavaScript for Jabber for Windows

This example shows an HTML page that uses JavaScript to display a form for inputting a number 1–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.

Example JavaScript for Jabber for Mac

Apple deprecated the NSWebView that previous Jabber releases used. The replacement, WKWebView, doesn't support window.external. For your custom embedded tabs on Mac, replace window.external with window.webkit.messageHandlers.

Here is an example of the new method.

<html> 
<h3>
    Jabber MAC
</h3>
<div style="padding: 10px;">
	<label title="" id="themestring"></label> 
	<button onclick="QueryCurrentThemeAction()">QueryCurrentTheme Action</button>
	<button onclick="SetNotificationBadgeAction()">SetNotificationBadge Action</button>
	<button onclick="GetUserLocaleAction()">GetUserLocale Action</button>
	<label title="" id="UserLocal"></label> 
	<button onclick="SubscribePresenceAction()">SubscribePresence Action</button>
	<label title="" id="Presence"></label> 
</div>

<script>

function OnThemeChanged(themeString) {
	var themeLabel = document.getElementById('themestring')
	themeLabel.innerHTML = themeString
}

function OnLocaleInfoAvailable(userLocal) {
	var localUserLabel = document.getElementById('UserLocal');
	localUserLabel.innerHTML = userLocal;
}

function QueryCurrentThemeAction() {
	var themeDiv = document.getElementById('MyTheme');
	themeDiv.style.backgroundColor = 'green';
	window.webkit.messageHandlers.QueryCurrentTheme.postMessage(null);
}

function SetNotificationBadgeAction() {
	window.webkit.messageHandlers.SetNotificationBadge.postMessage(40);
}

function GetUserLocaleAction() {
	window.webkit.messageHandlers.GetUserLocale.postMessage(null);
}

function SubscribePresenceAction() {
	window.webkit.messageHandlers.SubscribePresence.postMessage('quxie@hz.jabberqa.cisco.com');
}

function OnPresenceStateChanged(contactUri, presenceState, localizedPresenceString) {
	var Label = document.getElementById('Presence');
	Label.innerHTML =  contactUri + presenceState +  localizedPresenceString;
}

</script>
</html>

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);
      }
    }