Guidelines and checklist for toast notifications (Windows Store apps) (Windows)

8 out of 11 rated this helpful - Rate this topic

In this article

Appropriate use of toast notifications
Inappropriate use of toast notifications
Troubleshooting
Checklist
Related topics

This topic describes best practices to be followed when creating and sending toast notifications and lists any requirements your app must meet to be accepted in the Windows Store.

Appropriate use of toast notifications

Notify the user of something personally relevant and time sensitive. Examples include:
- an incoming VOIP call
- a new instant message
- a new text message
- a calendar appointment or other reminder
- notifications for which the user has explicitly opted in
Navigate to an appropriate destination in your app when the user taps on a toast. Consider that notifications are an invitation to switch context rather than a strictly informational update.
Consider that the user might not see a particular toast notification. Provide alternate ways for the user to get the same information if it is important. You may want to retain related information on your tile or within your app views.
A running app can hide a toast notification if it is no longer valid, such as an incoming call where the other party has hung up or the user has already answered on another device.
Combine multiple related updates that occur within a short period of time into a single toast notification. For instance, if you have three new updates that arrive at the same time, the app or app server should raise a single notification that states that there are three new updates rather than three separate notifications.
Present information in the simplest possible form. If your content doesn't require a headline, omit it. A message such as "Your download is complete." is entirely complete and needs no additional presentation.
Use images when they add clear value to the message, such as a photo of the sender of a message.

Inappropriate use of toast notifications

Don't use toast notifications to notify the user of something that must be seen, such as a critical alert. To ensure that the user has seen your message, notify them in the context of your app with a Flyout, dialog, app bar, or other inline element.
Don't include text telling the user to "click here to..." It is assumed that all toast notifications have a click or tap action with a result that is made clear by the context of the notification.
Don't use toast notifications to notify the user of transient failures or network events, such as a dropped connection.
Don't notify the user of something they didn't ask to be notified about. For instance, don't assume that all users want to be notified each time one of their contacts appears online.
Don't use toast notifications for anything with a high volume of notifications, such as stock price information.
Don't use toast notifications to notify the user of routine maintenance events, such as the completion of an anti-virus scan.
Don't raise a toast notification when your app is in the foreground and a more contextual surface such as an inline element, Flyout, dialog, or app bar is available. For example, additional instant messages that are related to an ongoing conversation that is in view should update the conversation inline rather than continue to raise a toast with each new message. Listen for the PushNotificationReceived event to intercept push notifications when your application is running.
Don't add generic images such as icons or your app logo in the image field of a notification.
Don't place your app's name in the text of the notification. Users will identify your application by your app's logo, which is automatically included in the toast notification.
Don't use your app to ask users to enable toast notifications if they have chosen to disable them. Your app is expected to work without toast notifications.
Don't automatically migrate your balloon notification scenarios to toast—consider that it may be more appropriate to notify the user when they aren't immersed in a full-screen experience (desktop style apps only).
Don't use toast notifications for non-real-time information, such as a picture of the day.
Don't hide toast notifications unless absolutely necessary.

Troubleshooting

This section addresses some common errors you might encounter while working with toast and toast templates. Largely, most of the troubleshooting steps used with toast notifications are the same steps used with tile notifications. Unless specified otherwise, each solution applies to all notification delivery types: local, scheduled, or push notifications.

There may also be specific troubleshooting steps to follow for your notification's delivery method. For more information, see these topics:

Local toast notification is not displayed

The most common problem in this situation is that the XML used to define your notification is incorrect in some way. However, there are other possible causes, which these steps walk you through:

Check user settings
Check app manifest entries
Check your image sizes
Verify your URLs
Examine your image formats
Check the syntax of your XML
Check your notification's expiration time

Check the user settings

Possible cause: The user or administrator has disabled notifications through settings. Check the global notification on/off switch and the per-application on/off switches in the PC Settings -> Notifications page. As for the administrator, there are several group policies which can disable notifications. Check with your administrator to ensure that notifications are enabled.

Fix: Enable notifications through settings or have an administrator enable notifications through group policy.

For more information, see How to check toast notification settings.

Check app manifest entries

Possible cause: The app manifest did not have the proper information set to enable toast delivery. Ensure that the "Toast Capable" setting in the app manifest is set to "Yes". If any notification content, such as an image, is retrieved from the Internet, make sure that the "Internet (Client)" capability is declared in the app manifest.

Fix: Enable notification-specific entries in the app manifest.

For more information, see Quickstart: Creating a default tile using the Microsoft Visual Studio manifest editor.

Check your image sizes

Possible cause: Images for all notifications must be smaller than 1024 x 1024 pixels and less than 200 KB in size. If any image in a notification exceeds any of these dimensions, the notification will be discarded.

Fix: Shrink your images.

For more information, see Tile and toast image sizes.

Verify your URLs

Possible cause: URL syntax errors.

Images in notifications are given as a resource reference or a literal path. If a path is used, it must be given using one of these three protocols:

Prefix	Use	Notes
http:// and https://	Images stored online	These images might be cached locally, so your image server might not receive a request for the image. Query strings are appended to these URLs. Make sure your web server returns the original image rather than a 404 if you choose to ignore the query string. An example query string: ?scale=100&contrast=blk&lang=en-US Note that to retrieve any notification content from the Internet, your app must declare the "Internet (Client)" capability in its app manifest.
ms-appx:///	Images included with your app's package	The Uniform Resource Identifier (URI) accepts either forward slash (/) or backward slash (\) to separate folders in a path, but most programming languages require you to use an escape character when you specify a backward slash (\\). Note that this reference requires a triple forward slash after the colon.
ms-appdata:///local/	Images saved locally by your app	This location corresponds to the folder returned by Windows.Storage.ApplicationData.current.localFolder. Folder separators in the path must use escape characters (\\). Note that this reference requires a triple forward slash after the colon.

Prefix

Use

Notes

http:// and https://

Images stored online

These images might be cached locally, so your image server might not receive a request for the image. Query strings are appended to these URLs. Make sure your web server returns the original image rather than a 404 if you choose to ignore the query string. An example query string: ?scale=100&contrast=blk&lang=en-US

Note that to retrieve any notification content from the Internet, your app must declare the "Internet (Client)" capability in its app manifest.

ms-appx:///

Images included with your app's package

The Uniform Resource Identifier (URI) accepts either forward slash (/) or backward slash (\) to separate folders in a path, but most programming languages require you to use an escape character when you specify a backward slash (\\). Note that this reference requires a triple forward slash after the colon.

ms-appdata:///local/

Images saved locally by your app

This location corresponds to the folder returned by Windows.Storage.ApplicationData.current.localFolder. Folder separators in the path must use escape characters (\\). Note that this reference requires a triple forward slash after the colon.

Note The '/' character works as a separator in every specification type. We recommended that you use '/' instead of '\' at all times to avoid inadvertent confusion with escape characters.

Well-formed examples:

URL
http://www.contoso.com/icon.jpg
ms-appx:///images/icon.png
ms-appdata:///local/myDrawing.jpg

Badly-formed examples:

URL	Notes
http://www.contoso.com\fail.png	An HTTP path must use the / character. Do not use the \ character.
http:www.contoso.com	An HTTP path requires a double-slash (//) after the colon.
"ms-appdata:///local/c:\\images\\Drawing.jpg"	An app cannot reference images outside of its local storage.
"ms-appx://images/triangle.png"	Use a triple-slash rather than a double-slash with "ms-appx:".

Examine your image formats

Possible cause: Images are in an unsupported format.

Notifications can only use images in .png, .jpg/.jpeg, or .gif format. The format of the image must also match its extension. Merely renaming an unsupported file type with a supported extension won't work.

The most common cause of image format errors is serialization of bitmaps to the Windows.Storage.ApplicationData.current.localFolder storage. Be sure to invoke your preferred format, or the image will be stored as a Windows bitmap and its header will include "BMP".

To verify: One way to verify your image format is to load your image into an image processing program and save as a .jpg. If you reference this new .jpg file in your notification and the error does not recur, it was probably an image format error. You can also open the file in the Visual Studio binary editor and examine its header.

Fix: Change or correct your image formats.

Check your XML syntax and content

Possible cause: XML syntax or validation errors.

Apart from basic syntax, make sure that your XML is complete and correct. Some common points of failure in the XML content include the following:

Case sensitivity. Tag names, attribute names, and attribute values are all case sensitive. Be sure that your XML has the correct casing.
Text strings should not contain reserved XML characters. For example, you cannot italicize a string in a toast by including <i> and </i> tags. If you intend to show the literal characters "<i>", they should be properly escaped. For more information on escape characters in XML, see XML Character Entities and XAML.
The values supplied for the lang attributes must conform to the ITEF BCP 47 specification.
XML strings created locally (for local or scheduled notifications) must use the UTF-8 encoding. When sent through push notifications or polled from a URL, the strings should use the UTF-16 encoding.
If you include an image element in your XML payload with a non-empty src attribute, you must be sure to include a reference to a valid image or the notification will fail.

You can use the Event Log to check for errors when your toast notification does not display. Look for events involving your toast notification in the Event Viewer under Applications and Services Logs > Microsoft > Windows > Immersive-Shell > Microsoft-Windows-TWinUI > Operational.

To verify: Use an XML syntax checker, such as the Visual Studio editor, to look for basic syntax errors. Look at the appropriate template reference (ToastTemplateType) to ensure that you are assigning the correct item to the correct element.

Fix: Change your XML or use a different template to match your content.

Ensure that your notification hasn't expired

Possible cause: The expiration time is set to too small a value.

If you set the expiration time in your notification through the ExpirationTime method (for a local notification) or the X-WNS-TTL header field (in a push notification), be aware that the values represent milliseconds. For example, if you want a toast notification to last for exactly one hour, the value should be 60 * 60 * 1000 = 3600000.

Fix: Use a larger value.

Checklist

For general Windows Store requirements, see Certification requirements for Windows apps.

Guidelines and checklist for toast notifications (Windows Store apps)