Toasts for Windows Phone 8

Article
05/20/2016

[ This article is for Windows Phone 8 developers. If you’re developing for Windows 10, see the latest documentation. ]

A toast displays at the top of the screen to notify users of an event, such as a news or weather alert.

This topic contains the following sections.

What it looks like

The following image shows a toast notification that was created by a fictional Contoso app.

How it works

A toast notification displays for about 10 seconds unless the user dismisses it with a flick to the right. If the user taps the toast, by default, your app's start screen launches. Or, you can choose to specify which screen of your app will launch.

On devices without Windows Phone 8 Update 3, toast notifications are not displayed when the target app is running in the foreground. On devices with Windows Phone 8 Update 3, toast notifications are displayed when the target app is running in the foreground but is obscured by other activity such as a phone call or the lock screen.

Toast properties

Windows Phone uses the user-selected theme color as the toast's background color. As a developer, you can create a toast notification with your app's icon, title, and a content string. The API names associated with each aspect of the toast are different, depending on if you create it locally from code, or externally, using push notifications, from a cloud service. See the images later on in this topic for the exact API names.

The amount of text that can be displayed depends on the characters used in the toast message and the length of Title, which is bolded, and Content, which is not bolded. If only Title is set, then approximately 40 characters can be displayed before being truncated. If only Content is set, then approximately 47 characters can be displayed. If a toast is split evenly between Title and Content, then approximately 41 characters can be displayed. Any text that does not fit on the toast will be truncated.

Windows Phone displays a small version of your app icon to the left of Title and Content. Although you can define what icon is associated with your app, it is not possible to pass a different icon with a toast notification.

How to send a toast notification

You can create a toast notification in one of two ways: locally from code, or externally, using a cloud service. The property names differ depending on the way you choose to create the toast notification.

Creating a toast notification using code

The following image shows the property names you'd use if you are creating a toast notification using code. Although you can define what icon is associated with your app, it is not possible to pass a different icon in place of the App List Icon, described in the following image, with a toast notification.

The following code example shows the properties used to create a toast notification using local code.

// Create a toast notification.
// The toast notification will not be shown if the foreground app is running.
ShellToast toast = new ShellToast();
toast.Title = "[title]";
toast.Content = "[content]";
toast.Show();

Creating a toast notification using a cloud service

The following image shows the property names you'd use if you are creating a toast notification using a cloud service. Although you can define what icon is associated with your app, it is not possible to pass a different icon in place of the App List Icon, described in the following image, with a toast notification.

The following code example shows the XML payload used to create a toast notification using a cloud service.

string toastMessage = "<?xml version=\"1.0\" encoding=\"utf-8\"?>" +
"<wp:Notification xmlns:wp=\"WPNotification\">" +
    "<wp:Toast>" +
        "<wp:Text1>[string]</wp:Text1>" +
        "<wp:Text2>[string]</wp:Text2>" +
        "<wp:Param>[string]</wp:Param>" +
    "</wp:Toast>" +
"</wp:Notification>";

For more detailed info about toast notification payloads when using a cloud service, see Sending push notifications for Windows Phone 8. For a detailed walkthrough on how to create a toast notification using a cloud service, see How to send and receive toast notifications for Windows Phone 8.

Deep linking to a screen using toast notifications

You can use the Param element or NavigateUri property, depending on how you're creating the toast notification, to deep link to a specific screen in your app. Here are the allowed formats. Any string used for the following examples must be 256 characters or less.

/page1.xaml – Defines the screen to navigate to in the app when the app starts. The string must begin with a "/".
/page1.xaml?value1=1234 &value2=9876 – Defines the screen to navigate to when the app starts, along with name/value pairs of info. The string must begin with a "/".
?value1=1234 &value2=9876 – Contains name/value pairs of info passed to the default start screen of the app. The string must begin with a "?".

Extracting URI parameters

URI parameter values are typically parsed out of the toast notification payload in the OnNavigatedTo event handler after the user has tapped the toast notification and navigated to the indicated screen of the client app running on the device.

        protected override void OnNavigatedTo(System.Windows.Navigation.NavigationEventArgs e)
        {
            base.OnNavigatedTo(e);

            string strVal1 = this.NavigationContext.QueryString["value1"];
            string strVal2 = this.NavigationContext.QueryString["value2"];

        }

Using custom sounds in toasts on Windows Phone 8 Update 3

Windows Phone 8 Update 3 (OS version number 8.0.10492) introduces the ability to provide a custom sound for toast notifications. Sound files can be in WAV, WMA, or MP3 format, must be less than 10 seconds long, and must be stored in the app’s installation directory or local storage folder.

To use a custom sound for a toast launched from code you must first determine that the current device is running on Windows Phone 8 Update 3. Once you have determined that custom sounds are supported, you must use reflection to access the new Sound property of the ShellToast class. Use the following helper methods in your code to determine the OS version and to set a property value using reflection.

// Set the minimum version number that supports custom toast sounds
private static Version TargetVersion = new Version(8, 0, 10492);
        
// Function to determine if the current device is running the target version.
public static bool IsTargetedVersion { get { return Environment.OSVersion.Version >= TargetVersion; } }
       
// Function for setting a property value using reflection.
private static void SetProperty(object instance, string name, object value)
{
    var setMethod = instance.GetType().GetProperty(name).GetSetMethod();
    setMethod.Invoke(instance, new object[] { value });
}

The following example shows you how to use these helper methods to show a toast using a custom sound. Note that you can show a toast that makes no sound by setting the Sound property to an empty string after verifying that the device supports the property.

public void ShowToast(bool useCustomSound, bool useWavFormat, bool doSilentToast)
{
    ShellToast toast = new ShellToast();
    toast.Title = "[title]";
    toast.Content = "[content]";

    //If the device is running the right version and a custom sound is requested
    if ((IsTargetedVersion) && (useCustomSound))
    {
        if (useWavFormat)
        {
            //Do the reflection to get the new Sound property added to the toast
            SetProperty(toast, "Sound", new Uri("MyToastSound.wav", UriKind.RelativeOrAbsolute));
        }
        else
        {
            //Do the reflection to get the new Sound property added to the toast
            SetProperty(toast, "Sound", new Uri("MyToastSound.mp3", UriKind.RelativeOrAbsolute));
        }
    }
    // For a silent toast, check the version and then set the Sound property to an empty string.
    else if ((IsTargetedVersion) && (doSilentToast))
    {
        //Do the reflection to get the new Sound property added to the toast
        SetProperty(toast, "Sound", new Uri("", UriKind.RelativeOrAbsolute));
    }


    toast.Show();
}

To use a custom sound for a toast that is launched via a cloud service, all you need to do is include a Sound element in the XML payload. To launch a silent toast, you can use the Silent attribute, set to “true”. The following example shows you how to create the XML payload for a toast that uses a custom sound. It reuses the version-checking helper method, IsTargetedVersion, from the previous example.

public void ShowToastWithCloudService(bool useCustomSound, bool useWavFormat, bool doSilentToast)
{
    StringBuilder toastMessage = new StringBuilder();
    toastMessage.Append("<?xml version=\"1.0\" encoding=\"utf-8\"?><wp:Notification xmlns:wp=\"WPNotification\"><wp:Toast>");
    toastMessage.Append("<wp:Text1>Toast Title</wp:Text1>");
    toastMessage.Append("<wp:Text2>Toast Content</wp:Text2>");
    if ((IsTargetedVersion) && (useCustomSound))
    {
        if (useWavFormat)
        {
            toastMessage.Append("<wp:Sound>MyToastSound.wav</wp:Sound>");
        }
        else
        {
            toastMessage.Append("<wp:Sound>MyToastSound.mp3</wp:Sound>");
        }
    }
    else if ((IsTargetedVersion) && (doSilentToast))
    {
        toastMessage.Append("<wp:Sound Silent=\"true\"/>");
    }
    toastMessage.Append("</wp:Toast></wp:Notification>");
}

Toasts in Windows Phone OS 7.1

Toast notifications that set the Parameter property can be sent only to devices running Windows Phone OS 7.1 or greater. Sending a notification with the Parameter property to a Windows Phone OS 7.0 device will result in a PushErrorTypePayloadFormatInvalid error and the channel will be closed.