Push Notifications

Airship’s SDK provides a simple interface for managing push notifications within your Windows app.

Enabling and Disabling Notifications

using UrbanAirship.Push;

// Enable Toast and Tile notifications
// Registers with WNS and UA
// In Win8, if either type is enabled (toast or tile), the app will be able to receive _both_ types of notification.
// Toast and Tile can be enabled separately in Windows Phone 8, so we have carried over that convention to W8 for
// consistency.
PushManager.Shared.EnabledNotificationTypes = NotificationType.Toast|NotificationType.Tile;


// Disable notifications
// Unregisters the device with WNS and UA
PushManager.Shared.EnabledNotificationTypes = NotificationType.None;

Once the application is set up, notifications must be enabled. The code sample to the right shows how to enable and disable Toasts.

Handling Push Events

The Airship library communicates with your app through three main Event types: RegistrationEvent, PushReceivedEvent and PushActivatedEvent.

RegistrationEvent: This event is fired once push registration is complete, both on the Microsoft side and with the Airship server infrastructure. A handler for this event will receive an instance of RegistrationEventArgs, which contains the APID identifier associated with your app, and a boolean indicating whether the APID is valid. If this boolean is true, then your app is fully registered and should now be able to receive push notifications. The library will normally attempt its own retries if registration fails, so in the unlikely case that the boolean is set to false, this indicates a fatal error was encountered (in this case, you should check the logs for a more complete report on the situation).
PushReceivedEvent: This event is fired as soon as a push notification comes in to the app. The library will pass along the relevant notification data in an instance of PushReceivedEventArgs, at which point your application can decide whether to do any additional work with this information. PushReceivedEventArgs contains an instance of UrbanAirship.Push.PushNotification, which encapsulates the notification text as well as the raw content as received by the library.
PushActivatedEvent: This event is fired as soon as a push notification is “activated” by the user, which is when the user clicks the notification while it is displayed on screen. This is a separate event from PushReceivedEvent, which will have already fired by the time this occurs. Handlers for this event will be passed an instance of PushActivatedEventArgs, which is effectively the same as PushReceivedEventArgs, containing an instance of the UrbanAirship.Push.PushNotification class for optional inspection and handling of the push payload.

Note

A Note on EventHandler Synchronization

In the UAirship.TakeOff call, the Airship library captures the current SychronizationContext and uses this to marshall the firing of these events onto the UI thread. In the case where TakeOff is called on a background thread, registration will continue as normal, but a warning will be logged and all events will be fired on the current thread of execution, which may result in your handlers being called on arbitrary background threads. If this can’t be avoided, it can still be mitigated by explicitly synchronizing in your event handlers before touching UI components or other thread-sensitive data, but for the most consistent result we recommend ensuring that TakeOff is called on the UI thread.

Example Event Listeners

//example of a custom registration listener
//this can be customized by the app developer
private class RegistrationEventListener
{
    //constructor, implicitly subscribes to the event
    public RegistrationEventListener()
    {
        PushManager.Shared.RegistrationEvent += RegistrationComplete;
    }
    //unsubscribes from the event
    public void Detach()
    {
        PushManager.Shared.RegistrationEvent -= RegistrationComplete;
    }
    //called when the event fires
    private void RegistrationComplete(object sender, RegistrationEventArgs e)
    {
        Logger.Info("Registration complete, apid: " + e.Apid + " valid: " + e.IsValid);
    }
}

//example of a custom push received listener
//this can be customized by the app developer
private class PushReceivedEventListener
{
    //constructor, implicitly subscribes to the event
    public PushReceivedEventListener()
    {
        PushManager.Shared.PushReceivedEvent += PushReceived;
    }
    //unsubscribes from the event
    public void Detach()
    {
        PushManager.Shared.PushReceivedEvent -= PushReceived;
    }
    //called when the event fires
    private void PushReceived(object sender, PushReceivedEventArgs e)
    {
        Logger.Info("Push received!");
        UrbanAirship.Push.PushNotification notification = e.Notification;

        if (notification.Type == UrbanAirship.Push.NotificationType.Toast)
        {
            ToastNotificationData data = notification.ToastData;
            Logger.Info("Text: ");
            foreach (var item in data.Text)
            {
                Logger.Info(item);
            }
            //if needed, the full XML payload is included for further inspection
            XmlDocument payload = (XmlDocument)data.Payload;
            Logger.Info("Full XML payload:");
            Logger.Info(payload.GetXml());
        }
    }
}

//example of a custom push activated listener
//this can be customized by the app developer
private class PushActivatedEventListener
{
    //constructor, implicitly subscribes to the event
    public PushActivatedEventListener()
    {
    PushManager.Shared.PushActivatedEvent += PushActivated;
    }
    //unsubscribes from the event
    public void Detach()
    {
        PushManager.Shared.PushActivatedEvent -= PushActivated;
}
//called when the event fires
private void PushActivated(object sender, PushActivatedEventArgs e)
{
    Logger.Info("Push activated!");
    UrbanAirship.Push.PushNotification notification = e.Notification;

    if (notification.Type == UrbanAirship.Push.NotificationType.Toast)
    {
        ToastNotificationData data = notification.ToastData;
        Logger.Info("Text: ");
        foreach (var item in data.Text)
        {
            Logger.Info(item);
        }
        //if needed, the full XML payload is included for further inspection
        XmlDocument payload = (XmlDocument)data.Payload;
        Logger.Info("Full XML payload:");
        Logger.Info(payload.GetXml());
    }
}
}

// Add the listeners as private fields to be set in the constructor in the block above
private RegistrationEventListener registrationListener;
private PushReceivedEventListener pushReceivedListener;
private PushActivatedEventListener pushActivatedListener;

Handling the Toast Launch String

Toast notifications can be sent with a launch string. A launch string is an arbitrary value that will be passed to your application’s OnLaunched handler.

App.xaml.cs

protected override void OnLaunched(LaunchActivatedEventArgs args)
{
        Logger.Debug("Toast Launch String: " + args.Arguments);

        // Additional launch actions here
}

Windows Push

WNS has several features not present in other platforms. These can be specified in the wns override in the notification object.

Toast Notifications

Toast notifications are unique to Windows devices and can be specified as an attribute within the platform override for WNS notifications. In the example below, we specify the text in a toast alert in the wns object. A toast notification requires at least one visual element. For more information see Toast schema .

{
   "audience": "all",
   "notification": {
      "wns": {
         "toast": {
            "binding": {
               "text": [
                  "Hello Airship!"
               ],
               "template": "ToastText01"
            }
         }
      }
   },
   "device_types": ["wns"]
}

Deep Link

Use the param key to specify an optional URI parameter that specifies an XAML page to open in your app, along with any query string parameters.

{
   "audience": "all",
   "notification": {
      "wns": {
         "toast": {
            "text2": "This Just In!",
            "text1": "New developments",
            "param": "BreakingNewsPage.xaml?item=4"
         }
      }
   },
   "device_types": ["wns"]
}

Audio

Optionally specify the toast alert sound with the audio key in the notification object.

{
   "audience": "all",
   "notification": {
      "wns": {
         "toast": {
            "binding": {
               "text": [
                  "Hello Airship!"
               ],
               "template": "ToastText01"
            },
            "audio": {
               "sound": "reminder"
            }
         }
      }
   },
   "device_types": ["wns"]
}

Duration

Optionally specify a display duration for your toast. There are two values: “short” (the default) and “long”. Use “long” only if your notification is part of a scenario such as an incoming call or appointment reminder. For more information

Windows devices have the ability to set the duration of a toast to be displayed on the device.

{
   "audience": "all",
   "notification": {
      "wns": {
         "toast": {
            "duration": "short"
         },
         "binding": {
            "text": [
               "Hello Airship!"
            ],
            "template": "ToastText01"
         }
      }
   },
   "device_types": ["wns"]
}

Templates

Windows devices have the ability to specify a templated toast notification from Microsoft’s list of Toast Templates document.

{
   "audience": "all",
   "notification": {
      "wns": {
         "toast": {
            "binding": {
               "text": [
                  "Hello Airship!"
               ],
               "template": "ToastText01"
            }
         }
      }
   },
   "device_types": ["wns"]
}

Badge Value

Windows 8 devices have the ability to to specify a badge value to be used to set a number on the application tile, usually representing unread messages or waiting actions inside the application.

{
   "audience": "all",
   "notification": {
      "wns": {
         "badge": {
            "value": "1"
         }
      }
   },
   "device_types": ["wns"]
}

Badge Glyph

In addition to numbers, there is also a fixed set of image glyphs that can be set on the badge.

{
   "audience": "all",
   "notification": {
      "wns": {
         "badge": {
            "glyph": "busy"
         }
      }
   },
   "device_types": ["wns"]
}

Tiles

Windows Phones have the ability to update live tiles on the home screen. With the use of templates, you can update any tile on the home screen.

{
   "audience": "all",
   "notification": {
      "wns":{
         "tile": {
            "count": 11,
            "wide_content_1": "Wide Content 1",
            "wide_content_2": "Wide Content 2",
            "wide_content_3": "Wide Content 3",
            "title": "Title",
            "template": "IconicTile",
            "background_color": "#FFAA0000"
         }
      }
   },
   "device_types": ["wns"]
}

{
   "audience": "all",
   "notification": {
      "wns": {
         "tile": {
            "binding": [
               {
                  "text": [
                     "TileWideImageAndText01"
                  ],
                  "image": [
                        "/Assets/1.jpg"
                  ],
                 "template": "TileWideImageAndText01"
               }
            ]
         }
      }
   },
   "device_types": ["wns"]
}

Feedback

Was this page helpful?