How to handle activation from a toast notification (HTML)

Note  Not using JavaScript? See How to handle activation from a toast notification (XAML).

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 XML and its manipulation through Document Object Model (DOM) APIs.
• A familiarity with the toast XML schema. For more information, see Toast schema.
• The ability to create a basic Windows Store app with JavaScript using Windows Runtime APIs. For more information, see Create your first Windows Store app using JavaScript.

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.

var launchAttribute = toastXml.createAttribute("launch");
launchAttribute.value = "{\"myContext\":\"12345\"}";
var toastNode = toastXml.selectSingleNode("/toast");
toastNode.attributes.setNamedItem(launchAttribute);

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;myContext&quot;:&quot;12345&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: Register for the "activated" event

When the user clicks on your toast or selects it through touch, the activated event is fired. Your app must register through the addEventListener function be informed of the 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 activated event is not fired.

WinJS.Application.addEventListener("activated", onActivatedHandler, false);

Step 3: Implement a handler for your toast's "activated" event

Your registered event handler receives all activation events, regardless of the activation type. The kind property included in the event notification indicates the type of activation event. When the user clicks on a toast that has a launch attribute specified in its XML payload, an activation event of kind launch is fired. This is the same event that is raised when a user taps on an app's primary or secondary tile.

The activation string that you provided through the launch attribute in step 1 is included in the event notification's arguments property.

This example shows the outline of the activated event handler registered in step 2.

function onActivatedHandler(args) {
    if (args.detail.kind === Windows.ApplicationModel.Activation.ActivationKind.launch) {
        var launchString = args.detail.arguments;

        // Handle activation as required for your app, using the launch string.
    }
}

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