Quickstart: Intercepting push notifications for running apps (HTML)
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:
- A familiarity with push notifications. For more information, see the Windows Push Notification Services (WNS) overview.
- A cloud service capable of sending push notifications to the Windows Push Notification Services (WNS). For more information, see Quickstart: Sending a push notification.
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.
Related topics
Samples
Push and periodic notifications sample
Conceptual information
Windows Push Notification Services (WNS) 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