Quickstart: Sending a toast notification (HTML)
A toast notification is a pop-up UI that appears on your screen to allow your app to communicate with the user when the user is in another app, on the Start screen, or, in the case of Windows, on the desktop. This Quickstart walks you through the steps to define and display toast content. These actions are demonstrated through a local notification, which is the simplest notification to implement. We discuss the following steps:
- Specifying a template for your notification
- Retrieving the template's blank XML content
- Adding text to the notification
- Adding an image to the notification
- Setting a duration for your notification
- Specifying audio to accompany your notification
- Providing contextual information used when your app is activated by the notification
- Sending your toast as a local notification
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 Toast notifications sample.
Note When testing toast notification code functionality through Microsoft Visual Studio, you must use either the Local Machine or Remote Machine debug setting on a Windows x86, x64, or Windows Runtime machine. You cannot use the Visual Studio Simulator debug function option—your code will compile and run in the Simulator, but the toast will not appear.
To understand this topic, you will need:
- A working knowledge of toast notification terms and concepts. For more information, see Toast notification overview.
- The Toast Capable option must be set to "true" in your app's manifest ("Yes" in the Visual Studio manifest editor) to send or receive toast notifications. For more information, see How to opt in for toast notifications.
- A familiarity with XML and its manipulation through Document Object Model (DOM) APIs.
- A familiarity with the toast XML schema. For more information, see Toast schema.
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.
Choose a template from the system-provided template catalog that fits the needs of your content. For the complete list of templates, see the ToastTemplateType enumeration. Note that each separate notification that you send can use a different template.
Only a variation of the toastText02 template is supported on Windows Phone 8.1. It accepts two text strings, with the first rendered in bold text, but they are both on the same line so only one short string or two very short strings should be used to avoid concatenation.
This example, for use with Windows, uses the toastImageAndText01 template, which requires one image and one string of text. An example is shown here:
var template = notifications.ToastTemplateType.toastImageAndText01; var toastXml = notifications.ToastNotificationManager.getTemplateContent(template);
<toast> <visual> <binding template="ToastImageAndText01"> <image id="1" src=""/> <text id="1"></text> </binding> </visual> </toast>
This example first retrieves all elements in the template with a tag name of "text". The toastImageAndText01 template contains only a single text string, which the code assigns. This string can wrap over a maximum of three lines, so the length of the string should be set accordingly to avoid truncation.
var toastTextElements = toastXml.getElementsByTagName("text"); toastTextElements.appendChild(toastXml.createTextNode("Hello World!"));
This code first retrieves all elements in the template with a tag name of "image". A toast template, such as toastImageAndText01, contains at most one image. Note that not all toast templates contain images; some are text only.
Images can be used from the app's package, the app's local storage, or from the web. Versions of this step are shown for each image source. Images must be less than 200 KB in size and smaller than 1024 x 1024 pixels. For more information, see Tile and toast image sizes.
The following code uses a local image from the app's package. This type of image is included in your Visual Studio solution file and is packaged as part of your app. These images are accessed by using the "ms-appx:///" prefix. As a best practice, we also assign optional alt text for accessibility purposes such as screen readers.
Important The image "redWide.png" used here is only an example and is not included in a Microsoft Visual Studio project. You will need to replace "redWide.png" with the name of an actual image of your own that you've added to the project before you attempt to send this toast.
toastImageElements.setAttribute("src", "ms-appx:///images/redWide.png"); toastImageElements.setAttribute("alt", "red graphic");
The following code uses a local image from the app's local storage. This type of image has been saved by your app to its local storage. This is the location returned by Windows.Storage.ApplicationData.current.localFolder. These images are accessed by using the "ms-appdata:///local/" prefix. Again, we also assign optional alt text for accessibility purposes such as screen readers.
toastImageElements.setAttribute("src", "ms-appdata:///local/redWide.png"); toastImageElements.setAttribute("alt", "red graphic");
The following code uses a web image. These images are accessed by using the "http://" protocol to specify the image's path. You can also use the "https://" protocol.
toastImageElements.setAttribute("src", "http://www.microsoft.com/redWide.png"); toastImageElements.setAttribute("alt", "red graphic");
You can use the optional baseUri attribute to specify a root path, such as "http://www.microsoft.com/", that is combined with any relative Uniform Resource Identifiers (URIs) specified in any image's src attributes. This attribute can be set on either the visual element (to apply to the entire notification) or the binding element (to apply to that binding). If baseUri is set on both, the value in binding overrides the value in visual.
If the baseUri was set to "http://www.microsoft.com/", this line in the example code:
could be shortened to this:
You can optionally set a display duration for your toast. There are two values: "short" (the default) and "long". Use "long" only if your notification is part of a scenario such as an incoming call or appointment reminder. For more information, see Toast notification overview.
Different durations are not supported on Windows Phone 8.1; all toasts have the same duration. If this attribute is included in a phone toast notification, it is ignored.
Note The default duration is "short", so you normally would add this attribute only to set the duration to "long".
var toastNode = toastXml.selectSingleNode("/toast"); toastNode.setAttribute("duration", "long");
By default, Windows plays a short sound when your toast is displayed. You can optionally specify a different sound from a system-provided set of sounds, or no sound at all. On Windows Phone 8.1, you can specify a custom sound. For more information, see The toast audio options catalog.
A template retrieved through getTemplateContent does not contain an audio element, so you must define and add it to your XML payload. The sound file is specified by using the "ms-winsoundevent:" prefix, or, on Windows Phone 8.1, a path that uses the "ms-appx:///" or "ms-appdata:///" prefix. This example creates an audio element and selects the toast element that will be its parent.
var toastNode = toastXml.selectSingleNode("/toast"); var audio = toastXml.createElement("audio");
This example specifies a non-default sound.
This example specifies that no sound should play.
In the case of a long-duration toast notification, the sound can be looped rather than playing only once. Note that looping audio is only valid for long-duration toasts. Specific sounds for use with looping are included in the system-specified sound set. This example specifies a looping sound.
Because it does not support long-duration toasts, Windows Phone 8.1 does not support looped audio.
toastNode.setAttribute("duration", "long"); var audio = toastXml.createElement("audio"); audio.setAttribute("src", "ms-winsoundevent:Notification.Looping.Alarm"); audio.setAttribute("loop", "true");
Once you have defined your audio element, you must attach it to your toast's XML payload as a child of the toast element, as shown here.
When the user clicks your toast notification, the expectation is that your app will be launched, with a view that relates to the content of the notification. To accomplish this, use the launch attribute of the toast element, which provides a string that is passed from the toast to the app when the app is launched through the toast. This string has no specific form and is app-defined. Your app must check for this string as an argument each time that it is activated adjust its view or operation accordingly.
In Windows Phone Silverlight 8.1, the value of the launch string is appended to your default launch page's URI. For example, if you provide the launch string "?conversation=71", it results in a URI such as /MainPage.xaml?conversation=71. Therefore, the launch string must also be a valid query string; otherwise, an exception is thrown.
var toastNotifier = notifications.ToastNotificationManager.createToastNotifier(); toastNotifier.show(toast);
In Windows Phone Silverlight 8.1, a toast is not displayed if the current foreground app is the caller of the ToastNotifier.Show method. In that case, toast should primarily be used by a background agent.
Note: The background color applied to your toast notification is the background color declared for your app's tile in its app manifest. For more information, see Quickstart: Creating a default tile using the Visual Studio manifest editor.
In this Quickstart, your sent your local toast notification to your user.
This Quickstart sent the toast as a local notification, that being the simplest notification type to implement and allowing you to quickly see your results. Next, you should explore the other methods of toast notification delivery: scheduled and push. For more information, see Delivering notifications.
- Toast notifications sample
- Sending toast notifications from desktop apps sample
- Reversi sample feature scenarios: toast notifications
- Toast notification overview
- The toast template catalog
- The toast audio options catalog
- Quickstart: Sending a push notification
- How to handle activation from a toast notification
- How to opt in for toast notifications
- How to schedule a toast notification
- Quickstart: Sending a toast notification from the desktop
- How to enable desktop toast notifications through an AppUserModelID
- Best practices
- Guidelines and checklist for toast notifications
- Toast XML schema