Quickstart: Managing toast notifications in action center (XAML)
Windows Phone 8.1 introduces APIs that you can use to manage toast notifications in action center. This topic shows how to manage your toast notifications using these APIs.
Prerequisites
To understand this topic, you will need:
- A working knowledge of toast notification terms and concepts. For more info, see Toast overview.
- A familiarity with action center. For more info, see Managing toast notifications in the action center.
- A working knowledge of general notification terms and concepts. For more info, see Sending notifications.
APIs for managing toast notifications in action center
The following table summarizes the major APIs related to managing toast notifications in action center.
| API | Description |
|---|---|
| ToastNotificationManager | Class used in creating and sending a toast, but mentioned here because it provides access to the ToastNotificationHistory object. |
| ToastNotificationHistory | Class that enables removal of toast notifications from action center. |
| Optional property used to categorize a toast notification into a group. | |
| Optional property that identifies a toast notification. Multiple notifications can have the same tag. | |
| Properties that prevent a toast notification's pop-up UI from appearing on the screen and that send the notification directly to action center. | |
| Property that represents the maximum time a toast notification remains visible in action center before it is removed by the system. The default time is 7 days. |
Sending a local toast notification
To demonstrate action center, we'll send toast notifications to populate it and to manipulate later. The simplest way to do that is to send local toast notifications. The code example here shows how to create a basic toast and send it locally. For an in-depth discussion of the procedure given in this step, see Quickstart: Sending a toast notification.
Here we create a toast by using the ToastText02 template. This template contains a maximum of two text elements. The first text element is treated as a header text and is always bold.
Important In Windows Phone 8.1, all toast templates are rendered as a ToastText02 template even if another template is specified and used if the toast is received on a PC or tablet. Images are ignored in Windows Phone 8.1; instead, the app's icon (defined in its manifest) is displayed to the left of the toast text and is also shown in action center.
This example:
- Retrieves the template contents.
- Fills in the text elements with previously defined string variables.
- Sets a duration for the toast UI to appear on the screen.
- Packages the modified XML into a toast notification object.
- Sets an explicit expiration time of one hour.
- Sends the toast.
using Windows.UI.Notifications;
using Windows.Data.Xml.Dom;
ToastTemplateType toastTemplate = ToastTemplateType.ToastText02;
XmlDocument toastXml = ToastNotificationManager.GetTemplateContent(toastTemplate);
XmlNodeList toastTextElements = toastXml.GetElementsByTagName("text");
toastTextElements[0].AppendChild(toastXml.CreateTextNode(toastHeading));
toastTextElements[1].AppendChild(toastXml.CreateTextNode(toastBody));
IXmlNode toastNode = toastXml.SelectSingleNode("/toast");
((XmlElement)toastNode).SetAttribute("duration", "long");
ToastNotification toast = new ToastNotification(toastXml);
toast.ExpirationTime = DateTimeOffset.UtcNow.AddSeconds(3600);
ToastNotificationManager.CreateToastNotifier().Show(toast);
using namespace Windows::UI::Notifications;
using namespace Windows::Data::Xml::Dom;
ToastTemplateType toastTemplate = ToastTemplateType::ToastText02;
XmlDocument^ toastXml = ToastNotificationManager::GetTemplateContent(toastTemplate);
XmlNodeList^ toastTextElements = toastXml->GetElementsByTagName("text");
toastTextElements->Item(0)->InnerText = toastHeading;
toastTextElements->Item(1)->InnerText = toastBody;
IXmlNode^ toastNode = toastXml->SelectSingleNode("/toast");
static_cast<XmlElement^>(toastNode)->SetAttribute("duration", "long");
ToastNotification^ toast = ref new ToastNotification(toastXml);
int minutes = 60;
auto cal = ref new Windows::Globalization::Calendar();
cal->AddMinutes(minutes);
toast->ExpirationTime = cal->GetDateTime();
ToastNotificationManager::CreateToastNotifier()->Show(toast);
When the toast is sent, it is displayed in a pop-up UI at the top of the phone's Start screen. If it is not explicitly acted on by the user, the toast is also shown in action center.
Sending a toast notification directly to action center
Instead of showing a pop-up UI for every toast, you can send some toast notifications directly to action center. This reduces noise while still keeping the user informed. This code example, which uses the toast object created in the previous example, suppresses the pop-up UI so that the same call to the Show method sends the notification directly to action center.
toast.SuppressPopup = true;
ToastNotificationManager.CreateToastNotifier().Show(toast);
toast->SuppressPopup = true;
ToastNotificationManager::CreateToastNotifier()->Show(toast);
Replacing a toast in action center
Keep info in action center fresh and unique. For example, multiple price notifications in action center for the same stock would be confusing. You can replace a notification in action center by sending a new toast with the same Tag and/or Group property values as the toast you want to replace.
In this code example, we assume that a finance app sends regular toast notifications with the current value of a stock whose symbol is BYA. Those notifications are always given a tag of "BYA" and a group of "DailyStockPrices". When you assign the Tag and Group properties in our standard toast notification, this notification replaces any existing notification in action center with the same tag and group. This practice ensures that there's only one notification for that stock in action center, and that it gives the most current price.
toast.Tag = "BYA";
toast.Group = "DailyStockPrices";
ToastNotificationManager.CreateToastNotifier().Show(toast);
toast->Tag = "BYA";
toast->Group = "DailyStockPrices";
ToastNotificationManager::CreateToastNotifier()->Show(toast);
Replacing a toast notification in action center is also useful when you use the snooze facility of the ScheduledToastNotification class. If you set the Tag and/or Group properties, the previous iteration of the notification is replaced in the action center every time the snoozed toast is raised. If you don't set those properties, each time the toast is raised and snoozed, it appears as an individual entry in action center.
Removing toasts from the action center
These code examples show the result of Remove and RemoveGroup method calls on the following set of labeled toast notifications in action center.
.png)
Remove a notification with a given tag and no group label
ToastNotificationManager.History.Remove("T2");
ToastNotificationManager::History->Remove("T2");
The preceding call results in the following set. Note that notifications with tag "T2" but also assigned to a group were not removed.
.png)
Remove a notification that matches a specified tag and a specified group
ToastNotificationManager.History.Remove("T2", "G1");
ToastNotificationManager::History->Remove("T2", "G1");
The preceding call results in the following set, removing the single notification that matches the criteria.
.png)
Remove all notifications in a specified group
ToastNotificationManager.History.RemoveGroup("G1");
ToastNotificationManager::History->RemoveGroup("G1");
The preceding call results in the following set, removing all notifications with the matching group label.
.png)
Summary and next steps
In this Quickstart, you managed toast notifications in action center by using the new notification-management APIs. You sent notifications directly to action center without displaying a pop-up UI. You used the Tag and Group notification properties and the ToastNotificationHistory object to remove notifications from action center and you also replaced a notification in action center with an updated message.
To see these action center concepts in action, download and run the Action Center Quickstart Sample.