map-o file-code-o arrow-directionplatform-webreach-project-type-boarding-passreach-project-type-couponreach-project-type-event-ticketreach-project-type-genericreach-project-type-gift-cardreach-project-type-loyalty-cardreach-project-type-member-card pictures more_vert chain keyboard_arrow_down keyboard_arrow_right

Windows

The Urban Airship Windows SDK supports Windows and Windows Phone devices, including Windows 10. Apps targeting Windows Phone 8.1 and higher should use the Universal Library, which is compatible with Windows Desktop and Windows Phone via the WNS push service.

Getting Started

Windows devices provide a unique notification user experience with live tiles, a set of app icon assets that can be customized to reflect your app’s branding.

Windows devices also support toast notifications, the familiar non-modal notification element often used to display a short, auto-expiring message in many Android and desktop applications.

For details on the Windows notification user experience, see the following resources from Microsoft:

Supported Features

Urban Airship provides Support for Live Tiles and Toast notifications. We support Tiles at the API Level only, and Toast both at the API level and in in our Message Composer.

We support Toast Templates at the API level as well.

See below for API and User Guide documentation on all supported Windows notification features.

Live Tiles

Toast Notifications

Toast Templates

Key Terminology

APID
Sometimes also described as a “Push ID”, and APID is an app-level device identifier that can be used to target specific devices with push notifications. All Windows apps using the Urban Airship library are assigned an APID, which takes the form of a UUID string, such as e3d35643-26d3-4b0e-c632-959291744a02.
App Key and Secret
All applications registered on the Urban Airship dashboard have an associated key, secret and master secret, which are strings used in authentication with the Urban Airship REST API. The app key is effectively an identifier. The app secret is used in authentication on the client side during registration.
Master Secret
There is also another secret, known as the master secret, that is used in authentication for REST API actions such as sending push notifications. This is the only one of these that should be kept truly secret, because with this, anyone could could send push notifications on your behalf.

Always keep the master secret safe, and be sure never to expose it in your application code.

To obtain these strings, create a new application on the Urban Airship dashboard or log in to your existing app. In the sidebar on the left side of the screen, click Details. In the resulting window, you should find the key and secret at the top of the list. Here is an overview of the steps:

Configure Services

  1. Secure your Windows Push Notification Services (WNS) service API keys from Microsoft.
  2. For Windows 8+ and Windows Phone 8.1+ (WNS) see How to authenticate with the Windows Push Notification Service (WNS) (Windows Runtime apps).
  3. Download the latest Urban Airship SDK here.
  4. Read our client documentation. (Below)
  5. Integrate our client library into your development application, per the documentation.
  6. Configure the Windows service in the Urban Airship web application.
  7. Follow the instructions in our Windows Integration documentation.
  8. Deploy your application to the Windows Store.

Universal Library

This document provides reference information for implementing a client for a Windows desktop, phone or tablet (e.g. Surface tablet) device.

Set Up Your Application in the Windows Store

In order to be able to receive push notifications, you must set up your application in the Windows Store. If your app is not already registered with the Windows Store, please review How to authenticate with the Windows Push Notification Service (WNS) on MSDN, and follow the instructions before continuing.

Once your app is registered with the Windows Store, and you have logged in as a developer, navigate to: App »» Advanced Features »» Push notifications and Live Connect services info. If you are submitting a Windows Phone 8.1 app, log in to the Windows Phone Dev Center, select your app, then navigate to the Details tab and look for the WNS heading. You will need to make note of the following pieces of information:

  • CN and Identity Name: Under the “Identifying your app” link on the sidebar.
  • SID and Client Secret: Under the “Authenticating your service” link on the sidebar

The CN and Identity Name must now be added to your package manifest. You can set them manually on the “Packaging” tab, or you can let Visual Studio automatically associate your project with the application in the Windows Store by right clicking on the project and selecting Store->Associate App with the Store.

Set Up Your Application with Urban Airship

It is customary on Urban Airship to create two separate apps in the dashboard, one for development and one for production. If you haven’t already, perform this step now. In order to keep them distinct, it is recommended to choose names that reflect their purpose in the development lifecycle, e.g. “My Development App” vs. “My Production App”. Repeat the process below for each app:

  • Go to your application in the Urban Airship dashboard
  • Click Settings gear icon
  • Click Services
  • Click Configure for Microsoft Windows Push Notification Service (WNS)
  • Enter your SID
  • Enter your client secret
  • Click Save

Client Library

Add UrbanAirship.winmd

To add the UrbanAirship runtime component to your application:

  1. Unzip the distribution file (urban-airship-windows-.zip)
  2. Copy the UrbanAirshipLibrary folder to a location in your project path.
  3. Add a reference to UrbanAirship.winmd.

Initialize the Urban Airship Library

The library must be initialized with your Urban Airship application key and application secret. If you have created separate applications for development and production, as is recommended above, this is a good opportunity to specify the key/secret pair for each mode.

Add airshipconfig.xml to your project

airshipconfig.xml

<?xml version="1.0" encoding="utf-8" ?>
<AirshipConfig>
        <!-- NOTE: These elements must be in alphabetical order. -->
        <DevelopmentAppKey>Development Key</DevelopmentAppKey>
        <DevelopmentAppSecret>Development Secret</DevelopmentAppSecret>
        <DevelopmentLogLevel>Verbose</DevelopmentLogLevel>
        <InProduction>false</InProduction>
        <ProductionAppKey>Production App Key</ProductionAppKey>
        <ProductionAppSecret>Production App Secret</ProductionAppSecret>
        <ProductionLogLevel>Error</ProductionLogLevel>
</AirshipConfig>

This file contains all the settings your app needs to register and receive push notifications. These settings can also be defined programmatically; see the integration section for details.

Initialize the Urban Airship Library

App.xaml.cs

using UrbanAirship;
using UrbanAirship.Push;

//...

/// <summary>
/// Initializes the singleton application object. This is the first line of authored code
/// executed, and as such is the logical equivalent of main() or WinMain().
/// </summary>
public App()
{
        this.InitializeComponent();
        this.Suspending += OnSuspending;

        // Initialize and register UA event listeners
        // See example implementations below
        this.registrationListener = new RegistrationEventListener();
        this.pushReceivedListener = new PushReceivedEventListener();
        this.pushActivatedListener = new PushActivatedEventListener();
}

/// <summary>
/// Invoked when the application is launched normally by the end user. Other entry points
/// will be used when the application is launched to open a specific file, to display
/// search results, and so forth.
/// </summary>
/// <param name="args">Details about the launch request and process.</param>
protected override void OnLaunched(LaunchActivatedEventArgs args)
{
        Logger.Debug("Launched with: " + args.Arguments);
        Frame rootFrame = Window.Current.Content as Frame;
        // Do not repeat app initialization when the Window already has content,
        // just ensure that the window is active
        if (rootFrame == null)
        {
                // Create a Frame to act as the navigation context and navigate to the first page
                rootFrame = new Frame();
                if (args.PreviousExecutionState == ApplicationExecutionState.Terminated)
                {
                        //TODO: Load state from previously suspended application
             }
                // Place the frame in the current Window
                Window.Current.Content = rootFrame;
        }
        if (rootFrame.Content == null)
        {
                // When the navigation stack isn't restored navigate to the first page,
                // configuring the new page by passing required information as a navigation
                // parameter
                if (!rootFrame.Navigate(typeof(MainPage), args.Arguments))
                {
                        throw new Exception("Failed to create initial page");
                }
        }
        // Ensure the current window is active
        Window.Current.Activate();

        //Initialize and setup UA library
        var config = AirshipConfig.ReadConfig("airshipconfig.xml");
        UAirship.TakeOff(config);
        config.DebugLog();
        PushManager.Shared.EnabledNotificationTypes = NotificationType.Toast;
}

Configure Keys and Secrets in Code

These configuration values can also be set programatically:

AirshipConfig config = new AirshipConfig();
config.DevelopmentAppKey = "DevelopmentAppKey";
config.DevelopmentAppSecret = "DevelopmentAppSecret";
config.ProdutionAppKey = "ProductionAppKey";
config.productionAppSecret = "ProductionAppSecret";

#if DEBUG
config.InProduction = false;
#else
config.InProduction = true;
#endif

UAirship.TakeOff(config);

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.

Setting Tags and an Alias

using UrbanAirship.Push;

// Create a list of tags (tags must be an IList<string>)
List<string> tagList = new List<string>();
tagList.Add("ATag");
tagList.Add("AnotherTag");

// Update the APID with the attributes set in the UI
// Set the new values first here
PushManager.Shared.Alias = "AnAliasString";
PushManager.Shared.Tags = this.Tags;

// Now update them on the server
// This does not need to be called if setting the tags or alias prior
// to calling TakeOff()
PushManager.Shared.UpdateRegistration();

The APID is the primary push address for this application and device, but you may also register a set of tags or an alias for this APID.

Handling Push Events

The Urban 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 Urban 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.

A Note on EventHandler Synchronization

In the UAirship.TakeOff call, the Urban 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
}

Manifest Permissions

To enable push notifications in your Windows Store app, you will need to add several items to your app’s manifest (Package.appxmanifest). The items below are organized by tab

Application UI

On the “Application UI” tab, make sure that “Toast capable” is checked.

Capabilities

Make sure that “Internet” is checked.

Declarations

Push Channels have an expiration date and must be renewed periodically. To ensure that the channel is renewed even if the user hasn’t launched the app recently, our library schedules a background task that will perform the renewal in the background.

  1. Open the manifest (Package.appxmanifest)
  2. On the “Declarations” tab, Add a “Background Task”.
  3. Set the task type to “System event”
  4. Set the “Entry Point” to UrbanAirship.Push.WNSChannelRenewalTask.