Creating a Custom silverlight installation experiEnce
April 2009
1 Introduction
When developers create a new Silverlight project, they typically ignore the installation experience. Since the developers already have Silverlight installed, installation is not something that is visible in the development process. Furthermore, for many Silverlight developers, the default installation medallion is acceptable. The following shows the default installation experience for a user that tries to run a Silverlight-based application when they do not already have Silverlight installed.
However, for many users, this default installation experience is not acceptable.
In fact, many users do not understand that they need to click the medallion and install Silverlight to completely experience the Web site. Other users think that the medallion is a banner ad on an empty page and just skip it.
The good news is that there now are options to improve the installation experience. This whitepaper covers the programming and design aspects of how to customize the installation experience. This whitepaper is organized into the following sections:
Principles of a Good Installation Experience
Programming the Installation Experience
Designing a Compelling Installation Experience
Conclusion
This whitepaper includes the following three code samples that are packed in the accompanied zip file: “Installation Experience Sample Code.zip”
1. InstallMechanism folder – A code sample that illustrates the core installation and detection scenarios, it is targeting advanced developers. (Discussed in the Programming the Installation Experience section)
2. WebAppInstall folder – A template for a generic Web application installation experience. (Discussed in the Designing a Compelling Installation Experience section)
3. MediaAppInstall folder – A template for a Web media application. (Discussed in the Designing a Compelling Installation Experience section)
2 Principles of a Good Installation Experience
After analyzing many sites, the Silverlight team has determined that there are several important principles behind a good installation experience.
Focus on the content and articulate the value – Users need to understand the context in which Silverlight will improve their experience of the site. The site needs to be clear to the user that installing Silverlight is a clear benefit. Since most users do not know what Silverlight is, the focus should be on the content and on the experience they will get. Obviously, at the end of the process, the reward should match the promise. If there is enough value in your experience, users will want to get it.
Reduce barriers – There is a trust issue when asking users to install something. Many users have been burned by malware and it is your responsibility to address those user concerns in the following way. Use familiar and trusted brands, such as “This is a Microsoft browser plug-in”. Set expectations as to the installation process itself, such as Silverlight is free, installation is quick, and no restart is required. Provide the user with the right context throughout the installation process.
Minimize choices – When presented with the opportunity to get the new experience (and install Silverlight), you should minimize the obstructions around this presentation. In other words, you should limit the number of choices that a user is faced with. Ideally, a single install option, such as “Install” or “View content with Silverlight”, is presented. If that is not possible, a second reject option, such as “No thanks” or “View content without Silverlight”, can be also presented. Presenting only a few options funnels users to make the right decision.
Interaction – Make the decision area interactive to encourage engagement and hence encourage a decision. Interaction can be triggered by both a mouse over (make the clickable regions more attractive) and a click (providing visual feedback for actions).
Figure 1 shows a before-and-after example of an MSN entertainment Web site installation experience. The before example shows the default installation experience when you create a new Silverlight project in Expression Blend or Visual Studio. The after example shows a custom installation experience and applies the following principles of a good installation:
· Uses an image and text to describe the experience, which is a famous lady tattoo site. (Content and value)
· Explains the requirement to install Silverlight and the installation process. (Reduce barriers)
· Provides a clear call to action by including a button that shows how to proceed. (Minimize choices)
· Uses a provocative image to engage users. (Interaction)
Before / AfterFigure 1: The default installation experience versus a customized installation experience.
3 Programming the Installation Experience
This section is intended to provide you with a deep understanding of how to program a good installation experience that utilizes the principles from the previous section. If you are not interested in the specifics of the programming mechanisms underlying the installation experience, you can skip to the Designing a Compelling Installation Experience section that provides a template that follows the design principals.
The sample under the InstallMechanism folder contains the code that is discusses in this section.
3.1 Silverlight Installation States
At any time, a site that uses Silverlight is in one of the seven installation states listed in Table 1. The HTML experience should reflect these states and display the correct UI. The purpose of this section is to show you how to identify these states reliably and how to display the correct UI.
Installation State / DescriptionThe correct version of Silverlight is installed and loaded / This state occurs when the correct version of Silverlight is already installed. The Silverlight application should just run and display the content.
The correct version of Silverlight is installed but not loaded / This state occurs after updating Silverlight to a new version while on a Web site that uses an older version. The old version will still be loaded in the browser and will prevent loading the new version that is already installed. In this case, the browser must be restarted. When this state is identified, you should prompt the user to restart the browser before coming back to the page to view the content.
An older version of Silverlight is installed / This state occurs when a user has an older version of Silverlight installed and the page requires a newer version. The page should convey that an upgrade to the new version of Silverlight is required and also set them up to restart the browser once installation is complete. As noted in the previous section, it is good to focus on the value of the content to entice users to update.
Upgrade started / This state occurs when a user starts the update process. In general, it is good to indicate to users that they are in this transient state. It is recommended to set their expectations and inform them that the upgrade is under way. Once the upgrade is complete, they’ll have to restart the browser.
Silverlight is not installed / This state indicates that there is no version of Silverlight installed and that users need to install Silverlight to view the content. As noted in the previous section, it is good to focus on the value of the content to entice users to install.
Install started / This state occurs when a user starts the installation process. In general, you should indicate to users that they are in this transient state. It is recommended to set their expectations and inform them that the installation is under way. Once the installation is complete, they may have to refresh the browser.
Incompatible Configuration / This state represents an incompatible configuration, in which you should display appropriate HTML content to the user that indicates the compatibility issue or display an alternative HTML experience. Although Silverlight covers the vast majority of PC and Macintosh browsers, there some incompatible configurations.
Table 1: Silverlight Installation states.
Figure 2 summarizes these installation states and associated prompts, the colors indicate connected states (i.e. when user enters a state, the next logical state has the same color):
Figure 2: Silverlight installation states.
The <object> tag for Silverlight and the Silverlight SDK contain components that help you build the right installation experience and detect the different installation states. The following lists these components:
· The <object> tag for Silverlight – Provides parameters to detect the version installed and the version required. It also provides a mechanism to display the right HTML experience.
· Silverlight.js - If referenced, refreshes the browser automatically after a Silverlight installation. It also contains some APIs that determine the state.
· Silverlight.supportedUserAgent.js - If referenced, contains code for detecting an incompatible configuration.
3.2 Task 1. Integrate Silverlight.js and Use the <object> Tag
The following steps describe how to integrate the Silverlight.js file and use the <object> tag for Silverlight.
3.2.1 Step 1. Integrate Silverlight.js
Silverlight.js is included by using a <script> tag within the page’s <head> tag. This JavaScript file defines the required APIs and includes the code required to check whether Silverlight is already installed.
head
script src="Silverlight.js" type="text/javascript" </script
</head
3.2.2 Step 2. Use an <object> Tag for Silverlight
The Web page must embed Silverlight on the page by using an HTML <object> tag. This must include the data and type attributes. By default, Silverilght projects use “application/x-silverlight-2” as the MIME type for these attributes. By doing this, you force the user to upgrade the plug-in with minimal impact on the Web site author.
Therefore, the data and type attributes should be defined like this:
data="data:application/x-silverlight,"
type="application/x-silverlight"
Note that in order to detect the installation state for Silverlight 1.0 users (a rare case), you should consider using the Silverlight 1.0 MIME type for both the data and type attributes
3.2.3 . Step 3. Use the minRuntimeVersion Parameter
The minRuntimeVersion parameter is part of the <object> tag that is used to ensure that the user has the correct version of Silverlight installed. If not, the plug-in will not download the XAP, and instead will ask the user to upgrade the plug-in. Additionally, this state will trigger the OnError event with the args.ErrorCode set to 8001 [Upgrade Required] or 8002 [Restart Required]. Silverlight.js will handle these events automatically, unless one wants to capture these for custom UI.
Checking the error state is not enough to see if an action is required on the part of the end user. Only by following the steps in this whitepaper and by using Silverlight.js can this be achieved.
The correct value for the minRuntimeVersion parameter is “2.0.31005” for the released version of Silverlight 2.
Note Silverlight 1.0 did not support this parameter.
3.2.4 Step 4. Use the autoUpgrade Parameter
When the autoUpgrade parameter is true, the user will see the default upgrade experience when a later version of Silverlight is required. If you want to control this with your own experience, set this parameter to false.
Note that you can test this upgrade experience by creating a Silverlight plug-in on a page by setting the data and type attributes and the minRuntimeVersion and autoUpgrade parameters to the following:
object data="data:application/x-silverlight,"
type="application/x-silverlight">
<param name="minRuntimeVersion" value="9.9.99999" />
<param name="autoUpgrade" value="true" />
</object
3.2.5 Step 5. Turn on Error Handling with onError
The OnSilverlightError function is designed to capture generic and instantiation errors from the Silverlight runtime. In general, the function is silently handling errors but in some cases developers would like to capture specific errors and emit customized UI.
The object> tag must use the onError parameter and its definition function must call Silverlight.IsVersionAvailableOnError(sender,args) that handles some of the errors that relate to version compatibility.
If this function returns true, then the correct version of Silverlight is already installed and loaded so that normal error handling code should be executed.
So, if the parameter on the <object> tag looks like this:
param name="onError" value="onSilverlightError" />
You would have a handler that looks like this:
function onSilverlightError(sender, args)
{
if ( Silverlight.IsVersionAvailableOnError(sender, args) ) {
//run error handling code
}
}
3.2.6 Step 6. Handle the onLoad Event
The onLoad parameter of the <object> tag must define a handler function that must call Silverlight.IsVersionAvailableOnLoad(sender) . Calling this function allows you to identify earlier versions of Silverlight 2, such as beta builds, and trigger an upgrade or restart in order to handle them.
So, if the parameter on the <object> tag looks like this:
param name="onLoad" value="onSilverlightLoad" />
You would have a handler that looks like this:
function onSilverlightLoad (sender)
{
Silverlight. IsVersionAvailableOnLoad (sender);
}
In the InstallMechanism sample, this handle is implemented in script in the default.html file.
3.2.7 Step 7. Address Incompatible Configurations
While the Silverlight plug-in is available for installation by a majority of the Internet's users, there are some platforms that are not currently supported. When users on an unsupported platform click the Silverlight installation URL, they are redirected to a Web page on www.microsoft.com/silverlight that informs them that they are not supported. This experience is fine for some pages, but some Web sites need to be able to identify these users without redirecting to www.microsoft.com. There are two primary methods to detect unsupported platforms:
1. Identify the user as being unsupported server-side based on the HTTP request.
2. Identify the user as being unsupported client-side based on navigator.userAgent.
A default implementation of client-side supported user detection is available in Silverlight.supportedUserAgent.js (http://code.msdn.microsoft.com/SLsupportedUA). Since this implementation is based on string parsing, it is easy to port to a server-side implementation of your choice.
If the detection is done server-side, then the page can conditionally replace the installation HTML with HTML that tells the user that their platform is unsupported. If client-side detection is used, then it should accomplish the same goal, but in a fashion that is used in the Reminding Firefox Users to Restart” section later.
It is very important to note that as Web browsers and the Silverlight runtime evolve, the supported user agent detection code will also change. Therefore, you should check the Silverlight.supportedUserAgent Web page (http://code.msdn.microsoft.com/SLsupportedUA) often to ensure that you have the latest version.