Quickstart: Sending a toast notification (Windows Store apps using JavaScript and HTML)

A toast notification is a pop-up UI that appear in the upper-right corner of your screen (upper-left corner for right-to-left languages) to allow your app to communicate with the user when the user is in another app, on the Start screen, or 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

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 Toast notifications sample.

Prerequisites

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 Microsoft 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.
• 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.

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. Pick a template for your toast and retrieve its XML contents

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.

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

The GetTemplateContent method returns an XmlDocument. The code above retrieves the following XML skeleton, for which you will provide the details in subsequent steps through standard DOM functions:

<toast>
    <visual>
        <binding template="ToastImageAndText01">
            <image id="1" src=""/>
            <text id="1"></text>
        </binding>
    </visual>
</toast>

3. Supply text content for your notification

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[0].appendChild(toastXml.createTextNode("Hello World!"));

4. Supply an image for your notification

This code first retrieves all elements in the template with a tag name of "image". Unlike tiles, a toast template such as ToastImageAndText01 will contain at most one image. Note that not all toast templates contain images; some are text only.

var toastImageElements = toastXml.getElementsByTagName("image");

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.

toastImageElements[0].setAttribute("src", "ms-appx:///images/redWide.png");
toastImageElements[0].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[0].setAttribute("src", "ms-appdata:///local/redWide.png");
toastImageElements[0].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[0].setAttribute("src", "http://www.microsoft.com/redWide.png");
toastImageElements[0].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:

toastImageElements[0].setAttribute("src", "http://www.microsoft.com/redWide.png");

could be shortened to this:

toastImageElements[0].setAttribute("src", "redWide.png");

5. Optional: Specify a toast duration

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.

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

6. Optional: Specify toast audio

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. For more information, see Toast audio options.

A template 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. 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.

audio.setAttribute("src", "ms-winsoundevent:Notification.IM");

This example specifies that no sound should play.

audio.setAttribute("silent", "true");

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.

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.

toastNode.appendChild(audio);

7. Specify app launch parameters

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.

toastXml.selectSingleNode("/toast").setAttribute("launch", '{"type":"toast","param1":"12345","param2":"67890"}');

8. Create the toast notification based on the XML content you've specified.

var toast = new notifications.ToastNotification(toastXml);

9. Send your toast notification.

 
 var toastNotifier = notifications.ToastNotificationManager.createToastNotifier();
 toastNotifier.show(toast);

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.

Summary and next steps

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.

Related topics

Guidelines and checklist for toast notifications

Toast notifications sample

Sending toast notifications from desktop apps sample

Toast notification overview

Toast XML schema

Toast template options

Toast audio options

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

Build date: 11/29/2012