Toast notification overview (Windows Runtime apps)
This topic discusses the concepts and terminology surrounding toast notifications, which are pop-up notifications used to allow the app to communicate with the user whether the user is in another app, on the Start screen, or on the desktop. A toast can originate either from a local API call or from the cloud.
Toast notifications
A toast notification is a transient message to the user that contains relevant, time-sensitive information and provides quick access to related content in an app. It can appear whether you are in another app, the Start screen, the lock screen, or on the desktop. Toasts should be viewed as an invitation to return to your app to follow up on something of interest. Toast notifications are an optional part of the app experience and are intended to be raised only when your app is not the active foreground app.
For your app to communicate through a toast notification, you must declare that it is Toast Capable in your app's manifest file. This action adds your app to the Notifications section of PC settings, from which the user can disable or enable toast notifications for your app at any time.
A toast notification can contain text, and toast notifications on Windows can contain images, but secondary actions such as buttons are not supported. A toast can also play a system-defined sound when it displays. On Windows, a toast notification appears in the upper-right corner of your screen (top-left corner for right-to-left (RTL) languages). On Windows Phone 8.1, a toast notification appears at the top of the screen. Toast notifications can be activated, dismissed, or ignored by the user. When a user taps or clicks the notification, the associated app is launched and the user can expect that the resulting view is related to the content of the notification. It is the only mechanism by which one app can interrupt a user in another app.
A toast notification should be used only for information of high interest to the user, typically involving some form of user opt-in. Therefore, it is a good choice for incoming IM chat requests, and information that the user has opted to receive. However, it is extremely important that when you consider using a toast notification, you must realize that, due to its transient nature, or because of the user's settings, the user might never see it. Toast is designed to be used in combination with badges, tile notifications, and in-app UI to keep the user informed of events or items of interest in your app.
Raising a toast notification is essentially the same as sending a tile notification: create an XML payload for a specific template and pass that payload to a manager object to display. A toast notification is visually distinct from a tile but the markup structure is nearly identical.
There are two types of toast notification:
Standard toast: Most developers should use the standard toast notification. This toast remains on the screen for seven seconds, playing a brief sound to alert the user when it appears. The standard toast is best for notifications such as an IM contact sign-in, or a social media update.
Long-duration toast: This notification looks the same as a standard toast but stays on the screen for 25 seconds and optionally can play longer, looping audio. This type of toast is used in situations where you want to grab the user's attention because there is a human waiting on the other end of the connection. This is appropriate for person-to-person communication like instant messages and VOIP calls. This type of toast can also be used for calendar reminders.
Note Long-duration toast is not supported on Windows Phone 8.1; all toast on the phone is shown for the same amount of time.
Scheduled and recurring toast notifications
A toast notification can be scheduled to appear at a specific time. Use this feature for alarms, calendar reminders, and notifications that depend on precise timing. These notifications do not depend on the app's state or the computer's network connection.
A scheduled toast can also display multiple times within a short period to increase the user's chance of seeing it. For instance, you might want to show an important meeting reminder three times, five minutes apart.
Scheduled toast notifications specify the date and time when Windows should raise that toast notification. In the case of a recurring scheduled toast notification, the specified time is the first time that Windows will display the notification.
Working with toast templates
Toast notifications are based on a set of Windows-provided XML templates, each with varying content and layout. They can contain an image, text, or both. Use of these templates enables an app to maintain the expected Windows look and feel in their notifications. A template supplies a framework for the necessary XML image and text elements that can be specified in the notification.
Note You can send any toast template to Windows Phone 8.1, but it will be rendered as a modified version of ToastText02. See The toast template catalog for details.
While tile and toast notifications share many similarities in definition, a toast notification also comes with a sound that is played when the notification is shown.
The elements of a toast notification are defined in the toast schema.
For a full list of available toast notification templates, with explanations of each, see Choosing a toast template.
Sending toast notifications from desktop apps
Generally, sending a toast notification from a desktop app is the same as sending it from a Windows Store app. However, you should be aware of these differences and requirements:
- The app must have a shortcut installed (though not necessarily pinned) to the Start screen or in the Apps view
- The shortcut must have an AppUserModelID
- Desktop apps cannot schedule a toast
- All toasts raised by desktop apps are the same system-defined color
- Desktop apps cannot use web images
- Desktop app notifications will not appear on the lock screen
For more information, see these topics:
- How to enable desktop toast notifications through an AppUserModelID
- Quickstart: Sending a toast notification from the desktop
Showing toast on the lock screen
Toast associated with an app that has a tile or badge on the lock screen will also appear on the lock screen. Toast shown on the lock screen is identical to toast shown elsewhere. It differs in that all toasts on the Windows lock screen are shown for the length of a long-duration toast. For more information, see the Lock screen overview.
Related topics
Quickstart: Sending a toast notification
How to opt in for toast notifications
How to handle activation from a toast notification