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 in the lower right corner of a tile (or the lower left corner if the UI uses a right-to-left language) to indicate an app's status in some way. The badge is an overlay on the tile, not a part of the tile itself. The badge is manipulated through its own APIs and schema and is updated through its own notifications. This Quickstart 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 Quickstart 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 Quickstart expressed using NotificationsExtenstions, see the App tiles and badges sample.
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.
- A familiarity with XML and its manipulation through Document Object Model (DOM) APIs.
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 Quickstart assumes that this variable has been declared.
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.
Numbered badges and glyph badges are defined through different XML in the badge templates. 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);
This example retrieves the badge element from the template and assigns it a numeric value.
var badgeAttributes = badgeXml.getElementsByTagName("badge"); badgeAttributes.setAttribute("value", "7");
This example assigns a glyph value to the badge.
var badgeAttributes = badgeXml.getElementsByTagName("badge"); badgeAttributes.setAttribute("value", "newMessage");
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);
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. This code uses a local notification, but, unlike tiles, a badge can be cleared through the cloud.
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.
- Badge overview
- Badge schema
- How to set up periodic notifications for badges
Build date: 11/29/2012