Handling Push Notifications in Windows 8.1 Universal and Windows 10 UWP

improve this page | report issue

Overview

MobileFirst-provided Notifications API can be used in order to register & unregister devices, and subscribe & unsubscribe to tags. In this tutorial, you will learn how to handle push notification in native Windows 8.1 Universal and Windows 10 UWP applications using C#.

Prerequisites:

Jump to:

Notifications Configuration

Create a new Visual Studio project or use and existing one.
If the MobileFirst Native Windows SDK is not already present in the project, follow the instructions in the Adding the MobileFirst SDK to Windows applications tutorial.

Adding the Push SDK

  1. Select Tools → NuGet Package Manager → Package Manager Console.
  2. Choose the project where you want to install the MobileFirst Push component.
  3. Add the MobileFirst Push SDK by running the Install-Package IBM.MobileFirstPlatformFoundationPush command.

Pre-requisite WNS configuration

  1. Ensure the application is with Toast notification capability. This can be enabled in Package.appxmanifest.
  2. Ensure Package Identity Name and Publisher should be updated with the values registered with WNS.
  3. (Optional) Delete TemporaryKey.pfx file.

Notifications API

MFPPush Instance

All API calls must be called on an instance of MFPPush. This can be done by creating a variable such as private MFPPush PushClient = MFPPush.GetInstance();, and then calling PushClient.methodName() throughout the class.

Alternatively you can call MFPPush.GetInstance().methodName() for each instance in which you need to access the push API methods.

Challenge Handlers

If the push.mobileclient scope is mapped to a security check, you need to make sure matching challenge handlers exist and are registered before using any of the Push APIs.

Learn more about challenge handlers in the credential validation tutorial.

Client-side

C Sharp Methods Description
Initialize() Initializes MFPPush for supplied context.
IsPushSupported() Does the device support push notifications.
RegisterDevice(JObject options) Registers the device with the Push Notifications Service.
GetTags() Retrieves the tag(s) available in a push notification service instance.
Subscribe(String[] Tags) Subscribes the device to the specified tag(s).
GetSubscriptions() Retrieves all tags the device is currently subscribed to.
Unsubscribe(String[] Tags) Unsubscribes from a particular tag(s).
UnregisterDevice() Unregisters the device from the Push Notifications Service

Initialization

Initialization is required for the client application to connect to MFPPush service.

  • The Initialize method should be called first before using any other MFPPush APIs.
  • It registers the callback function to handle received push notifications.
MFPPush.GetInstance().Initialize();

Is push supported

Checks if the device supports push notifications.

Boolean isSupported = MFPPush.GetInstance().IsPushSupported();

if (isSupported ) {
    // Push is supported
} else {
    // Push is not supported
}

Register device & send device token

Register the device to the push notifications service.

JObject Options = new JObject();
MFPPushMessageResponse Response = await MFPPush.GetInstance().RegisterDevice(Options);         
if (Response.Success == true)
{
    // Successfully registered
} else {
    // Registration failed with error
}

Get tags

Retrieve all the available tags from the push notification service.

MFPPushMessageResponse Response = await MFPPush.GetInstance().GetTags();
if (Response.Success == true)
{
    Message = new MessageDialog("Avalibale Tags: " + Response.ResponseJSON["tagNames"]);
} else{
    Message = new MessageDialog("Failed to get Tags list");
}

Subscribe

Subscribe to desired tags.

string[] Tags = ["Tag1" , "Tag2"];

// Get subscription tag
MFPPushMessageResponse Response = await MFPPush.GetInstance().Subscribe(Tags);
if (Response.Success == true)
{
    //successfully subscribed to push tag
}
else
{
    //failed to subscribe to push tags
}

Get subscriptions

Retrieve tags the device is currently subscribed to.

MFPPushMessageResponse Response = await MFPPush.GetInstance().GetSubscriptions();
if (Response.Success == true)
{
    Message = new MessageDialog("Avalibale Tags: " + Response.ResponseJSON["tagNames"]);
}
else
{
    Message = new MessageDialog("Failed to get subcription list...");
}

Unsubscribe

Unsubscribe from tags.

string[] Tags = ["Tag1" , "Tag2"];

// unsubscribe tag
MFPPushMessageResponse Response = await MFPPush.GetInstance().Unsubscribe(Tags);
if (Response.Success == true)
{
    //succes
}
else
{
    //failed to subscribe to tags
}

Unregister

Unregister the device from push notification service instance.

MFPPushMessageResponse Response = await MFPPush.GetInstance().UnregisterDevice();         
if (Response.Success == true)
{
    // Successfully registered
} else {
    // Registration failed with error
}

Handling a push notification

In order to handle a push notification you will need to set up a MFPPushNotificationListener. This can be achieved by implementing the following method.

  1. Create a class by using interface of type MFPPushNotificationListener

    internal class NotificationListner : MFPPushNotificationListener
    {
         public async void onReceive(String properties, String payload)
    {
         // Handle push notification here      
    }
    }
    
  2. Set the class to be the listener by calling MFPPush.GetInstance().listen(new NotificationListner())
  3. In the onReceive method you will receive the push notification and can handle the notification for the desired behavior.

Image of the sample application

Windows Universal Push Notifications Service

No specific port needs to be open in your server configuration.

WNS uses regular http or https requests.

Sample application

Click to download the Windows 8.1 Universal project.
Click to download Windows 10 UWP project.

Sample usage

Follow the sample’s README.md file for instructions.

Inclusive terminology note: The Mobile First Platform team is making changes to support the IBM® initiative to replace racially biased and other discriminatory language in our code and content with more inclusive language. While IBM values the use of inclusive language, terms that are outside of IBM's direct influence are sometimes required for the sake of maintaining user understanding. As other industry leaders join IBM in embracing the use of inclusive language, IBM will continue to update the documentation to reflect those changes.
Last modified on February 07, 2017