Requesting badge updates
Now that you have defined the badge metadata for your pinned site, it's time to request the badge from the server.This topic explains how to request badge updates from the client, and describes the XML file format returned by the server when responding to badge update requests.
This topic contains the following sections:
- Methods Used in this Task
- msSiteModeClearBadge()
- msSiteModeRefreshBadge()
- Clearing the badge notification
- Sending an ad-hoc request to refresh the badge
- Responding to badge update requests
- Planning the details of your request
- Related topics
Methods Used in this Task
The following methods are introduced in this topic:
msSiteModeClearBadge()
The window.external.msSiteModeClearBadge method clears the badge from the app tile of a Pinned site.
msSiteModeRefreshBadge()
The window.external.msSiteModeRefreshBadge method begins a new request to the server to update the app tile.
Clearing the badge notification
When a user clicks your app tile to open the website, and there is nothing to notify the user about, you should reset the badge notifications to zero. The easiest way to do this is to clear the badge notification by calling window.external.msSiteModeClearBadge. This clears the badge from the app tile and resets the timer to the next badge update.
(function () {
try {
if (window.external.msIsSiteMode()) {
try {
window.external.msSiteModeClearBadge();
}
catch (err) {}
// Continue initialization for pinned site.
}
}
catch (err) {
// Pinned site API not supported.
}
} ());
Notice that two try/catch blocks are used. The first prevents the browser from throwing an error if the pinned site API is not available. The second try/catch block is required to make sure the call to msSiteModeClearBadge, which was introduced in Internet Explorer 10, doesn't cause problems in earlier versions of Windows Internet Explorer.
Sending an ad-hoc request to refresh the badge
Windows sends badge update requests to the server based on the polling frequency specified in the "msapplication-badge" metadata when the site was pinned; however, you can request badge updates as often as you like. Obviously, you should be careful not to request updates so frequently that you negatively impact the server, but you can use this technique to get more frequent updates while your site is running.
Here's how that might look in code:
try {
window.external.msSiteModeClearBadge();
setInterval( window.external.msSiteModeRefreshBadge, 60000 );
}
catch (err) {}
Now, while your site is running, you can receive badge update every minute.
Responding to badge update requests
So, what exactly does the server send back when it receives a badge update request? It responds with a simple XML file based on the badge XML schema. Here's what a typical response looks like:
<?xml version="1.0" encoding="UTF-8"?>
<badge value="2"/>
This XML instructs Windows to add the number 2 as an icon overlay on your app tile. If you would like to try it yourself, paste the following URL into the address bar of your browser.
http://ietestdrive2.com/pinnedsites/TweetCounter/microsoft/1440/
The badge isn't limited to numbers, either. You can also select one of the standard icon overlays, such as "alert" or "attention". For a complete list of the supported icons, see badge XML schema.
Planning the details of your request
Although the server implementation is beyond the scope of this introduction, you need to consider what kinds of details to send with the request and how you specify those details in the URL. The fresh tweets sample app sends the following in the URL:
- Twitter username to follow. For example, "@microsoft"
- The age of tweets. For example, "1440" (all tweets from the previous day)
Depending on your app, you might also want to send a GUID or email address that uniquely identifies your user.
The sample app sends details to the server as part of the URL formatted according to the ASP.NET MVC pattern. You can also send request details as URL parameters to a classic ASP page, or you can design your server to ignore the client completely and perform some arbitrary code instead. You cannot send client-side cookies or form data with your request.