Quickstart: Sending a badge update (Windows Store apps using JavaScript and HTML)

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.

To see C#, C++, or Visual Basic versions of the JavaScript examples given in this Quickstart, click the "VB/C#/C++ and XAML" link at the upper right of this page.

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.

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 Getting started with Windows Store apps.
• 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 Quickstart 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.

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);

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. This code uses a local notification, but, 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.

Related topics

Badge overview

Badge schema

How to set up periodic notifications for badges

BadgeTemplateType

BadgeNotification

Build date: 11/29/2012