Customizing Branding in Windows Messenger 5.0

On This Page

Summary
Appendix A: Registry Entries for Branding and Tabs
Appendix B: Visual Examples of Branding and Tabs
Appendix C: Enabling Branding through Scripting and the Registry
Appendix D: Tab scripts and XML examples
Appendix E: Technical Tab Specifications and Requirements

Summary

This document is intended for Microsoft(R) Office Live Communications Server 2003, Standard Edition administrators. It describes the Microsoft Windows(R) Messenger 5.0 client branding, and how administrators can implement branding on Windows Messenger 5.0 through Live Communications Server.

Overview of Branding

Microsoft(R) Office Live Communications Server 2003, Standard Edition administrators can brand Microsoft Windows(R) Messenger 5.0. Branding allows a company or organization deploying a Live Communications Server to provide links or actual content in the Windows Messenger window. Typically, this can include internal Web sites or information about the company. Users cannot configure branding, but they can choose whether to display the tabs where branding is displayed.

An administrator can create either a script or a registry (.reg) file that can be delivered, or pushed, to the user's computer or placed on an internal Web site for the user to download, or pull. The script or reg file contains registry entries that configure the various parts of the branding feature. The registry entries usually point to an internal Web server.

Branding Areas

Branding contains three sub-features that you, the administrator, can configure. The three sub-features are:

  • Conversation Window Image

  • Help Menu Entry

  • Tabs

Conversation Window Image

With branding you can display a custom image in the lower part of each conversation window, allowing access to a Web page that opens in the user's browser. If this portion of branding is not configured, the extra space in the lower part of the conversation window is not displayed. An administrator configures this feature by creating two entries in the HKey Local Machine (HKLM) portion of the registry hive:

  • BannerURL. Provides the image.

  • BannerLinkURL. Defines the URL of the site to be displayed when the image is clicked.

Help Menu Entry

A custom entry can be placed in the Windows Messenger Help menu, allowing for customized support for company employees. When the user clicks the menu command, a Web page is displayed in a separate browser window. An administrator configures this feature by creating two entries in the HKLM portion of the registry hive:

  • ProviderName. Provides the text to display in the Help menu.

  • HelpURL. Defines the URL of the site to be displayed when the text is clicked.

    Note: If you do not provide a ProviderName in the registry, the Help menu will not display the ‘HelpURL’ entry. You must provide both the ProviderName and HelpURL for an entry to appear in the Help menu.

Tabs

An administrator configures this feature by placing an entry in the HKLM part of the registry hive. TabURL provides the location of an XML file containing the information for all the configured tabs.

After tabs have been configured by the server administrator, Windows Messenger reads the TabURL entry in the HKLM hive. The entry points to an XML file, which is read into memory. When a user's mouse pointer hovers over a displayed tab, a ToolTip is displayed (if one has been configured in the XML file). When the user clicks a tab, Messenger takes the user to the HTML page contained in the contenturl entry in the XML file for the tab the user clicked.

Note: The Web page is displayed in the Windows Messenger main window, not in a separate browser.

Setting up the Conversation Window and the Help menu

The branding information for a SIP provider is located at:

HKLM\SOFTWARE\Microsoft\MessengerService
\ServiceProviders\{83D4679F-B6D7-11D2-BF36-00C04FB90A03}
\Branding\Your SIP Domain Name goes here\

The following strings store the data:

  • BannerURL. Sets the location of where to get the image for the branding area of the conversation window.

  • BannerLinkURL. Sets the URL to go to when the branding banner image is clicked.

  • ProviderName. Sets the name that will appear in the Help menu.

  • HelpURL. Sets the URL to go to when the branding ProviderName in the Help menu is clicked by the user.

For more information about setting up the registry entries needed for branding, see Appendix B.

Setting up Tabs

The tab information for a SIP provider is located at:

HKLM\SOFTWARE\Microsoft\MessengerService
\ServiceProviders\{83D4679F-B6D7-11D2-BF36-00C04FB90A03}
\Branding\Your SIP Domain Name goes here\

The XML file can be used to configure up to 32 tabs on the client. However, exercise some caution because a long list of tabs on a client computer using a low-resolution screen setting can become difficult for the user to manage.

The following string stores the data:

  • TabURL. Sets the name and location of the XML for the tabs.

For more information about setting up the registry entries needed for branding, see Appendix A.

There are three tags in the XML file that directly affect what the user sees. They are the image tag, the tooltip tag, and the contenturl tag. An example of an XML file for tabs follows and also appears in Appendix D.

Note: All code examples in this document are unsupported and are provided only to give you a starting point for implementing your deployment.

The following is an example of an XML file that sets up one tab:

<?xml version="1.0" ?>  
<msntabdata> 
<tab> 
   <image>http://contoso/wm5/myservice/tab1.png</image>  
   <name>SomeTAB</name> 
   <tooltip>Some Tab</tooltip>  
   <contenturl>http://contoso/stuff.html</contenturl>   
   <tabid>1</tabid> 
   <hidden>false</hidden> 
</tab> 
</msntabdata>

Note: The administrator provides the text between the <tab> and </tab> attributes.

The user at the client computer can control whether a tab appears in Messenger. This can be accomplished by using the Tab control at the bottom left corner of the main Messenger window or by clicking Tools and Show Tabs from Windows Messenger. The Tab control is not visible until at least one tab is enabled.

When a user is logged on to a Microsoft .NET–connected Web service, such as Microsoft Hotmail(R) or MSN(R), one tab, the Alert tab, is provided by .NET.

Conclusion

This document described Windows Messenger client branding, and how administrators can implement branding on Windows Messenger 5.0 through a SIP provider such as Live Communications Server. See the following appendixes for more detailed information about Registry entries for branding and tabs, visual examples of branding and tabs, enabling branding through scripting and the registry, Tab scripts and XML examples, and technical tab specifications and requirements.

Appendix A: Registry Entries for Branding and Tabs

Branding Entries

The following are the registry locations and examples for the four branding entries.

ProviderName String

This string sets the name that will appear in the Help menu.

 HKLM\Software\Microsoft\MessengerService
\ServiceProviders\
{83D4679F-B6D7-11D2-BF36-00C04FB90A03}
\Branding\Type your SIP Domain Name here\

ProviderName: Contoso Company

"REG_SZ"

BannerURL String

This string sets the location of where to get the image for the branding area of the conversation window. 

HKLM\Software\Microsoft\MessengerService
\ServiceProviders\
{83D4679F-B6D7-11D2-BF36-00C04FB90A03}
\Branding\Type your SIP Domain Name here\

BannerURL: http://contoso/wm5/tab/our-domain/banner.gif

"REG_SZ"

BannerLinkURL String

This string sets the URL to go to when the branding banner image is clicked.

 HKLM\Software\Microsoft\MessengerService
\ServiceProviders\
{83D4679F-B6D7-11D2-BF36-00C04FB90A03}
\Branding\Type your SIP Domain Name here\

BannerLinkURL: http://contoso/communications/windowsmessenger

"REG_SZ"

HelpURL String

This string sets the URL to go to when the branding ProviderName in the Help menu is clicked by the user.

HKLM\Software\Microsoft\MessengerService
\ServiceProviders\
{83D4679F-B6D7-11D2-BF36-00C04FB90A03}
\Branding\Type your SIP Domain Name here\

HelpURL: http://contoso/communications/windowsmessenger/support

"REG_SZ"

Tab Entry

The following is the registry location and example for the Tab entry.

TabURL string

This string sets the name and location of the XML file for the tabs.

HKLM\Software\Microsoft\MessengerService
\ServiceProviders\
{83D4679F-B6D7-11D2-BF36-00C04FB90A03}
\Branding\Type your SIP Domain Name here\

TabURL: http://contoso/wm5/tab/our-domain/company-tabs.xml

"REG_SZ"

Appendix B: Visual Examples of Branding and Tabs

Tabs

In this example, four tabs are configured; however, up to 32 tabs can be configured.

Figure 1 Tabs example

Figure 1 Tabs example

ToolTips

In this example, the user hovers the mouse pointer over the One tab allowing the ToolTip to display.

Figure 2 ToolTips example

Figure 2 ToolTips example

Web Page

Continuing along with this example, the user has clicked tab number 3, and the Web page configured for this tab appears within the Windows Messenger main window.

Figure 3 Web page displayed from a tab

Figure 3 Web page displayed from a tab

Conversation Window Banner

In this case, the banner has been configured to appear in the conversation window. Clicking the banner will take you to the Web page the administrator has configured. The Web page will open in a separate browser window.   

Figure 4 Conversation window banner example

Figure 4 Conversation window banner example

Help Menu Example

In this example, a custom Help menu item has been configured to display. Clicking the 'Company Help' item will take you to the Web page the administrator has configured for this entry. The Web page will open in a separate browser window.

Figure 5

Figure 5

Appendix C: Enabling Branding through Scripting and the Registry

Sample script for enabling the Branding feature.

<job id="main"> 
    <script language="JScript"> 
        var WshShell = WScript.CreateObject("WScript.Shell"); 
            try   
            { 
                WshShell.RegWrite("HKLM\\Software\\Microsoft\\MessengerService\\
ServiceProviders\\{83D4679F-B6D7-11D2-BF36-
00C04FB90A03}\\Branding\\<SIP Domain Name >\\PROVIDERNAME", 
"Contoso Company Internal Server", "REG_SZ"); 
                WshShell.RegWrite("HKLM\\Software\\Microsoft\\MessengerService\\
ServiceProviders\\{83D4679F-B6D7-11D2-BF36-
00C04FB90A03}\\Branding\\<SIP Domain Name >\\BANNERURL", 
"http://contoso/wm5/tab/myserver/contoso.gif", "REG_SZ"); 
                WshShell.RegWrite("HKLM\\Software\\Microsoft\\MessengerService\
\ServiceProviders\\{83D4679F-B6D7-11D2-BF36-
00C04FB90A03}\\Branding\\<SIP Domain Name >\\BANNERLINKURL",
 "http://contoso/internal/communications/windowsmessenger/", "REG_SZ"); 
                WshShell.RegWrite("HKLM\\Software\\Microsoft\\MessengerService\\
ServiceProviders\\{83D4679F-B6D7-11D2-BF36-
00C04FB90A03}\\Branding\\<SIP Domain Name >\\HELPURL", 
"http://contoso/companysupport/help.html", "REG_SZ"); 
            } 
            catch (e) { 
                WScript.Echo("It failed to change Server information. 
Please do it manually."); 
                WScript.Quit(); 
            } 
            WScript.Echo("It changed the Server information successfully."); 
    </script> 
</job>

The following is a sample registry file for enabling the branding feature.

Windows Registry Editor Version 5.00 
[HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\MessengerService\
ServiceProviders\{83D4679F-B6D7-11D2-BF36-00C04FB90A03}\Branding] 
[HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\MessengerService\
ServiceProviders\{83D4679F-B6D7-11D2-BF36-00C04FB90A03}\Branding\\
<SIP Domain Name >\] 
"BANNERURL"="http://contoso/wm5/tab/myserver/contoso.gif" 
"BANNERLINKURL"=
"http://contoso/internal/communications/windowsmessenger/" 
"HELPURL"="http://contoso/myserver/windowsmessenger/test/" 
"PROVIDERNAME"="Contoso Company Internal Server" 
"TABURL"="http://contoso/companysupport/tabs.xml"

Appendix D: Tab scripts and XML examples

The following example script enables the Tabs portion of branding:

<job id="main"> 
    <script language="JScript"> 
        var WshShell = WScript.CreateObject("WScript.Shell"); 
            try   
            { 
                WshShell.RegWrite("HKLM\\Software\\Microsoft\\MessengerService\\
ServiceProviders\\{83D4679F-B6D7-11D2-BF36-
00C04FB90A03}\\Branding\\
<SIP Domain Name >\\TABURL", 
"http://contoso/wm5/tab/myservice/tab.xml", "REG_SZ"); 
            } 
            catch (e) { 
                WScript.Echo("It failed to change Server information. 
Please do it manually."); 
                WScript.Quit(); 
            } 
            WScript.Echo("It changed the Server information successfully."); 
    </script> 
</job>

XML Files

The following XML file example sets up one tab:

<?xml version="1.0" ?>  
<msntabdata> 
<tab> 
  <image>http://contoso/wm5/myservice/tab1.png</image> 
  <name>MyTab</name> 
  <tooltip>MY Tab</tooltip> 
  <contenturl>http://contoso/stuff.html</contenturl> 
  <tabid>1</tabid> 
  <hidden>false</hidden> 
</tab> 
</msntabdata>

Below is an example of a slightly longer list of tabs.

<?xml version="1.0"?> 
<msntabdata> 
    <tab> 
        <image>http://contoso/wm5/myservice/news.png</image> 
        <name>News</name> 
        <tooltip>My Technology News</tooltip> 
        <contenturl>https://www.contoso.com/news</contenturl> 
        <tabid>1</tabid> 
        <hidden>true</hidden> 
    </tab> 
    <tab> 
        <image>http://contoso/wm5/myservice/sports.png</image> 
        <name>Sports</name> 
        <tooltip>Sports News</tooltip> 
        <contenturl>https://www.contoso.com/sports</contenturl> 
        <tabid>2</tabid> 
        <hidden>true</hidden> 
    </tab> 
    <tab> 
        <image>http://contoso/wm5/myservice/racing.png</image> 
        <name>Racing</name> 
        <tooltip>Racing Showtimes)</tooltip> 
        <contenturl>https://www.contoso.com/racing</contenturl> 
        <tabid>3</tabid> 
        <hidden>true</hidden> 
    </tab> 
    <tab> 
        <image>http://contoso/wm5/myservice/mygame.png</image> 
        <name>My Game</name> 
        <tooltip>My Game Stories </tooltip> 
        <contenturl>https://www.contoso.com/mygame</contenturl> 
        <tabid>4</tabid> 
        <hidden>true</hidden> 
    </tab> 
    <tab> 
        <image>http://contoso/wm5/myservice/search.png</image> 
        <name>Search</name> 
        <tooltip>Search</tooltip> 
        <contenturl>https://www.contoso.com/search</contenturl> 
        <tabid>5</tabid> 
        <hidden>false</hidden> 
    </tab> 
    <tab> 
        <image>http://contoso/wm5/myservice/traffic.png</image> 
        <name>My Traffic</name> 
        <tooltip>My Traffic</tooltip> 
        <contenturl>http://www.contoso.gov/mytraffic</contenturl> 
        <tabid>8</tabid> 
        <hidden>false</hidden> 
    </tab> 
    <tab> 
        <image>http://contoso/wm5/myservice/dinner.png</image> 
        <name>Restaurants</name> 
        <tooltip>Search for a Restaurant</tooltip> 
        <contenturl>https://www.contoso.com/restaurants</contenturl> 
        <tabid>6</tabid> 
        <hidden>true</hidden> 
    </tab> 
</msntabdata>

Appendix E: Technical Tab Specifications and Requirements

The tab content is called from the URL when each client loads, and what is served from that URL can generally be as dynamic as it needs to be. See the section "META-refresh" later in this document for more detailed information about META-refresh intervals and caching tab content. The META Refresh Mechanism in HTTP:

  • is understood by nearly all client browsers.

  • forces the task of asking for new content onto the client.

  • does not require session-tracking on the server side.

Tab Optimization

Components that need to be downloaded, such as multimedia files and Microsoft ActiveX(R) controls, add a longer download time and should not be used in a tab. Audio and video components are particularly inappropriate because they interfere with the voice communication capabilities inherent within the client.

Tab Frameset Template

The tab frameset HTML code should be served by each tab-implementing site. Within the frameset template are three distinct named frames, each with a particular purpose:

  • Main frame. The frame in which the majority of the tab-specific content appears.

  • Header frame. Used to title, or uniquely identify, the tab.

  • Footer frame. Exists mainly to store common button elements.

Set all possible spacing, padding, margins, and borders to zero (0) in the frameset HTML as shown in the following example:

Sample Tab Template
<html> 
<head> 
<title>Sample tab</title> 
<META HTTP-EQUIV="MSThemeCompatible" CONTENT="Yes">  
</head> 
<frameset rows="21,*,25" cols="1" framespacing="0" 
frameborder="0"> 
     <frame src="header.htm" 
name="header" 
frameborder="No" scrolling="No" 
noresize marginwidth="0" marginheight="0"> 
    <frame src="content.htm" 
name="main" 
frameborder="0" scrolling="auto" marginwidth="0" marginheight="0"> 
    <frame src="footer.htm" 
name="footer" 
frameborder="No" scrolling="No" noresize marginwidth="0" 
marginheight="0"> 
</frameset> 
</html>
HTML Code Within the Main Frame

The main frame is where the majority of the specific functionality of a tab should be contained; thus, Tab implementers should keep the content concise. The provided template file is a small example illustrating some of the code and concepts you can use.

Browser Compatibility

HTTPS

Content of the frame may be served securely with HTTPS (Hypertext Transfer Protocol Secure). However, the tab implementer is responsible for enforcing that there are no mixed-content warnings. All elements of the frames, framesets, images, and so forth, must be served securely to avoid the mixed-content warnings. Tab implementers are required to obtain a certificate that is issued by a common trusted root or certification authority with built-in trust in most common browsers. Certain links out of a secure tab may trigger secure or unsecure transition warnings as issued through the browser layer of the tab.

Security Settings

Various security settings regarding scripting, cookies, transitions, and the like, within the tabs are controlled through the browser control. In other words, the options selected in the browser affect what displays inside a tab. It is not always safe to assume that these settings are still at "default," so widen your test matrix accordingly.

Browser Detection

Windows Messenger requires Microsoft Internet Explorer 4.01 or later to be installed on the computer in order to display tabs.

For example, this browser and operating system combination on Microsoft Windows(R) XP has a userAgent string of:

Mozilla/4.0 (compatible; MSIE6.0; Windows NT5.1)

Messenger tab implementation does not make requests based on a client-unique userAgent string. The requests are identical to those made directly using the browser on that same computer and cannot be differentiated.

META Refresh

This section explains the syntax, refresh time, and alternatives to META refresh.

Syntax

Meta refresh syntax appears within META tags in the HEAD section of standard HTML.

<HTML>
<HEAD>
<META HTTP-EQUIV="REFRESH" CONTENT=#seconds>
</HEAD>
<BODY></BODY>
</HTML>

The content entry, #seconds, specifies the refresh interval in seconds. For as long as this page is in the browser, it will refresh periodically on that interval.

Appropriate META Refresh Time Windows

Do not set the interval shorter than would make sense, given the overall architecture of exactly how timely information is made available to the user. For example, if a server that delivers stock quotes only changes its information globally every 2 minutes, it does not make sense to have the tab refresh interval at a substantially lesser time.

User-driven changes to configuration choices within the tab (for example, adding a particular stock to track) should change the tab content immediately and force a refresh every time, and then resume the regular refresh interval.

Alternatives to META Refresh

Tab implementers may use other solutions for refreshing content, such as a server-side push of content. However, the same rules should be applied as those that should be applied to the META refresh: do not refresh content more than appropriate for the subject matter, or faster than makes sense, given the back-end infrastructure. Tab implementers should also consider whether their alternative solution is an advantage for the user experience or the operational point of view.

MSThemeCompatible META Tag

Microsoft Internet Explorer 6 supports a META tag to enable themes within the body of a Web page. The most obvious effect of themes within a Web page is to override the defaults for certain elements such as the text used for form input or general appearance of <INPUT> or <SELECT> controls and related buttons. It might take some experimentation to find all possible impacts this META tag has on the tab's design.

The META tag to declare Internet Explorer 6 theme compatibility is as follows:

<META HTTP-EQUIV="MSThemeCompatible" CONTENT="Yes">  
Cookies

Tabs can write cookies. However, tab implementers should keep in mind that users might potentially disable cookies. Tabs should provide fallback implementations for cases where the cookies are not accessible.

Tab implementers who write cookies should also be aware that Internet Explorer 6 (and thus the display engine for Messenger tabs) introduced new restrictions on third-party use and re-use of cookies per the Platform for Privacy Preferences (P3P) standards. Consult Internet Explorer 6 developer documentation for more details about P3P.

XML Descriptor Files

Windows Messenger uses XML descriptor files to identify which tabs it should display, the user interface (UI) elements for each tab, and the URL of the HTML content within the tab when it has focus.

Contents of the XML Descriptor File

The following outlines the contents of the XML descriptor file:

  • <msntabdata> The top-level container tag for an XML descriptor file. This tag should have a single <tab> child container within it.

  • <tab> The second-level container tag for an XML descriptor file. All other tags described below are child nodes of <tab>.

  • <image> The URL of the image used in the always-visible tabs area of the Messenger UI. Note that when the image is not in focus, the color is shaded blue, and the image should be designed accordingly. This must be a standard http://URL. This URL should reference a graphic in the PNG format.

  • <name> The display label of the tab. This label appears in the menus used to customize tab displays.

  • <tooltip> The text to display when a user hovers the mouse pointer over the outline tab image for this tab.

  • <contenturl> The URL where the tab content should be accessed. This URL should be pointing specifically at the tab template frameset as served from the tab implementing site, not the specific "main" content frame.

    The query string can be parsed to determine the language of the installed Messenger client and therefore can help tab implementers determine what language the tab content should be.

  • <hidden> Boolean. False shows this tab when it is first loaded (potentially unfocused) in the Messenger UI on startup, unless it is specifically disabled by user preferences. True does not show this tab, unless it is specifically enabled by user preferences.

  • <tabid> An integer value used internally by the client. For practicality, this value should be 1 (one); see <siteid> below.

  • <siteid> Specify the <siteid> tag instead of <tabid> if, and only if, you are also using Microsoft Passport service for single sign-in authentication. In this case, <siteid> should contain the integer value of the Site ID as obtained through the Passport site registration process. Do not specify both a <tabid> and a <siteid>.

Example XML descriptor file

<?xml version="1.0" ?>  
<msntabdata> 
<tab> 
  <image>https://www.contoso.com/img/demotab.png</image> 
  <name>DemoTab</name> 
  <tooltip>The demo tab</tooltip> 
  <contenturl>https://www.contoso.com/tabcontent/index.htm</contenturl> 
  <tabid>1</tabid> 
  <hidden>false</hidden> 
</tab> 
</msntabdata>
Serving Tabs with HTTPS

The tab content URL may be served secure (HTTPS), but sites should have certificates that are issued by a trusted certificate authority in Internet Explorer 6 browsers (or better yet, as many browsers as possible, in preparation for a future release, and instances where links out of the tab content need to be securely served.)

If the frameset and content URL are served secure, all images, frame sources, and any other elements required for rendering should also be served securely to avoid mixed-content warnings that can appear to the end user.

Serving secure pages may require secure-insecure transitions. Flagging secure or unsecure transitions is a user-selectable warning on most browsers. Therefore, tab implementers may want to provide a message to the user that HTTP to HTTPS transition behavior is acceptable in this situation.

Note The tab outline image file (specified by the <image> tag in the XML descriptor) must be served HTTP and will not load or render if served as HTTPS.

HTTP Errors

If a request for an element of tab content does not return HTTP status code 200 (OK), then the engine that displays tab content in Messenger tabs behaves the same as a browser would. If the element is the base URL of the request, then the user sees the error page that the browser and server in combination would ordinarily display in response. For instance, a page not found (404 error) would display either the browser's default page for 404 or whatever custom error the server (or proxy) sent back assuming that at least the host portion of the URL was resolvable.

Missing elements, such as style sheets or scripts, will not load, and consequences of this are identical to the same behavior as a tab loaded into a browser. Missing images show the browser's default missing-image placeholder. If an Outline tab image is missing, code within Messenger handles this 404 error specifically and displays a question-mark image in the tab outline area. However, this only indicates that the image is missing (the tab content may or may not be properly accessible to the user if the tab outline corresponding with the missing image is clicked).

The fact that HTTP errors can get through to the end user and expose the underlying HTML nature of the tabs makes maintaining a constantly accessible and error-free tab source server an even higher priority. End users will not be able to differentiate that a 404 error in the tab is not a newly introduced error in Messenger itself, and there will be misrouting of support issues if any tab implementer's servers should ever fail to consistently serve valid responses.