Quickstart: Sending a badge update (HTML)
Note Not using JavaScript? See Quickstart: Sending a badge update (XAML).
This topic shows you how to create or update a badge on a tile. You will send a badge notification that includes either a glyph or numeric value. You will also see how to remove your badge from the tile.
A badge is a number or glyph that is displayed on the tile to indicate an app's status in some way. The badge is an overlay on the tile, not a part of the tile itself. It can appear in several places on the tile:
- In the lower right corner on Windows using a left-to-right language such as English
- In the lower left corner on Windows using a right-to-left language such as Arabic
- In the upper right corner on Windows Phone 8.1 using a left-to-right language
- In the upper left corner on Windows Phone 8.1 using a right-to-left language
The badge is manipulated through its own APIs and schema and is updated through its own notifications. This topic walks you through the procedure to define badge content, send it through a notification, and remove that content once it's no longer needed. These actions are demonstrated using a local notification, which is the simplest notification to implement.
Note In this topic you'll manipulate the notification content directly through the XML Document Object Model (DOM). An optional approach is available through the NotificationsExtensions library, which presents the XML content as object properties, including Intellisense. For more information, see Quickstart: Using the NotificationsExtensions library in your code. To see the code in this topic expressed using NotificationsExtenstions, see the App tiles and badges sample.
Prerequisites
To understand this topic, you will need:
- A working knowledge of badge and notification terms and concepts. For more information, see Tiles, Badges, and Notifications.
- A familiarity with the badge XML schema. For more information, see Badge schema.
- The ability to create a basic Windows Store app with JavaScript using Windows Runtime APIs. For more information, see Create your first Windows Store app using JavaScript.
- A familiarity with XML and its manipulation through Document Object Model (DOM) APIs.
Instructions
1. Optional: Declare a namespace variable
This step provides you with a short name to use in place of the full namespace name. It is the equivalent of a "using" statement in C# or the "Imports" statement in Visual Basic. It allows you to simplify your code.
Note The rest of the code in this topic assumes that this variable has been declared.
var notifications = Windows.UI.Notifications;
2. Choose whether to display a number or a glyph
A badge can display the numbers 0-99 or one of a set of system-defined status glyphs. The badge you choose will depend on your scenario. For example, an e-mail program might display the number of unread mails or it might display the "new message" glyph when a new mail arrives. For more information on the available glyphs, see the Badge overview. For more information on when to use numbers or glyphs, see Guidelines and checklist for tiles and badges.
Note As of Windows Phone 8.1, only the "alert" and "attention" status glyphs, as well as numbers, are supported for phone badges. Sending any other glyphs to the phone will clear the badge.
Numbered badges and glyph badges are defined through specific badge templates for each. You must retrieve the appropriate template for the badge type that you've decided on. This example retrieves the template for a numeric badge.
var badgeType = notifications.BadgeTemplateType.badgeNumber;
var badgeXml = notifications.BadgeUpdateManager.getTemplateContent(badgeType);
This example retrieves the template for a glyph badge.
var badgeType = notifications.BadgeTemplateType.badgeGlyph;
var badgeXml = notifications.BadgeUpdateManager.getTemplateContent(badgeType);
3. Assign a value to your badge
This example retrieves the badge element from the template and assigns it a numeric value.
var badgeAttributes = badgeXml.getElementsByTagName("badge");
badgeAttributes[0].setAttribute("value", "7");
This example assigns a glyph value to the badge.
var badgeAttributes = badgeXml.getElementsByTagName("badge");
badgeAttributes[0].setAttribute("value", "newMessage");
4. Create the badge notification and send it to the badge
This example packages the XML you've defined into a notification and sends it to the badge.
var badgeNotification = new notifications.BadgeNotification(badgeXml);
notifications.BadgeUpdateManager.createBadgeUpdaterForApplication().update(badgeNotification);
5. Optional: Clear the badge if it is no longer valid
If the information conveyed through the badge number or glyph is out of date or no longer useful, you should remove the badge. The following code removes the current badge from the calling app's tile. You could also send the value "none" as a badge update in place of calling the Clear method.
Note Unlike tiles, a badge can be cleared through the cloud.
notifications.BadgeUpdateManager.createBadgeUpdaterForApplication().clear();
Summary and next steps
In this Quickstart, you defined and sent new content to a badge on your app's tile, and then removed it once it was no longer valid.
This Quickstart sent the badge update as a local notification. You can also explore the other methods of notification delivery: scheduled, periodic, and push. For more information, see Delivering notifications.