Optimizing the Silverlight Installation Experience

Before users can view Silverlight content through their Web browsers, they are required to download and install the Microsoft Silverlight plug-in on their computer. Web sites that want to deliver rich content and information by using the Silverlight plug-in must create installation experiences that entice users to start, approve, and complete the Silverlight installation process. These experiences should remind users of why they want to install Silverlight, show users that the hosting Web site trusts Silverlight, and remove roadblocks to Silverlight installation and usage. This overview provides best practices and methods for providing an integrated and branded installation experience for new users of Microsoft Silverlight.

This overview contains the following sections:

Definitions

Implementing a Compelling Silverlight Installation Experience

  • Designing the Default Experience
  • Designing the Installation Experience

Sample Installation <DIV> Design

Integrating the Installation Experience and Default Experience

Definitions

  • Default experience – What a user sees when viewing a Silverlight-enabled page from a browser that already has an appropriate version of Silverlight installed.
  • Installation experience – What a user sees when viewing a Silverlight-enabled page from a browser that does not have the correct version of Silverlight installed.
  • Surrounding experience (surrounding content) - The theme or general look of the HTML page that surrounds the embedded Silverlight plug-in. For full-page Silverlight applications, this term does not apply.
  • Silverlight placeholder element - The HTML element that contains the Silverlight plug-in. In this overview, a DIV is used to contain and position the Silverlight plug-in.

Implementing a Compelling Silverlight Installation Experience

The two design goals for implementing a compelling Silverlight installation experience are as follows:

  • Create a clear incentive for customers to install Silverlight.
  • Eliminate confusion to prevent users from completing their installation.

To accomplish these goals, follow these high-level design guidelines:

  • Provide a glimpse or indication of what the Silverlight-enabled content looks like.
  • Communicate to the customer that they need to “Get Silverlight” and explain the installation experience.
  • Use the Silverlight installation prompt without changes to ensure a consistent experience for users.

Keeping these points in mind, use the following steps to implement a compelling Silverlight installation experience.

  1. Design the default experience of your page.
  2. Design the installation experience of your page.
  3. Tie the two experiences together.

Designing the Default Experience

We will use an example of a Halo-branded Silverlight mini-site to illustrate the design recommendations in this overview. In the case of our Halo site, the default experience (see Definitions above) is captured in the following screen image.

Default experience for Halo site

Default Halo experience

The default experience can typically be split into two distinct portions. The first portion is the area defined by the Silverlight placeholder element that contains the Silverlight plug-in (see Definitions). In this overview, an HTML DIV is used as the Silverlight placeholder element (called Silverlight <DIV> from now on). This Silverlight <DIV> defines the area of the screen that is used to display Silverlight content. The second portion is the surrounding content. The surrounding content, typically in HTML, includes images, links, navigation elements, and branded images. Taking our example, we can split the screen into the two portions as shown in the following illustration.

Silverlight <DIV> and surrounding content

Silverlight DIV and surrounding content

When your surrounding content (see Definitions) is defined, you can use it as a basis for designing your installation experience.

Designing the Installation Experience

The goal of the installation experience is to fill the Silverlight plug-in with meaningful content along with the Silverlight installation prompt when the control is not available. Because the Silverlight <DIV> typically has predefined dimensions, designers can create alternate content of that size, which can be inserted when the control is not available.

Designing the installation experience

Designing the installation experience

Designer should keep the following points in mind when they implement the installation experience content to be inserted into the Silverlight <DIV>:

  • The <DIV> must contain a child <DIV> in which the Silverlight installation prompt will be placed. This child <DIV> must be at least 206 pixels wide and as tall as the generated installation prompt for your locale. The English prompt, for example, is 148 pixels high. Make sure that this <DIV>is free of content, because it will be populated by Silverlight.js.
  • The <DIV> should not contain any JavaScript code, which will be broken if the <DIV>’s contents are dynamically replaced.
  • The <DIV> should contain additional graphical elements that entice users to click “Get Microsoft Silverlight”.
  • The <DIV> should maintain stylistic continuity with the surrounding content.
  • The <DIV> should provide users with post-installation steps if necessary.

The <DIV> should include text that points out that some users will need to restart their browsers when installation is complete. The recommended text is defined in the following table. You can determine which text to use by inspecting two properties of Silverlight.js: Silverlight.ua.Browser and Silverlight.available.

  • Silverlight.ua.Browser is a string property that defines the browser type detected by Silverlight.js.
  • Silverlight.available is a Boolean that is set to true if some version of Silverlight has been installed on the user’s computer.
Silverlight.ua.Browser Silverlight.available Text to present to users
MSIE False "When installation is complete, refresh (F5) your browser to activate your Silverlight content."

Alternatively, you can use InstallAndCreateSilverlight.js, as described below, and choose not to display additional text to these users.
MSIE True "When installation is complete, restart your browser to activate your Silverlight content."
Firefox False "When installation is complete, restart your browser to activate your Silverlight content."
Firefox True "When installation is complete, restart your browser to activate your Silverlight content."
Safari False "When installation is complete, restart your browser to activate your Silverlight content."
Safari True "When installation is complete, restart your browser to activate your Silverlight content."
Unsupported False "Your browser may not be supported by Microsoft Silverlight. Please visit https://www.microsoft.com/silverlight/system-requirements.aspx for more information."
Unsupported True "Your browser may not be supported by Microsoft Silverlight. Please visit https://www.microsoft.com/silverlight/system-requirements.aspx for more information."

Alternatively, you can use a single text string to cover all of these experiences. The recommended text in this case is:

"You may have to restart your browser to complete installation."

However, this will create sub-optimal installation experiences for users of Internet Explorer who do not have Silverlight installed.

Sample Installation <DIV> Design

The installation <DIV> for this sample will entice the user to install Silverlight by presenting them with a grayed-out image of the content that will be shown if they install Silverlight. In addition, text that asks the user to install Silverlight and to restart the browser if necessary will be added to the image.

To generate the grayed-out image, follow these steps:

  1. Create an image of the active control.
  2. Modify the image to notify the user that the page is not yet live and requires user action.
  3. Add text that directs the user to install Silverlight and to restart their browser if needed.

1. Create an image of the active control.

You can create the image by loading the default experience into a Web browser (Silverlight must be installed) and capturing the screen bypressing ALT+PRINT SCREEN while the browser window is active. You can then paste the screen capture from the Clipboard into an image editor, and edit the image to contain only the portion of the screen taken up by the Silverlight <DIV>. This portion should have the same dimensions as the Silverlight <DIV> itself. Finally, save the image for additional processing.

Capturing the image

Capturing the image

2. Modify the image.

Next, modify the image to visually indicate that the control is not live. This can be accomplished by graying out the entire image. Depending on your installation experience and the design of your site, other methods may prove more successful. To gray out the image, open it in an image editor. Next, add a layer on top of the image layer. Give the new layer a white background, and then reduce the layer’s opacity to about 40%.

Graying out the image

Graying out the image

3**. Add text to guide the user.**

Finally, add text to the image to encourage the user to click "Get Microsoft Silverlight". You can also leave room below this text to embed the Silverlight installation prompt and to provide the post-installation guidance text. In this sample, the text reads "To view this video you need to install Microsoft Silverlight by clicking the button below." on top and "You may have to restart your browser to complete installation" on the bottom. This text was added to the image by inserting another layer to the grayed out image and positioning text areas on this layer.

Adding text

Adding text

Now that the background image is complete, you can create HTML code to be injected into the Silverlight <DIV> to display the installation experience.

Completed background image

Completed background image

Implementing the Installation Experience

At this point, you should have three sets of resources: the site's surrounding content, the Silverlight content, and a background image for the installation experience. You can now add the appropriate JavaScript and HTML to tie these resources together.

The following code shows the JavaScript and HTML for the Halo example.

HTML
<DIV style="text-align:left; auto; height:716px; background-image:url(installImage.jpg);">
        <DIV style=” padding-left:392px; padding-top:350px;”>
                  <DIV ID=”InstallPromptDiv”>
                  </DIV>
        </DIV>
        <DIV ID="PostInstallGuidance" style="width:auto; height:auto; padding-top:20px;text-align:center; 
                  color:#D2E9F2; font-weight:bolder; font-size:medium;">
      </DIV>
      <script type="text/javascript">
	if ( Silverlight.ua.Browser == "MSIE" )
	{
	    if ( Silverlight.available )
	    {
		PostInstallGuidance.innerHTML="";
                  }
	    else
                  {
		PostInstallGuidance.innerHTML="When installation is complete,<br />restart your " + 
                                              "browser to activate your Silverlight content.";
	    }
	}
	else if ( Silverlight.ua.Browser == "Firefox" || Silverlight.ua.Browser == "Safari")
	{
	    PostInstallGuidance.innerHTML="When installation is complete,<br />restart your browser " +
                                            "to activate your Silverlight content.";
	}
	else
	{
	    PostInstallGuidance.innerHTML="Your browser may not be supported by Microsoft " +   
                                           "Silverlight.<br />Please visit " + 
                                           "https://www.microsoft.com/silverlight/system-requirements.aspx " +
                                           "for more information.";
	}
      </script>
</DIV>

The first <DIV> in this code sample is a container that defines the width, the height, and the background image, which was created in the previous step. This <DIV> contains two other <DIV>s. The first <DIV> is used to give the correct layout to the InstallPromptDiv, which is its child element. The second <DIV>, PostInstallGuidance, provides the correct layout and font for the post-installation guidance text that was defined in the previous table. Finally, there is a <script> element that populates the post-installation guidance text.

Integrating the Installation Experience and Default Experience

YOu integrate the two experiences that have been built into a single page by using JavaScript. This overview uses a helper file called InstallAndCreateSilverlight.js to help with this integration. This section will first cover the reference implementation of Silverlight.InstallAndCreateSilverlight(...). Next, it will present some simplified HTML to represent a page whose installation experience is to be modified. Finally, it will integrate InstallAndCreateSilverlight(...) into this HTML to tie the installation experience with the default experience.

InstallAndCreateSilverlight.js
The InstallAndCreateSilverlight.js file is a reference implementation of the method called Silverlight.InstallAndCreateSilverlight, which instantiates Silverlight as soon as installation is complete. Currently, this implementation is only supported in Internet Explorer on Windows. On other supported platforms, this method will have the same effect as calling CreateSilverlight directly. However, as an added benefit, the method’s implementation will simplify building an optimized installation experience across all platforms.

JavaScript
if(!window.Silverlight)
    window.Silverlight={};
Silverlight.InstallAndCreateSilverlight = function(version, SilverlightDiv, installExperienceHTML, installPromptDivID, createSilverlightDelegate)
{
    var RetryTimeout=3000; //The interval at which Silverlight instantiation is attempted(ms)	
    if ( Silverlight.isInstalled(version) )
    {
	createSilverlightDelegate();
    }
    else
    {
	if ( installExperienceHTML && SilverlightDiv )
	{
	    SilverlightDiv.innerHTML=installExperienceHTML;
	    document.body.innerHTML;
	}
               if (installPromptDivID)
               {
	    var installPromptDiv = document.GetElementById(installPromptDivID);
	    if ( installPromptDiv )
	          installPromptDiv.innerHTML = Silverlight.createObject(null, null, null, {version: version, inplaceInstallPrompt:true},{}, null);
               }
        	TimeoutDelegate = function()
	{
	    Silverlight.InstallAndCreateSilverlight(version, null, null, null, createSilverlightDelegate);
	}
	setTimeout(TimeoutDelegate, RetryTimeout);
    }
}

Silverlight.InstallAndCreateSilverlight takes the arguments shown in the following table. All of these arguments are required to use the method.

Argument Type Description Sample value
version String The version of Silverlight which is required on this site. Equivalent to the version parameter to Silverlight.createObject. '1.0'
SilverlightDiv   The <DIV> that should be populated with the installation experience if Silverlight is not available. This is typically the same argument as that which is passed as the Parent Element (pe) in Silverlight.CreateObject document.getElementById('SilverlightDiv')
installExperienceHTML   A string that represents the HTML to be shown in the SilverlightDiv if Silverlight has not already been installed. Pass null if this HTML is being rendered in a different way. '<DIV style=”.../DIV>'
installPromptDivID Object The <DIV> that should contain the installation prompt if Silverlight is not available on the client. 'InstallPromptDIV'
createSilverlightDelegate Method The method that should be called to instantiate the Silverlight control when installation is complete. If Silverlight is already present on the client, this method will be called immediately. CreateSilverlight

Required Script File References

To implement the branded installation experience, the page will need to reference three files:

  • Silverlight.js
  • CreateSilverlight.js
  • InstallAndCreateSilverlight.js

Each file should be referenced in the <HEAD> element of the page. You should use the latest version of Silverlight.js from the Silverlight 1.0 SDK and not modify the file in any way. CreateSilverlight.js should contain the CreateSilverlight method, which contains the call to Silverlight.CreateObject using the appropriate parameters for the control. Both of these files are described in this overview. InstallAndCreateSilverlight.js should contain the implementation of Silverlight.InstallAndCreateSilverlight described previously or a different implementation that respects the same API.

Sample HTML

The following pseudo-HTML represents the resources for the branded, Silverlight-enabled page.

HTML
<html>
<head>
<title>My Application</title>
<script type=”text/javascript” src=”Silverlight.js”></script>
<script type=”text/javascript” src=”CreateSilverlight.js”></script>
<script type=”text/javascript” src=”InstallAndCreateSilverlight.js”></script>
</head>
<body>
    … <!-- Surrounding Content -->
      <div id=”SilverlightDIV”>
          <script type=”text/javascript>
             createSilverlight();
          </script>
      </div>
   … <!-- Surrounding Content -->
</body>
</html>

Implementing the Installation Experience

To add the installation experience by default, modify the HTML as shown in the following code.

HTML
  ... <!-- Surrounding Content -->
      <div id=”SilverlightDIV”>
      </div>
  ... <!-- Surrounding Content -->
   //Create the install experience html
   var installExperienceHTML =  '<div style="position:auto; text-align:left; background-repeat:no-repeat; height:477px; background-image:url(assets/faded_preinstall.png);">'; 
       installExperienceHTML += '<div style="padding-left:212px; padding-top:170px;">';
       installExperienceHTML += '<div id="InstallPromptDiv"> </div> </div> <div id="PostInstallGuidance"'; 
       installExperienceHTML += 'style="width:auto; font-weight:bold; font-size:18px; font-family:sans-serif; height:auto; padding-top:20px;text-align:center; color:#3366ff; ';
       installExperienceHTML += 'font-weight:normal; font-size:11pt"> </div> </div>';
  //calls installandcreatesilverlight method to instantiate silverlight once it is installed
  Silverlight.InstallAndCreateSilverlight('1.0', 
			document.getElementById('divPlayer_0'), 
			installExperienceHTML,
			'InstallPromptDiv',
			createSilverlight);
   </script>

This HTML contains three major changes:

  1. The script tag is moved outside the Silverlight <DIV>.
  2. The predesigned installation HTML is moved into a string that can be passed to InstallAndCreateSilverlight.
  3. The call to CreateSilverlight is replaced with a call to InstallAndCreateSilverlight.

If Silverlight is not installed, the call to InstallAndCreateSilverlight will add the installation HTML and the Silverlight direct installation prompt to InstallPromptDiv. This will enable the user to install the product from within the branded installation experience. When Silverlight is detected as being installed, InstallAndCreateSilverlight calls CreateSilverlight, which injects the Silverlight object into the Silverlight <DIV>. When it does so, it replaces the installation experience content with the final Silverlight content.

Replacing the installation experience with final content

Replacing the installation experience with final content

Opportunities for Optimization

  • Develop a dedicated installation page that implements this experience. Have other pages redirect if Silverlight is not available.
  • Have your CreateSilverlight delegate account for calling each CreateSilverlight method associated with the page to avoid showing multiple installation prompts.

Common Errors

  • The call to InstallAndCreateSilverlight must take place outside the Silverlight <DIV> to avoid synchronization errors.
  • The call to SetTimeout in InstallAndCreateSilverlight should be the last statement in the method to avoid synchronization errors.

See Also

Brushes Overview
VideoBrush Overview

Overviews and How-to Topics