Creating a First-run Experience
This topic describes how you can detect when a Pinned site is launched by the user for the first time. Providing a first-run experience allows you to call attention to features of your Pinned site.
- Methods Used in this Task
- msIsSiteModeFirstRun(fPreserveState)
- Why Create a First-Run Experience?
- Reminding Users to Pin the Site
- Redirecting to a Configuration Page
- Related topics
Methods Used in this Task
The following method is introduced in this topic:
msIsSiteModeFirstRun(fPreserveState)
The window.external.msIsSiteModeFirstRun method determines whether a Pinned site was launched for the first time. Calling this method resets the first-run state if the fPreserveState parameter is false.
This method returns one of the following values:
0 — The Pinned site is not in a first-run state.
1 — This is the first launch from a drag-and-drop operation.
2 — This is the first launch from a shortcut on the Start menu.
Why Create a First-Run Experience?
After users pin your site, you might want to tell them about features that make the Pinned site more useful, like Thumbnail Toolbars, or dynamic Jump Lists. If your website can be configured or customized, you might want your users to review their personalization settings after they pin the site. And, if users add your website to the Start menu, it is especially important to remind them to pin the site to the Windows taskbar.
Only a Pinned site window that is launched immediately after installation can be in a first-run state. The state is not stored in the registry. The next time a Pinned site is launched, the opportunity to tell your users about features will have passed.
Reminding Users to Pin the Site
If you provide the option of adding the Pinned site shortcut to the Start menu by using the msAddSiteMode method, also remind users to pin the site to the Windows taskbar when the site is first launched. The following script shows you how to do this.
try {
if (window.external.msIsSiteMode()) {
// Detect first launch from the Start menu.
if (window.external.msIsSiteModeFirstRun(false) == 2) {
alert("Don't forget to pin this program to the taskbar.");
}
}
}
catch (ex) {
// Fail silently. Pinned Site API not supported.
}
The msIsSiteModeFirstRun method returns 2 if the site was first launched from a shortcut in the Start menu. By setting the fPreserveState parameter to false, this code example both reads and resets the first-run state in one operation. If you want to use the first-run state again, you should either set fPreserveState to true, or save the value in a variable.
Redirecting to a Configuration Page
For a more advanced first-run experience, you might want to direct your users to personalization and configuration settings for the Pinned site. Depending on your site, you should consider how this affects the overall experience of navigating your site. YChoose the least disruptive option available to you.
The following script redirects to a configuration page if the Pinned site is in a first-run state.
try {
if (window.external.msIsSiteMode()) {
// Detect any first-run state.
if (external.msIsSiteModeFirstRun(false)) {
window.location = "./ConfigPage.html";
}
}
}
catch (ex) {
// Fail silently. Pinned Site API not supported.
}
Note If you decide to redirect to a new page, do so while the page is loading, not after. This can be done either by adding an event listener to the DOMContentLoaded event, or by placing inline script within the page body or head element.
Related topics
Tasks
Declaring Pinned Site Metadata
Conceptual
Badge Notifications, directly on your Windows 8 Pinned Site
How to Improve Discoverability
Fresh Tweets 2.0 - demo for Windows 8