Quickstart: Intercepting push notifications for running apps (XAML)

Note  Not using C#/VB/C++? See Quickstart: Intercepting push notifications for running apps (HTML).

 

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. Add namespace declarations

Windows.Networking.PushNotifications includes the push notification and raw APIs. Windows.UI.Notifications is needed to retrieve tile, toast, and badge content from the notification.

using Windows.UI.Notifications;                        
using 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.

PushNotificationChannel channel = null;

try
{
    channel = await PushNotificationChannelManager.CreatePushNotificationChannelForApplicationAsync();
}

catch (Exception ex)
{ 
    // ... 
}

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.

string content = null;
private async void OnPushNotification(PushNotificationChannel sender, PushNotificationReceivedEventArgs e) 
{ 
    String notificationContent = String.Empty; 
    
    switch (e.NotificationType) 
    { 
        case PushNotificationType.Badge:
            notificationContent = e.BadgeNotification.Content.GetXml(); 
            break; 
        
        case PushNotificationType.Tile: 
            notificationContent = e.TileNotification.Content.GetXml(); 
            break; 
        
        case PushNotificationType.Toast: 
            notificationContent = e.ToastNotification.Content.GetXml(); 
            break; 
        
        case PushNotificationType.Raw: 
            notificationContent = 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.PushNotificationReceived += OnPushNotification;

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