How to handle activation from a toast notification (XAML)

Note  Not using C#/VB/C++? See How to handle activation from a toast notification (HTML).

 

This topic demonstrates the actions you should take in response to a user clicking on a toast notification sent from your app. Your app should respond by displaying UI specific to the toast. The app should typically launch in a context or view that is related to the toast's content. You accomplish this through an activation string that you include in the toast payload, which is then passed to your app as an argument in the activation event. The basic data flow is shown here:

1. The app or web service creates and sends the toast payload, including the launch string
2. The toast is raised and/or sent to the action center
3. The user selects the toast (click or touch)
4. The activated event fires
5. The app's activated event handler reads the launch string
6. The app is launched using the parameters provided in the launch string

Note  When testing toast notification code functionality through Microsoft Visual Studio, you must use either the Local Machine or Remote Machine debug setting on a Windows x86, x64, or Windows Runtime machine. You cannot use the Visual Studio Simulator debug function option—your code will compile and run in the Simulator, but the toast will not appear.

 

What you need to know

Technologies

• Windows Runtime

Prerequisites

To understand this topic, you will need:

• A working knowledge of toast notification terms and concepts. For more information, see the Toast notification overview.
• The Toast Capable option must be set to "true" in your app's manifest ("Yes" in the Visual Studio manifest editor) to send or receive toast notifications. For more information, see Quickstart: Creating a default tile using the Visual Studio manifest editor and How to opt in for toast notifications.
• A familiarity with the toast XML schema as well as a general familiarity with XML and its manipulation through Document Object Model (DOM) APIs. For more information, see Toast schema.
• The ability to create a basic Windows Store app with C# or C++ Microsoft Visual Basic using Windows Runtime APIs. For more information, see Create your first Windows Store app using C# or Visual Basic.

Instructions

Step 1: Include activation data in your toast payload

When your app is activated through a toast notification, it needs to be given information related to the content of the toast. Then it can reflect that content by launching into an associated view, rather than its default. When your app or web service creates the toast, it uses the launch attribute to specify this activation information. You can think of the string as analogous to command-line arguments. The string can contain any information that can be understood by the app, if it does not cause the XML payload to become invalid. Note that the total size of the toast's XML payload, including the launch string, cannot exceed 5 KB.

If you do not include a launch attribute string, your app will be launched normally, as though the user had launched it from the Start screen.

In this step, we assume a previously created XmlDocument object named toastXml. This example creates the launch attribute, assigns its string value, then adds it to the toast notification's XML payload. For instructions on creating the full toast notification, see Quickstart: Sending a toast notification.

((XmlElement)toastNode).SetAttribute("launch", "{\"type\":\"toast\",\"param1\":\"12345\",\"param2\":\"67890\"}");

The code above results in the following XML, based on the contents of the visual element that is defined in Quickstart: Sending a toast notification.

<toast launch="{&quot;type&quot;:&quot;toast&quot;:&quot;param1&quot;:&quot;12345&quot;:&quot;param2&quot;:&quot;67890&quot;}">                        
    <visual>
        <binding template="ToastImageAndText01">
            <image id="1" src="ms-appx:///images/redWide.png" alt="red graphic"/>
            <text id="1">Hello World!</text>
        </binding>
    </visual>
</toast>

Step 2: Handle the app's "OnLaunched" event

When the user clicks on your toast or selects it through touch, the associated app is launched, firing its OnLaunched event.

Note  If you do not include a launch attribute string in your toast and your app is already running when the toast is selected, the OnLaunched event is not fired.

 

This example shows the syntax for the override of the OnLaunched event, in which you will retrieve and act on the launch string supplied through the toast notification.

protected override void OnLaunched(LaunchActivatedEventArgs args)
{
    string launchString = args.Arguments

    ....
}

Related topics

Toast notifications sample

Windows.UI.Notifications API namespace

Toast notification overview

Guidelines and checklist for toast notifications

Quickstart: Sending a toast notification

The toast template catalog

Toast XML schema