Local Connection between Silverlight Applications



Creating a Custom silverlight installation experiEnce

April 2009

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.

[pic]

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)

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)

|[pic] |[pic] |

|Before |After |

Figure 1: The default installation experience versus a customized installation experience.

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.

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 |Description |

|The correct version of Silverlight is |This state occurs when the correct version of Silverlight is already installed. The Silverlight |

|installed and loaded |application should just run and display the content. |

|The correct version of Silverlight is |This state occurs after updating Silverlight to a new version while on a Web site that uses an older|

|installed but not loaded |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 |This state occurs when a user has an older version of Silverlight installed and the page requires a |

|installed |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):

[pic]

Figure 2: Silverlight installation states.

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

2 Task 1. Integrate Silverlight.js and Use the Tag

The following steps describe how to integrate the Silverlight.js file and use the tag for Silverlight.

1 Step 1. Integrate Silverlight.js

Silverlight.js is included by using a tag within the page’s tag. This JavaScript file defines the required APIs and includes the code required to check whether Silverlight is already installed.

2 Step 2. Use an Tag for Silverlight

The Web page must embed Silverlight on the page by using an HTML 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 . Step 3. Use the minRuntimeVersion Parameter

The minRuntimeVersion parameter is part of the 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.

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:

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 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 tag looks like this:

You would have a handler that looks like this:

function onSilverlightError(sender, args)

{

if ( Silverlight.IsVersionAvailableOnError(sender, args) ) {

//run error handling code

}

}

6 Step 6. Handle the onLoad Event

The onLoad parameter of the 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 tag looks like this:

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.

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 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 . 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 (). 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 () often to ensure that you have the latest version.

3 Task 2. Render the UI Prompts at the Appropriate Time

Earlier in Figure 2, you saw a state diagram that identified the five main prompts that need to be provided to the user:

[pic]

Figure 2: Silverlight installation states.

Figure 2: Silverlight installation states. The green state is when the correct version of Silverlight is installed and loaded, so the content is displayed to the user without further prompting.

The red path in the diagram is followed when the user does not have Silverlight installed. In this case, they should be first prompted with a “Click to Install” and once installation is done they should be requested to refresh their browser (unless you are using Silverlight.js, in which case this is done automatically).

The yellow path is followed when the user has Silverlight, but it is an older version. In this case, users should be prompted with a “Click to Upgrade” message and once installation is done, they should be prompted to restart their browser.

The orange path is followed when the correct version of Silverlight is detected, but it hasn’t been loaded. In this case the user should be prompted to restart their browser.

The gray path is followed when an incompatible configuration is detected.

Note The sub-states on the yellow and red paths are not automatically detected. You will have to generate these prompts in response to the user selecting the “Click to Install” or “Click to Upgrade” options. You will see how to do this later in this whitepaper.

To summarize, the following list contains the six states where the user needs to be provided with the right user interface:

• Silverlight is not installed, click to install.

• You are now installing Silverlight, refresh when done.

• An older version of Silverlight is installed, click to upgrade.

• You are not upgrading Silverlight, restart when done.

• Please restart your browser.

• Incompatible configuration HTML.

Note The actual UI is very important and is discussed in more detail later in Designing a Compelling Installation Experience.

1 Step 1. Define the HTML for Silverlight Not Being Installed

The tag definition allows you to render HTML that shows when the object cannot be created. This will display when Silverlight is not installed. This is very straightforward to do. One way is to add a tag after the parameters that render the HTML.

Note Somewhere in this HTML, you should capture a click and use it to run a JavaScript function. This JavaScript is necessary to render the installing message.

Here’s an example of a fully formed tag that contains HTML. The actual implementation the is mentioned in section 3.6 includes also other sections that are needed to address other states (such as Firefox restart scenarios)

The above HTML defines an image (images/install.PNG) to show when Silverlight isn’t installed. You can replace this image with a custom HTML experience of your own that is tailored to the site. If you want to implement a simple HTML HREF link , you can just link the Silverlight installation URL; however, in order to change the state of the UI once the link is clicked you need to have an onclick event handler ; You’ll explore that in Step 3.

2 Step 2. Define UI for Prompt States

The other four prompt states can be defined as JavaScript variables and are implemented as such in the InstallMechanism sample.

The variables that are used for the states in this example are:

• var PromptFinishInstall for “You are now installing Silverlight, refresh when done.”

• var PromptUpgrade for “An older version of Silverlight is installed, click to upgrade.”

• var PromptFinishUpgrade for “You are not upgrading Silverlight, restart when done.”

• var PromptRestart for “Please restart your browser.”

• var PromptIncompatible for “Your browser is incompatible with this experience.”

In a case of a simple UI, these could simply be HTML div elements that replace the innerHTML of a portion of your page when you need to issue that prompt to the user.

Note that the PromptUpgrade variable should have a call to a JavaScript function when an area within it is clicked (similar to the prompt in Step 1). This JavaScript function changes the onscreen prompt to the “You are now upgrading Silverlight, restart when done” state. You’ll see this in Step 3.

Here’s an example of the PromptUpgrade variable. Note the definition of the onclick event handler:

var PromptUpgrade =

"" +

" " +

"";

3 Step 3. Define JavaScript Functions to Handle User Actions for Install and Upgrade

In Step 1, you defined the prompt to solicit the user to click an area on your page to install Silverlight. The response to this should be to trigger the download of the installer, and to update the screen to inform the user that they are not in the installation state.

The JavaScript to achieve this looks like this:

function InstallClicked()

{

window.location = "";

document.getElementById("silverlightControlHost").innerHTML =

PromptFinishInstall;

}

Note that it changers the innerHTML property of the tag to the value of PromptFinishInstall as defined in Step 2.

In Step 2, when defining the upgrade prompt, you specified an onClick event handler named UpgradeClicked. This is similar to the InstallClicked event handler in that it downloads the software and changes the prompt. The prompt changes one that indicates to finish the upgrade.

function UpgradeClicked()

{

window.location = "";

document.getElementById("silverlightControlHost").innerHTML =

PromptFinishUpgrade;

}

4 Task 3. Capture the Callbacks from Silverlight.js

Silverlight.js has some helper functions that trap the different states and allows you to update the UI accordingly. The following lists the helper functions:

• Silverlight.onRequiredVersionAvailable

The correct version of Silverlight is installed and available. You can use this to let the user know that they are good to go, or just ignore it and render the content.

• Silverlight.onRestartRequired

You need to restart the browser. In this case, you will change the prompt HTML to the contents of your PromptRestart variable.

• Silverlight.onUpgradeRequired

You need to upgrade from an older version of Silverlight. In this case, you will change the prompt HTML to the contents of your PromptUpgrade variable.

• Silverlight.onInstallrequired

Silverlight isn’t installed but needs to be. You don’t need to take any action here as you are capturing this state in the tag.

The following shows the code for these helper functions that are called by the isVersionAvailableOnLoad function; the functions, are implemented as empty functions in Silverlight.js:

function onSilverlightLoad(sender)

{ Silverlight.IsVersionAvailableOnLoad(sender); }

Silverlight.onRequiredVersionAvailable = function(){ };

Silverlight.onRestartRequired = function()

{ document.getElementById("silverlightControlHost").innerHTML =

PromptRestart; };

Silverlight.onUpgradeRequired = function()

{ document.getElementById("silverlightControlHost").innerHTML =

PromptUpgrade; };

Silverlight.onInstallRequired = function() { };

5 Exploring the Finished Page with the Installation Experience

Visual Studio creates a default HTML page to host your Silverlight content. It’s fairly easy to follow the previous steps to upgrade this default installation experience to one that manages the installation states described earlier.

Here’s the complete listing, with the new sections highlighted.

Silverlight Installation Mechanism Sample

html, body {

height: 100%;

overflow: auto;

}

body {

padding: 0;

margin: 0;

}

#silverlightControlHost {

height: 100%;

}

var PromptFinishInstall = "You are now installing Silverlight, refresh your browser when done.";

var PromptUpgrade = "This application needs you to upgrade the Silverlight plugin that runs it. An older version is installed. Click here to upgrade it.";

var PromptFinishUpgrade = "You are now upgrading Silverlight. When this is done, please restart your browser.";

var PromptRestart = "Please restart your browser.";

var PromptNotSupported = "This browser doesn't support Silverlight, sorry!";

function onSilverlightError(sender, args) {

if (Silverlight.IsVersionAvailableOnerror(sender, args)) {

var appSource = "";

if (sender != null && sender != 0) {

appSource = sender.getHost().Source;

}

var errorType = args.ErrorType;

var iErrorCode = args.ErrorCode;

var errMsg = "Unhandled Error in Silverlight 2 Application " + appSource + "\n";

errMsg += "Code: " + iErrorCode + " \n";

errMsg += "Category: " + errorType + " \n";

errMsg += "Message: " + args.ErrorMessage + " \n";

if (errorType == "ParserError") {

errMsg += "File: " + args.xamlFile + " \n";

errMsg += "Line: " + args.lineNumber + " \n";

errMsg += "Position: " + args.charPosition + " \n";

}

else if (errorType == "RuntimeError") {

if (args.lineNumber != 0) {

errMsg += "Line: " + args.lineNumber + " \n";

errMsg += "Position: " + args.charPosition + " \n";

}

errMsg += "MethodName: " + args.methodName + " \n";

}

throw new Error(errMsg);

}

}

function onSilverlightLoad(sender) {

Silverlight.IsVersionAvailableOnLoad(sender);

}

Silverlight.onRequiredVersionAvailable = function() {

};

Silverlight.onRestartRequired = function() {

document.getElementById("silverlightControlHost").innerHTML = PromptRestart;

};

Silverlight.onUpgradeRequired = function() {

document.getElementById("silverlightControlHost").innerHTML = PromptUpgrade;

};

Silverlight.onInstallRequired = function() {

};

function UpgradeClicked() {

window.location = "";

document.getElementById("silverlightControlHost").innerHTML = PromptFinishUpgrade;

}

function InstallClicked() {

window.location = "";

document.getElementById("silverlightControlHost").innerHTML = PromptFinishInstall;

}

function CheckSupported() {

var tst = Silverlight.supportedUserAgent();

if (tst) {

// Do nothing

}

else {

document.getElementById("silverlightControlHost").innerHTML = PromptNotSupported;

}

}

This application needs you to use the Silverlight plugin. Click here to install it.

try {

if (navigator.plugins["Silverlight Plug-In"].description) {

document.getElementById("SLInstallFallback").innerHTML = PromptRestart;

}

}

catch (e) {

}

6 Working Around Known Upgrade Issues

There are two known issues that affect users upgrading from Silverlight 1.0 or Silverlight 2 beta to the released version of Silverlight 2. Both issues have been fixed in Silverlight 2 and will not affect future releases of Silverlight. The two issues are:

• Users of Firefox for Windows will see the tag's fallback experience after they upgrade to Silverlight 2 until they restart their browser.

• Macintosh users are sometimes misidentified as being in the upgrade required state when they are actually in the restart required state.

1 Reminding Firefox Users to Restart

Users of Firefox for Windows may sometimes experience a problem when Silverlight is upgraded from Silverlight 1.0 or a Silverlight 2 beta to the final Silverlight 2 release. The browser sometimes considers Silverlight to be broken until the browser is restarted. Thinking that Silverlight is not installed, the browser will display the inner HTML of the tag for Silverlight, which is the plug-in's installation experience. Unfortunately, there is not a straightforward way to identify whether a browser has Silverlight installed. Therefore, it is useful to replace the tag’s inner HTML with the page's restart message when the user is identified as having Silverlight installed on Firefox. If the user is experiencing this problem, then they will be asked to restart. Otherwise, they will not see the fallback HTML and will simply enjoy the application.

The logic for this workaround looks like this:

if ( the user is on Firefox and has Silverlight installed)

{

replace the tag's inner HTML with the restart prompt

}

In the InstallMechanism code sample Default.html page, the workaround requires two changes:

First, name the div element that contains the installation HTML.

Second, add JavaScript that is evaluated after this div element is created. Have that JavaScript verify that the user is on Firefox with Silverlight installed. If they are, replace the contents of the named div element with the PromptRestart HTML.

2 Detecting aRequired Restart on the Macintosh

The Silverlight.js component that detects the restart required state is not very reliable on Macintosh when upgrading from Silverlight 1.0 or a Silverlight 2 beta (which are rare cases as not many people have these versions anymore). Empirical evidence shows that the user will see the right content once and then will be reverted to the upgrade required state. There is no known workaround for this issue, but it is mitigated by several factors:

• When a user upgrades from Silverlight 2 to the next version, the detection code will work as expected.

• This only affects users who upgrade and then do not follow the installer and on-page instructions to restart the browser.

• The upgrade message will ask the user to re-upgrade, which in turn will re-remind them to restart their browser.

Designing a Compelling Installation Experience

The different states of the installation experience were described earlier in Table 1 and Figure 2. This section describes the UI for these states to optimize the installation experience for a generic Web application and a Web media application.

1 Recommended UI for an Installation Experience

The installation experience UI for a generic Web application and a Web media application follow a common pattern. The recommended UI for a generic Web application is illustrated in Figure 3.

[pic]

Figure 3: The recommended installation experience UI for a generic Web application.

The recommended UI for a Web media application is illustrated in Figure 4.

[pic]

Figure 4: The recommended installation experience UI for a Web media application.

These UI patterns use different elements as described in Table 2.

|# |Element |Description |

|1 |Header Text |Text that is the name of the application. Another way to think about this is as the answer to|

| | |the question: “What is this?” |

|2 |Main text |Text that explains the value of the application and asks users to click and continue. Another|

| | |way to think about this is as the answer to the question: “What is in this for me? Why should|

| | |I click?” |

|3 |Button |The call to action, which will trigger the installation. |

|4 |Application/Media image |Area for an image that is relevant to the application. For the generic Web application, the |

| | |image in the content area can be a screenshot of the actual application. For the Web media |

| | |application, the image is typically a grayed out sample frame from the video. |

|5 |Powered By Silverlight Logo |Text or a logo that sets the user’s expectations that Silverlight is required. Note that you |

| | |can get access to the logo by clicking the following link: |

| | |() |

Table 2: Installation experience elements.

Later in this section, you will learn how to create the following two examples that are based on the principles of this whitepaper:

1. This first example is a small online game called “The Amazing Soccer Online Game”. It is a generic Web application installation experience that is consistent with Figure 3.

[pic]

Figure 5: An example of the installation experience UI for a generic Web application.

2. The second example is a video playback application called “The Best Countdown” that shows an award winning video clip. It is a Web media application installation experience that is consistent with Figure 4.

[pic]

Figure 6: An example of the installation experience UI for a Web media application.

2 Recommended Installation Experience Text for a Generic Web Application

The following table lists the recommended installation experience text for “The Amazing Soccer Online Game”. The header clearly describes the application: “The Amazing Soccer Online Game”, The button text clearly articulates the call to action: Update (your browser with Silverlight) and Play (the game). For line-of-business applications, you can use Update and Start instead. The main text articulates the value of the game and clearly describes the status of the installation states.

|Installation State |Header Text |Main Text |Button Text |

|Silverlight is installed and loaded|not required as the |not required as the Silverlight content is presented |not required as the |

| |Silverlight content is | |Silverlight content |

| |presented | |is presented |

|The correct version of Silverlight |The Amazing Soccer Online |You are almost ready to play soccer online. |None |

|is installed but not loaded |Game |Please restart the Web browser to continue and play. | |

|An older version of Silverlight is |The Amazing Soccer Online |The Amazing Soccer online game is the best online game |“Update and Play” |

|installed |Game |of 2009. The game includes: | |

| | |Amazing 2D/3D animations and special effects | |

| | |Smooth, high quality HD video of real EUFA games  | |

| | |Enhanced playability, 40% faster than before | |

| | |Click below the update your browser with Microsoft | |

| | |Silverlight and Play. | |

|Upgrade started |The Amazing Soccer Online |You are almost ready to play soccer online. |None |

| |Game |Please wait for the installation update to complete and| |

| | |then restart your browser. | |

|Silverlight is not installed |The Amazing Soccer Online |The Amazing Soccer online game is the best online game |“Update and Play” |

| |Game |of 2009. The game includes: | |

| | |Amazing 2D/3D animations and special effects | |

| | |Smooth, high quality HD video of real EUFA games  | |

| | |Enhanced playability, 40% faster than before | |

| | |Click below the update your browser with Microsoft | |

| | |Silverlight and Play. | |

|Install started |The Amazing Soccer Online |You are almost ready to play soccer online. |None |

| |Game |Please wait for the installation update to complete. | |

| | |You may need to refresh your browser once installation | |

| | |is done by pressing F5. | |

|Incompatible configuration |The Amazing Soccer Online |This browser is not compatible with this online game. |NA |

| |Game | | |

Table 3: Installation experience textfor a generic Web application.

3 Recommended Installation Experience Text for a Web Media Application

The following table lists the recommended installation experience text for “The Best Countdown” video experience.

|Installation State |Header Text |Main Text (70 words) |Button Text |

|Silverlight is installed and |NA |NA |NA |

|loaded | | | |

|The correct version of Silverlight|The Best Countdown |You are ready to watch the video. Please restart the |None |

|is installed but not loaded | |Web browser to play the countdown video. | |

|An older version of Silverlight is|The Best Countdown |Watch the video highlights of the best countdown. |“Update and Watch” |

|installed | | | |

| | |To watch, you need to update your browser with the | |

| | |Microsoft Silverlight technology. Clicking installs | |

| | |the update and then plays the video. | |

|Upgrade started |The Best Countdown |You are almost ready to watch the Best Countdown. |None |

| | |Please wait for the installation update to complete, | |

| | |and then restart your Web browser. | |

|Silverlight is not installed |The Best Countdown |Watch the video highlights of the best countdown. |“Update and Watch” |

| | | | |

| | |To watch, you need to update your browser with the | |

| | |award-winning Microsoft Silverlight technology. | |

| | |Clicking installs the update and then plays the | |

| | |video. | |

|Install started |The Best Countdown |You are almost ready to watch the Best Countdown. |None |

| | |Please wait for the installation update to complete. | |

|Incompatible configuration |The Best Countdown |This browser is not compatible with this video |NA |

Table 5: Installation experience text for a Web media application.

4 Generic Web Application Installation Experience Example

This section contains instructions on how to create a generic Web application installation experience for “The Amazing Soccer Online Game”. The template for this example is in WebAppInstall folder included with this whitepaper.

The generic Web application template has the following folder structure:

[pic]

- The ClientBin folder contains the Silverlight application.

- The CSS folder contains CSS files that are used in this design.

- The Images folder has images that are used in the installation experience (and also contain a specific image that you can customize).

- The js folder contains the small file that implements the states of the installation.

- The root folder contains the default HTML file and also the two standard script files that are part of the Silverlight SDK for supporting the installation. The default HTML file is the file that you will customize. The Customized_Default.html file contains the completed customizations that are described in this section.

The generic Web application supports three form factors (as described later) that will fit different sizes of the Silverlight plug-in.

The following sections provide five simple steps to customize the generic Web application installation experience (Step 5 is optional).

1 Enter Your HTML Snippets in the Default.html File

To customize the button text and provide a custom image, you will need to edit the appropriate sections in the Default.html file. The following shows a non-customized Default.html file. The highlighted sections can be customized. Note that the code can generate three installation experience form factors (wide, narrow, and small) that are determined by the size of the plug-in. If your plug-in size is dynamic, you will need to customize all of the form factors.

|Silverlight.inject( |

|{ |

|source: "ClientBin/InstallUXTest.xap", |

|parentElement: "silverlightControlHost", |

|properties: |

|{ |

|width: "100%", |

|height: "100%", |

|background: "white", |

|version: "2.0.31005.0" |

|}, |

|// Contextual ui configuration |

|installerUiConfig: |

|{ |

|// The title of the application |

|title: "Generic Silverlight Web Application", |

| |

|// The path of the image to display |

|// For optimal results use an image that is 165x124 pixels in size |

|picture: "images/wide/light.jpg", |

| |

|// Leave the entire 'description' section commented out to get the default |

|// descriptions.; The default text is specified in js/AgInstall.js. |

|// |

|// Note: If the custom text is shorter than the default text, some of the images |

|// in the UI will be out of place,. Tto address this, add an appropriate number of |

|// paragraphs or breaks before or after the custom text. See 'install: wide' below |

|// for an example. |

|/*description: |

|{ |

|install: |

|{ |

|wide: "Add custom description and 'installation required' text here.", |

|narrow: "Add custom description and 'installation required' text here.", |

|small: "Add custom description and 'installation required' text here." |

|}, |

|upgrade: |

|{ |

|wide: "Add custom description and 'upgrade required' text here.", |

|narrow: "Add custom description and 'upgrade required' text here.", |

|small: "Add custom description and 'upgrade required' text here." |

|}, |

|// To use the default text for a section, comment out the lines with custom text |

|installing, remember to keep the commas at the end of the lines as neccesary: |

|{ |

|//wide: "Add custom 'Silverlight is installing/upgrading' text here.", |

|//narrow: "Add custom 'Silverlight is installing/upgrading' text here.", |

|//small: "Add custom 'Silverlight is installing/upgrading' text here." |

|}, |

|restart: |

|{ |

|wide: "Add custom 'Please restart browser' text here.", |

|narrow: "Add custom 'Please restart browser' text here.", |

|small: "Add custom 'Please restart browser' text here." |

|}, |

|notSupported: |

|{ |

|wide: "Add custom 'browser not compatible' text here.", |

|narrow: "Add custom 'browser not compatible' text here.", |

|small: "Add custom 'browser not compatible' text here." |

|} |

|},*/ |

|// Specify the custom text of the install button/link here. |

|// In the large and narrow forms, an arrow graphic element is included. |

|// In the small, text-only form, you can specify a > with > |

|// For example:, "Update and Go! >" |

|buttonLabel: "UPDATE AND START" |

|} |

|}); |

After replacing the highlighted sections with your HTML snippets, the Default.html file looks like this:

|Silverlight.inject( |

|{ |

|source: "ClientBin/InstallUXTest.xap", |

|parentElement: "silverlightControlHost", |

|properties: |

|{ |

|width: "100%", |

|height: "100%", |

|background: "white", |

|version: "2.0.31005.0" |

|}, |

|// Contextual UI configuration |

|installerUiConfig: |

|{ |

|// The title of the application |

|title: "The Amazing Soccer Online Game", |

| |

|// The path of the image to display |

|// for optimal results use an image that is 165x124 pixels in size |

|picture: "images/wide/soccer.jpg", |

| |

|// Leave the entire 'description' section commented out to get the default. |

|// descriptions;. The default text is specified in js/AgInstall.js. |

|// |

|// Note: Iif the custom text is shorter than the default text, some of the images |

|// in the UI will be out of place,. To address this, add an appropriate number of |

|// paragraphs or breaks before or after the custom text. See 'install: wide' below |

|// for an example. |

|// |

|// Also, if you comment out just a single form factor, remember to remove the comma from the end of the line as it will break the experience |

|on IE6 and IE7 |

|// |

| |

|description: |

|{ |

|install: |

|{ |

|wide: "The Amazing Soccer online game is the best online game of 2009. The game is powered by the Microsoft Silverlight and |

|includes:Amazing 2D/3D animations and special effectsSmooth, high quality HD video of real UEFA gamesEnhanced |

|playability that is 40% faster than beforeClick below to update your Web browser with Microsoft Silverlight and play the |

|game." |

|//narrow: "Add custom description and 'installation required' text here.", |

|//small: "Add custom description and 'installation required' text here." |

|}, |

|upgrade: |

|{ |

|wide: "The Amazing Soccer online game is the best online game of 2009. The game is powered by the Microsoft Silverlight and |

|includes:Amazing 2D/3D animations and special effectsSmooth, high quality HD video of real UEFA gamesEnhanced |

|playability that is 40% faster than beforeClick below to update your Web browser with Microsoft Silverlight and play the |

|game." |

|//narrow: "Add custom description and 'upgrade required' text here.", |

|//small: "Add custom description and 'upgrade required' text here." |

|}, |

|// To use the default text for a section, comment out the lines with custom text |

|installing: |

|{ |

|wide: "You are almost ready to play. Please wait for the installation update to complete. " |

|//narrow: "Add custom 'Silverlight is installing/upgrading' text here.", |

|//small: "Add custom 'Silverlight is installing/upgrading' text here." |

|}, |

|restart: |

|{ |

|wide: "You are almost ready to play. Please restart your Web browser to start playing. " |

|//narrow: "Add custom 'Please restart browser' text here.", |

|//small: "Add custom 'Please restart browser' text here." |

|}, |

| |

|notSupported: |

|{ |

|wide: "This Web browser is not compatible with this game. Try using a compatible Web browser. " |

|//narrow: "Add custom 'browser not compatible' text here.", |

|//small: "Add custom 'browser not compatible' text here." |

|} |

|}, |

|// Specify the custom text of the install button here. |

|// In the large and narrow forms, an arrow graphic element is included. |

|// In the small, text-only form, you can specify a > with > |

|// For example:, "Update and Go! >" |

|buttonLabel: "UPDATE AND PLAY" |

|} |

|}); |

2 Create your Custom Image

The template contains a 165x124 pixel image that you can create for your own installation experience. In this example, the Silverlight image was replaced with a soccer image.

[pic] [pic]

The new image is placed in the images folder and referenced from the Default.html file.

|// the path of the picture to display in the image |

|// for optimal results use an image of 165x124 pixels |

|picture: "images/wide/soccer.jpg", |

3 Adjust the Silverlight Application Source and Target Runtime Version

In the source property, specify the location of the .xap file. To specify the target runtime version for the Silverlight plug-in, you need to modify the code in Default.html as shown in the following code snippet. The released version of Silverlight 2 is 2.0.31005.0.

| Silverlight.inject( |

|{ |

|source: "ClientBin/InstallUXTest.xap", |

|parentElement: "silverlightControlHost", |

|properties: |

|{ |

|width: "100%", |

|height: "100%", |

|background: "white", |

|version: "3.0.31005.0" |

|}, |

|... |

4 Change the Title and Parameters

The title and parameters of your hosting HTML file are important too. They contain the browser header and also some key parameters that are used by search engines. Remember to adjust them.

| Amazing Soccer Game |

| |

| |

5 Update no-script experience

When script is disabled, the Silverlight.inject function will not work. In that case the DIV that is hosting the injected code will be displayed. You can customize that DIV in the HTML file to fit your experience, in our example this markup is customized as follows:

| |

|This game requires you to update your browser with the Microsoft Silverlight plugin. Click here to update. Browser restart may be required. |

| |

6 Enter Additional Data to Customize the Experience in CSS (Advanced Only)

If you want to further customize the fonts, colors, or layout for any of the form factors, the settings are specified in the CSS files that control these parameters. There is a separate CSS file for each of the form factors as follows:

• slInstallWide.css – CSS for the wide layout (custom image to the left)

• slInstallNarrow.css – CSS for the medium layout (custom image on the top)

• slInstallSmall.css – CSS for the small layout, (text-only)

Explaining each of the parameters in the three CSS files is beyond the scope of this whitepaper. However, if you are familiar with simple CSS, you can easily modify the UI for each of the form factors. For example, to change the font size, style, or color of the title text for the wide form factor, the necessary edits would be made in the appropriate section in slInstallWide.css:

[pic]

For another example, to change the font size, style, or color of the title text for the narrow form factor, the necessary edits would be made in the appropriate section in slInstallNarrow.css:

[pic]

5 Web Media Installation Experience Example

This section contains instructions on how to create a Web media application installation experience for “The Best Countdown”. The template for this example is in MediaAppInstall folder included with this whitepaper.

The Web media application template has the following folder structure:

[pic]

- The CSS folder contains CSS files that are used in this design.

- The Images folder has images that are used in the installation experience (and also contain a specific image that you can customize).

- The js folder contains the small file that implements the states of the installation.

- The root folder contains the default HTML file and also the two standard script files that are part of the Silverlight SDK for supporting the installation. The default HTML file is the file that you will customize. The Customized_Default.html file contains the completed customizations that are described in this section. Finally, the XAP file resides in the root. This is consistent with the way Expression Encoder emits code.

The media installation experience includes two form factors. The first form is selected when the application is 300x250 or larger. In this version, the play button image is displayed. If the application is smaller than 300x250, the second form is selected and the play button is not displayed. The other UI elements (text, logo, etc.) do not differ between the two versions.

The default text for the two form factors – with and without the play button image – is specified in js\AgInstall.js. If you choose not to customize any of the installation experience UI, the default text will be retrieved from AgInstall.js.

Unlike the generic Web application, the Web media application version does not have a default background image because video publishing tools, such as Expression Encoder, typically output a thumbnail image when encoding media. If you choose not to export a thumbnail during the encoding process, the background of the installation experience UI will be a uniform gray (though this background color can easily be edited in the CSS file).

If you want to customize the text displayed in the installation experience UI for either of the form factors, this is done in Default.html after the media has been published from Expression Encoder.

The following sections provide five simple steps to customize the Web media application installation experience (Step 5 is optional).

1 Enter Your HTML Snippets in the Default.html File

To customize the text and provide a custom image, you will need to edit the appropriate sections in the Default.html file. The following shows a non-customized Default.html file. The highlighted sections can be customized.

|installerUiConfig: |

|{ |

|type: AgInstall.ENCODER, |

| |

|// The title of the project |

|title: "The Best Countdown Video", |

| |

|// The path of the image to display |

|picture: "BW_countdown_leader_Thumb.jpg", |

| |

|// The size of the thumbnail |

|pictureWidth: 512, |

|pictureHeight: 384, |

| |

|// Leave the entire 'description' section commented out to get the default |

|// descriptions;. The default text is specified in js/AgInstall.js. |

|// |

|description: |

|{ |

|install: |

|{ |

|encoder:"Watch the video highlights of the best countdown." + |

|"To watch, you need to update your Web browser with " + |

|"Microsoft Silverlight. Click to install the update and then play the video." |

|}, |

|upgrade: |

|{ |

|encoder:"Watch the video highlights of the best countdown." + |

|"To watch, you need to update your Web browser with " + |

|"Microsoft Silverlight. Click to install the update and then play the video." |

|}, |

|installing: |

|{ |

|encoder: "You are almost ready to watch the action!Wait for the updates to install..." |

|}, |

|restart: |

|{ |

|encoder: "You are almost there. Please restart your Web browser to watch the video." |

|}, |

| |

|// to display the default text for inidivual items, comment out the specific items |

| |

|notSupported: |

|{ |

|encoder: "This Web browser is not compatible with this video." |

|} |

|}, |

|// The text of the install link. |

|buttonLabel: "UPDATE AND WATCH" |

2 Create your Custom Image

The template contains an image that is shown in the background. You can customize this image with something that is more appropriate.

The new image is placed in the root folder and referenced from the Default.html file.

|// the path of the picture to display in the image |

|// for optimal results use an image of the video size |

|picture: "BW_countdown_leader_Thumb.jpg", |

3 Adjust the Silverlight Application Source and Target Runtime Version

In the source property, specify the location of the .xap file. To specify the target runtime version for the Silverlight plug-in, you need to modify the code in the Default.html as shown in the following code snippet. The released version of Silverlight 2 is 2.0.31005.0.

| |

|source: "MediaPlayerTemplate.xap", |

|parentElement: "silverlightControlHost", |

|properties: |

|{ |

|width: "100%", |

|height: "100%", |

|version: "2.0.31005.0" |

|}, |

4 Update no-script experience

When script is disabled, the Silverlight.inject function will not work. In that case the DIV that is hosting the injected code will be displayed. You can customize that DIV in the HTML file to fit your experience, in our example this markup is customized as follows:

| |

|To play the Best Countdown video you are required to update your Web browser with Microsoft Silverlight. Click here to update and play. Browser restart may be required. |

| |

5 Change the Title and Parameters

The title and parameters of your hosting HTML file are important too. They contain the browser header and also some key parameters that are used by search engines. Remember to adjust them.

| The Best Countdown Video |

| |

| |

6 Enter Additional Data to Customize the Experience in CSS (Advanced Only)

If you want to customize the fonts, colors, or layout, the settings are all specified in the slInstallEncoder.css file. Explaining each of the parameters in slInstallEncoder.css is beyond the scope of this whitepaper. However, if you are familiar with simple CSS, you can easily modify the UI. For example, if you did not export a thumbnail from Expression Encoder and you want a custom background color, the following code snippet from slInstallEncoder.css shows where this color is set:

[pic]

For another example, if you want to modify the color of the title of the “Update and Start” link, the following snippet from slInstallEncoder.css shows where this color is set:

[pic]

Conclusion

This document articulated the details of implementing a proper installation experience for Silverlight applications. It drilled down on the mechanism of that implementation and also provided prescribed details on suggested effective designs for media and generic web application.

The installation experience patterns presented here, use client side script and markup to obtain the right experience. They are not using server based script models that are used by some developers (and also implemented in the wave 2 of the Silverlight development tools). Future papers will try to cover that aspect as well as articulating more advanced patterns that cover specific web content scenarios.

Regardless of the specific implementation, a well designed installation experience is a very important part of implementing a Silverlight web application and in many cases is the main factor determining if users will actually use the application.

The information contained in this document represents the current view of Microsoft Corporation on the issues discussed as of the date of publication. Because Microsoft must respond to changing market conditions, it should not be interpreted to be a commitment on the part of Microsoft, and Microsoft cannot guarantee the accuracy of any information presented after the date of publication.

This document is for informational purposes only. MICROSOFT MAKES NO WARRANTIES, EXPRESS, IMPLIED OR STATUTORY, AS TO THE INFORMATION IN THIS DOCUMENT.

Complying with all applicable copyright laws is the responsibility of the user. Without limiting the rights under copyright, no part of this document may be reproduced, stored in or introduced into a retrieval system, or transmitted in any form or by any means (electronic, mechanical, photocopying, recording, or otherwise), or for any purpose, without the express written permission of Microsoft Corporation.

Microsoft may have patents, patent applications, trademarks, copyrights, or other intellectual property rights covering subject matter in this document. Except as expressly provided in any written license agreement from Microsoft, the furnishing of this document does not give you any license to these patents, trademarks, copyrights, or other intellectual property.

Unless otherwise noted, the example companies, organizations, products, domain names, e-mail addresses, logos, people, places and events depicted herein are fictitious, and no association with any real company, organization, product, domain name, email address, logo, person, place or event is intended or should be inferred.

© (2009) Microsoft Corporation. All rights reserved.

Microsoft, Silverlight, Visual Studio, and Expression, are either registered trademarks or trademarks of Microsoft Corporation in the United States and/or other countries.

-----------------------

.slInstall .slHeadlineWide

{

font-weight:bold;

font-size:18px;

color:BLUE;

...

.slInstall .slHeadlineNarrow

{

font-weight:bold;

font-size:18px;

color:#000;

text-align:center;

...

.slInstallEncoderOverlay

{

margin:0;

padding:0;

background-color: #FFF;

position: absolute;

height: 300px;

width: 400px;

/* for IE */

filter:alpha(opacity=80);

/* CSS3 standard */

opacity:0.8;

z-index:1;

.slInstallEncoderTitle a

{

color: BLUE;

................
................

In order to avoid copyright disputes, this page is only a partial summary.

Google Online Preview   Download