Quickstart: Intercepting push notifications for running apps (HTML)

  • Article

Note  Not using JavaScript? See Quickstart: Intercepting push notifications for running apps (XAML).

 

You can design your app to intercept a push notification and respond to that notification in a non-default manner. This procedure can be used for all push notification types, but it is particularly useful for toast and raw notifications.

When your app's cloud service sends a notification to Windows, your app has the opportunity to intercept and handle that notification before it displays a toast, updates a tile or badge, or delivers a raw notification to a background task. It can also suppress the display or update of those elements. Implementing a notification delivery event handler is optional. It is most useful in scenarios in which the app wants to handle and suppress incoming toasts instead of showing them to the user.

Note  As of Windows Phone 8.1, the phone can also keep a toast notification from being displayed through use of the ToastNotification.suppressPopup or ScheduledToastNotification.suppressPopup property in the notification's XML content.

Note  This procedure applies only to running apps. Notifications that the system sends when the app is not running and the handler is not implemented are delivered normally—tiles are updated, toast is shown, and raw notifications are delivered to background tasks (if implemented).

 

Prerequisites

To understand this topic or to use the code it provides, you will need:

Instructions

1. Optional: Declare a namespace variable

This step provides you with a short name to use in place of the full namespace name. It is the equivalent of a "using" statement in C# or the "Imports" statement in Visual Basic. It allows you to simplify your code.

Note  The following code assumes that this variable has been declared.

 


var pushNotifications = Windows.Networking.PushNotifications;

2. Create a push notification channel

A valid notification channel is required to receive notifications pushed from a cloud server. The event listener watches this channel for the arrival of the notification. For more information about how to create a channel, see How to request, create, and save a notification channel.

If successful, this example creates a channel that can be accessed through newChannel.uri.


var channel;
var channelOperation = pushNotifications.PushNotificationChannelManager.createPushNotificationChannelForApplicationAsync();

return channelOperation.then(function (newChannel) {
    channel = newChannel;
    },
    function (error) {
        // ...
    }
);

3. Create a function to handle the push notification event

The example below shows how to handle all notification types.

The last line of code in this example sets the event's cancel property to true. This prevents the notification from carrying out any UI changes, such as updating a tile or badge or displaying a toast. In the case of a raw notification, it prevents the notification from being delivered to a background task, if one is implemented. In this way, any response to the notification is up to handler.


var content;
function onPushNotification(e) {
    var notificationPayload; 

    switch (e.notificationType) { 
        case pushNotifications.PushNotificationType.toast: 
            notificationPayload = e.toastNotification.content.getXml(); 
            break; 

        case pushNotifications.PushNotificationType.tile: 
            notificationPayload = e.tileNotification.content.getXml(); 
            break; 

        case pushNotifications.PushNotificationType.badge: 
            notificationPayload = e.badgeNotification.content.getXml(); 
            break; 

        case pushNotifications.PushNotificationType.raw: 
            notificationPayload = e.rawNotification.content; 
            break; 
    } 

    e.cancel = true;
}

4. Add an event listener for received push notifications

Use the channel created in step 1 to assign the event handler created in step 2 to handle the PushNotificationReceived event.


channel.addEventListener("pushnotificationreceived", onPushNotification, false);

Summary

If your scenario calls for it, intercepting and handling a push notification while your app is running can give your app more control over the effect of those notifications. For instance, you might not want a toast notification to display on top of a game in progress, and your event handler could integrate the content of that notification into the game UI in a less intrusive manner.

Samples

Raw notifications sample

Push and periodic notifications sample

Conceptual information

Windows Push Notification Services (WNS) overview

Raw notification overview

Best practices

Guidelines and checklist for push notifications

Guidelines and checklist for raw notifications

How-to

Quickstart: Creating and registering a raw notification background task