Raw notifications

Raw notifications are a type of push notifications. It is a push notification with an arbitrary payload. You can put anything you want (With size limitations : 4K payload max). It cannot be received directly by your application, but by one of its a background task. So it can be intercepted even if you application is not running. Nice isn’t it?

Preparing the cloud side

The principles are the same as with tiles push notification, you must register to WNS, etc…,check all about it here : Bard’s Tile 3.

The big difference when sending it is that the type must be set to “wns/raw”. Example from Bard’s Tile sample :

protected void SendPushNotification(string uri, string rawdata, string type = "wns/raw")
{
    try
    {
        var contentInBytes = Encoding.UTF8.GetBytes(rawdata);

        var webRequest = HttpWebRequest.Create(uri);

        webRequest.Method = "POST";

        webRequest.Headers.Add("X-WNS-Type", type);
        webRequest.Headers.Add("Authorization", String.Format("Bearer {0}", _accessToken));

        var requestStream = webRequest.GetRequestStream();
        requestStream.Write(contentInBytes, 0, contentInBytes.Length);
        requestStream.Close();

        var webResponse = (HttpWebResponse)webRequest.GetResponse();
    }
    catch (WebException webException)
    {
        // Check here if response is OK (200) or not
    }
    catch (Exception ex)
    {
        // Log exception here
    }

}

Preparing the application

The way to receive a raw notification is very different from push tile notification. It is not your application that will receive it, but a specific background task you must create. Also, very important, your application MUST be on the lock screen to get the notification !

For more about background task, check here.

The steps are :

1. Make your application lock screen capable
2. Create a background task
3. Add background capability in manifest
4. Register the background task
5. Register to a channel WNS

Step 1 : Make your app lock screen capable

You can check Bard’s Tile 5 for how-to.

Step 2 : Create a background task.

Just add a new class library project to your solution. Then create a sealed class that derives from IBackgroundTask :

namespace MyBackgroundTask
{
    public sealed class MyBackgroundTask : IBackgroundTask
    {
        public void Run(IBackgroundTaskInstance taskInstance)
        {
            // Code here
        }
    }
}

Two important things : the class must be sealed, and the project output must be set to WinMD

Step 3 : Add background task in manifest.

You must add the background task capability in your application manifest. The background task must have Push Notification as supported task type :

You must give your class namespace + name as entry point, and BackgroundTaskHost.exe (Or your app executable. For the difference, check the document about background task I mentioned earlier) as launch

Step 4 : Register the task

In your main application, you must now create a background task and register it.

The background task trigger must be, of course, a PushNotificationTrigger :

var builder = new BackgroundTaskBuilder();
builder.Name = "RawNotificationBT";
builder.TaskEntryPoint = "MyBackgroundTask.MyBackgroundTask";     
var trigger = new PushNotificationTrigger();
builder.SetTrigger(trigger);

var task = builder.Register();

Note : you can check the background tasks associated with your application, so you will not register the same twice :

foreach (var task in BackgroundTaskRegistration.AllTasks)
{
    if (task.Value.Name == "RawNotificationBT")
        continue;
}

Step 5 : Register to a channel WNS

Same as with tile push notification, so you can check it here : Bard’s Tile 3.

Consuming Raw Notification

From now, if your application is on the lock screen and you receive a raw notification, the background task will be launched and the Run method will be called.

In the Run method, you can have the Raw Notification using :

var rawnotification = (RawNotification)taskInstance.TriggerDetails;

Then, to get the payload :

var payload = rawnotification.Content;

Communicating with app

Your task can communicate with your applications (If it is launched) using the BackgroudTask Completed event and local settings.

You can register to the event after the task registration :

task.Completed += task_Completed;

void task_Completed(BackgroundTaskRegistration sender, BackgroundTaskCompletedEventArgs args)
{
    if (args.Status == null)
    {
        var settings = ApplicationData.Current.LocalSettings;

        if (settings.Values.Keys.Contains("RawNotificationBT"))
        {
            var payload = settings.Values["RawNotificationBT"];
        }
    }
    else
    {
        // Manage exception here
    }
}

Note that you have to re-register to the event if your application is restarted :

foreach (var task in BackgroundTaskRegistration.AllTasks)
{
    task.Value.Completed += task_Completed;
}

In the backgroundtask, you can save the payload in the local settings.

public void Run(IBackgroundTaskInstance taskInstance)
{
    var rawnotification = (RawNotification)taskInstance.TriggerDetails;

    ApplicationData.Current.LocalSettings.Values["RawNotificationBT"] = rawnotification.Content;

}

Consumer Preview Bug

It can happen that your backgroundtask will not be started, despite the raw notification is received. In that case, you can :

1. Uninstall your app
2. Reboot
3. Re-install your app (Don’t forget to add it again on the lock screen)

Conclusion

This time, raw notifications are a bit different than on phone 7. It is nice you can receive the notification with a backgroundtask, but I wish you could receive it without having to put your application on the lock screen.

A sample application (based on the Bard’s Tile III app) is here.