Adaptive and interactive toast notifications are a new feature in Windows 10. They allow you to:

• Create flexible toast notifications with more content and optional inline images without being limited to the existing restricted “toast template catalog”.
• Create actionable toast notifications that enable user interaction.

Note: This is pre-release documentation and it subject to change. Once the official MSDN documentation is posted, this post will be updated accordingly, or becomes a collection of links to a set of more comprehensive documents on MSDN. In the meantime, please use this post as a guidance to try out the cool features you can do with toast notifications via universal Windows apps and the Windows 10 preview SDK.

To see the legacy templates from Windows 8.1 and Windows Phone 8.1, please see the legacy toast template catalog.

Overview

In Windows 10, we have updated the existing toast templates in several aspects:

• Moving from a restricted template model to a flexible and adaptive template model;
• Adding ability to include custom actions and system actions in the payload;
• Providing 3 different activation types for the main toast notification and for each action;
• Adding ability to create a notification for specific scenarios, including alarm, reminder, and incoming call.

All of the above will be covered in this post.

Structure of toast notification

In Windows 10, developers construct a toast notification using XML, which should typically contain the following key elements:

• <visual> which covers the content available for the users to visually see, including text and images;
• <actions> which contains the custom interactions the developer wants to add inside the notification;
• <audio> which specifies a in-box or custom sound to be played along with the notification when it pops, and other sound-related properties.

Here is a quick example:

<toast><visual><binding template="ToastGeneric"><text>Sample</text><text>This is a simple toast notification example</text><image placement="AppLogoOverride" src="oneAlarm.png"/></binding></visual><actions><action content="check" arguments="check" imageUri="check.png"/><action content="cancel" arguments="cancel"/></actions><audio src="ms-winsoundevent:Notification.Reminder"/></toast>

Visual

Inside the visual element, it is required to have a binding element which contains the visual template information and the visual contents of the toast.

Different from tile notifications, which supports multiple templates based on different tile sizes, toast notifications for Windows 10 UWP apps only have one template name – ToastGeneric. This has several advantages over the legacy template model which was a set of restricted templates.

• Flexible. Developers can change the content of the toast, such as adding another line of text, adding an optional inline image, or change the thumbnail image from displaying application icon to something else, without worrying about changing the entire template or creating an invalid payload due to template-name – content mismatch.
• Adaptive. Developers can use the same code to construct the same payload for the toast notification that targets to deliver to different types of Windows devices, such as phone, tablet, desktop PC, or even Xbox – the different devices will accept the notification, and display it to the user under their own UI policies with appropriate visual affordance and interaction model.

For all the attributes supported in the visual section and its child elements, please see Schema section below.

For more examples, please see Samples below.

Actions

In Windows 10 UWP apps, developers can add custom interactions to their toast notification, to empower the users to do more outside of the app. The actions are specified inelement. There are 2 types of elements a developer can specify:

• <action>. A developer can specify up to 3 custom or system actions inside a toast notification.
• <input>. A developer can enable users to provide input to an app via a toast notification. For example, being able to type a reply to an instant message directly inside a toast.

Note: Both <action> and <input> are adaptive within the Windows family. For example, in Windows Mobile or Desktop, an <action> to a user is a button to tap/click on. A text <input> is a textbox that user can input text with using keyboard or virtual keyboard. It is, however, very possible that in some future devices, an action is announced out by voice, and a text input from the user is taken by dictation – the notification’s interactivity will adapt to the interaction model and visual affordance of the device where the message is displayed on.

When an action is taken by the user, the developer can choose to do one of the following be specifying the activationType attribute inside <action>:

• Activating the app in the foreground, with an action-specific argument that can be used to navigate to a specific page/context;
• Activating the app’s background task without affecting the user;
• Activating another app via protocol;
• Specify a system action to perform. The current available system actions are snoozing and dismissing scheduled alarm/reminder, which will be further explained in a section below.

For all the attributes supported in <actions> section and its child elements, please see the Schema section below.

For an example of how interactive toasts work, please see the Samples below.

Audio

In Windows 10 UWP apps, the <audio> element remains unchanged compared to what’s currently supported for Windows Phone 8.1.

You can now also provide a path to a local audio file in your app package or app storage, to play a custom sound specific for your app:

• ms-appx:///
• ms-appdata:///

For all the attributes supported in <audio> and its child elements, please see Schema section below.

Toast notifications for special scenarios

In Windows 10, a developer can use toast notifications for alarms, reminders, and incoming calls. These special toast notifications look visually consistent with the “standard” toast notifications, with some extra bits of UI policy that fits each scenario.

A reminder toast notification will stay on screen until the user dismisses it or takes action. On Windows Mobile, the reminder toast notifications will also show up pre-expanded.

In addition to sharing the above behaviors with reminder notifications, alarm notifications also automatically play looping audio.

Incoming call notifications are displayed full screen on Windows Mobile devices.

This is done by specifying the “scenario” attribute inside the root element of a toast notification – <toast>:

<toast scenario=" { default | alarm | reminder | incomingCall } " >

XML Samples

Please note that all toast notifications are taken from Desktop preview OS, the mobile version of the toast notifications are sometimes collapsed, with a grabber at the bottom to expand.

Notification with rich visual contents

You can have multiple lines of text, an optional small image to override the application logo, and an optional inline image thumbnail in a toast.

<toast><visual><binding template="ToastGeneric"><text>Photo Share</text><text>Andrew sent you a picture</text><text>See it in full size!</text><image placement="appLogoOverride" src="A.png"/><image placement="inline" src="hiking.png"/></binding></visual></toast>

Notification with actions (sample 1)

<toast><visual><binding template="ToastGeneric"><text>Microsoft Company Store</text><text>New Halo game is back in stock!</text><image placement="appLogoOverride" src="A.png"/></binding></visual><actions><action activationType="foreground" content="see more details" arguments="details" imageUri="check.png"/><action activationType="background" content="remind me later" arguments="later" imageUri="cancel.png"/></actions></toast>

Notification with actions (sample 2)

<toast><visual><binding template="ToastGeneric"><text>Cortana</text><text>We noticed that you are near Wasaki.</text><text>Thomas left a 5 star rating after his last visit, do you want to try?</text><image placement="appLogoOverride" src="A.png"/></binding></visual><actions><action activationType="foreground" content="reviews" arguments="reviews"/><action activationType="protocol" content="show map" arguments="bingmaps:?q=sushi"/></actions></toast>

Notification with text input and actions (sample 1)

In this sample, you can add a textbox that allows the user to input text.

<toast><visual><binding template="ToastGeneric"><text>Andrew B.</text><text>Shall we meet up at 8?</text><image placement="appLogoOverride" src="A.png"/></binding></visual><actions><input id="message" type="text" placeholderContent="reply here"/><action activationType="background" content="reply" arguments="reply"/><action activationType="foreground" content="video call" arguments="video"/></actions></toast>

Notification with text input and actions (sample 2)

If allowing user to reply with text input is the only scenario you care about, you can also use the below layout. This only works if your action specifies an image icon.

<toast><visual><binding template="ToastGeneric"><text>Andrew B.</text><text>Shall we meet up at 8?</text><image placement="appLogoOverride" src="A.png"/></binding></visual><actions><input id="message" type="text" placeholderContent="reply here"/><action activationType="background" content="reply" arguments="reply" imageUri="send.png" hint-iunputId="message"/></actions></toast>

Notification with selection input and actions

In this sample, you can add a dropdown list with pre-defined selections for the user to select.

<toast><visual><binding template="ToastGeneric"><text>Spicy Heaven</text><text>When do you plan to come in tomorrow?</text><image placement="appLogoOverride" src="A.png"/></binding></visual><actions><input id="time" type="selection" defaultInput="2"><selection id="1" content="Breakfast"/><selection id="2" content="Lunch"/><selection id="3" content="Dinner"/></input><action activationType="background" content="Reserve" arguments="reserve"/><action activationType="background" content="Call Restaurant" arguments="call"/></actions></toast>

Reminder Notification

Note that in a reminder scenario, the image is enlarged to fill the width of the toast notification.

<toast scenario="reminder"><visual><binding template="ToastGeneric"><text>Adam's Hiking Camp</text><text>You have an upcoming event for this Friday!</text><text>RSVP before it"s too late.</text><image placement="appLogoOverride" src="A.png"/><image placement="inline" src="hiking.png"/></binding></visual><actions><action activationType="background" content="RSVP" arguments="rsvp"/><action activationType="background" content="Reminder me later" arguments="later"/></actions></toast>

Activation Samples

Like mentioned above, the body and actions in the toast are capable of activating apps in different ways. The below sample will show you how to handle different type of activations from toast and/or toast actions.

Foreground

In this scenario, an app sets up to launch itself in the foreground to respond to an action inside an actionable toast notification.

Note: activation from toast notifications used to invoke OnLaunched(). In Windows 10, toast has its own activation kind and will invoke OnActivated().

async protectedoverridevoid OnActivated(IActivatedEventArgs args)
{//Find out if this is activated from a toast;
	If (args.Kind == ActivationKind.ToastNotification)
	{//Get the pre-defined arguments and user inputs from the eventargs;var toastArgs = args as ToastNotificationActivatedEventArgs;var arguments = toastArgs.Arguments;var input = toastArgs.UserInput[“1”]; 
}//...
}

Background

In this scenario, an app sets up to respond to an action inside an actionable toast notification using a background task. The below code shows how to declare this background task for handling toast activations inside manifest, and how to get details on action, and user inputs, when the task is executed.

<!-- Manifest Declaration --><!-- A new task type toastNotification is added --><Extension Category = "windows.backgroundTasks"
EntryPoint = "Tasks.BackgroundTaskClass"><BackgroundTasks><Task Type="systemEvent"/></BackgroundTasks></Extension>

namespace ToastNotificationTask
{publicsealedclass ToastNotificationBackgroundTask : IBackgroundTask
    {publicvoid Run(IBackgroundTaskInstance taskInstance)
        {//Inside here developer can retrieve and consume the pre-defined //arguments and user inputs;var details = taskInstance.TriggerDetails as NotificationActionTriggerDetails;var arguments = details.Arguments;var input = details.Input.Lookup(“1”);// ...
        }        
    }
}

Schema

Note: "?" means an attribute is optional

Section 1. <visual> and <audio>

<toast launch? duration? activationType? scenario? hint-people? ><visual version? lang? baseUri? addImageQuery? ><binding template? lang? baseUri? addImageQuery? ><text lang? >content</text><text/><image src placement? alt? addImageQuery? hint-crop? /></binding></visual><audio src? loop? silent? /><actions></actions></toast>

Attributes in <toast>

Attributes in <visual>

Attributes in <binding>

Attributes in <text>

Attributes in <image>

Attributes in <audio>

Section 2. <actions>

<toast><visual></visual><audio/><actions><input id type title? placeHolderContent? defaultInput? ><selection id content /></input><action content arguments activationType? imageUri? hint-inputId /></actions></toast>

Attributes in <input>

Attributes in <selection>

Attributes in <action>

Section 3. Additional attributes for system handled actions.

In addition to the above sections, in Windows 10, we also provide system-handled actions for snoozing and dismissing notifications, for apps that do not want to handle the snoozing/rescheduling of these notifications inside their background task. The actions can be combined, or specified individually, but we do not recommend anyone to implement a snooze action without a dismiss action.

System commands combo – SnoozeAndDismiss

<toast><visual></visual><audio/><actions hint-systemCommand? = "SnoozeAndDismiss"/></toast>

Attributes in <actions>

Individual system handled actions

<toast><visual></visual><audio/><actions><input id="snoozeTime" type="selection" defaultSelection="10"><selection id="5" content="5 minutes"/><selection id="10" content="10 minutes"/><selection id="20" content="20 minutes"/><selection id="30" content="30 minutes"/><selection id="60" content="1 hour"/></input><action activationType="system" arguments="snooze" hint-inputId="snoozeTime" content=""/><action activationType="system" arguments="dismiss" content=""/></actions></toast>

To construct individual snooze and dismiss actions, you need to do the following:

• Specify activationType = “system”.
• Specify arguments = “snooze” | “dismiss”
• Specify content:
  • If you want localized string of “snooze” and “dismiss” to be displayed on the actions, then specify content to be empty string – <action content = “”/>;
  • If you want your own customized string, just provide its value – <action content=”Remind me later” />.
• Specify input:
  • If you do NOT want user to select a snooze interval, instead, just want your notification to snooze only once for a system-defined time interval (that is consistent across the OS), then do NOT construct any <input> at all;
  • If you want to provide selections of snooze interval:
    • Specify hint-inputId in the snooze action;
    • Make sure you match the id of the input with the hint-inputId of the snooze action – <input id=”snoozeTime”></input><action hint-inputId=”snoozeTime”/>
    • Specify id for selection to be a nonNegativeInteger which represent snooze interval in minutes – <selection id=”240” /> means snoozing for 4 hours;
    • Make sure that the value of defaultSelection in <input> matches with one of the ids of the <selection> children elements.