# Windows Integrate the Airship SDK into your Windows applications. (Deprecated) # Getting Started > The Airship Windows SDK supports Windows and Windows Phone devices, including Windows 10. > **Important:** Windows platform support is deprecated. Apps targeting Windows Phone 8.1 and higher should use the [Universal Library](#universal-library), which is compatible with Windows Desktop and Windows Phone via the WNS push service. 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: * [UX guidelines for tiles and notifications](https://msdn.microsoft.com/en-us/library/windows/apps/dn611865.aspx) * [Windows Push Notification Services (WNS) overview](https://docs.microsoft.com/en-us/windows/uwp/controls-and-patterns/tiles-and-notifications-windows-push-notification-services--wns--overview) ## Supported Features 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 the dashboard. We support Toast Templates at the API level as well. See [Windows Push](https://www.airship.com/docs/developer/sdk-integration/windows/push-notifications/#windows-push) for examples of tiles and toast notifications. ## 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 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 with Airship have an associated key, secret and master secret, which are strings used in authentication with the 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. > **Warning:** 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 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)](https://docs.microsoft.com/en-us/windows/uwp/controls-and-patterns/tiles-and-notifications-windows-push-notification-services--wns--overview) service API keys from Microsoft. 1. For Windows 8+ and Windows Phone 8.1+ (WNS) see [How to authenticate with the Windows Push Notification Service (WNS) (Windows Runtime apps)](https://msdn.microsoft.com/en-us/library/windows/apps/hh465407.aspx). 1. Read our client documentation. (Below) 1. Integrate our client library into your development application, per the documentation. 1. Configure the Windows service in the [Dashboard](https://www.airship.com/docs/reference/glossary/#dashboard). 1. 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)](https://msdn.microsoft.com/en-us/library/windows/apps/hh465407) 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 Project with Airship It is customary on Airship to create two separate projects in the [Dashboard](https://www.airship.com/docs/reference/glossary/#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. > **Note:** You will need your Windows Push Notification Services (WNS): > > * Package security identifier (SID) > * Secret key > > You can find these in the [Partner Center](https://partner.microsoft.com/dashboard); follow the instructions on the App Management - WNS/MPNS page. 1. Next to your project name, select the dropdown menu (▼), then **Settings**. 1. Under **Channels**, select **Windows**. 1. Enter your SID and secret key. 1. 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) 1. Copy the `UrbanAirshipLibrary` folder to a location in your project path. 1. Add a reference to `UrbanAirship.winmd`. ### Initialize the Airship Library The library must be initialized with your 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 Development Key Development Secret Verbose false Production App Key Production App Secret Error ``` 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 Airship Library **`App.xaml.cs`** ```c# using UrbanAirship; using UrbanAirship.Push; //... /// /// 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(). /// public App() { this.InitializeComponent(); this.Suspending += OnSuspending; // Initialize and register Airship event listeners // See example implementations below this.registrationListener = new RegistrationEventListener(); this.pushReceivedListener = new PushReceivedEventListener(); this.pushActivatedListener = new PushActivatedEventListener(); } /// /// 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. /// /// Details about the launch request and process. 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 Airship 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 programmatically: ```c# AirshipConfig config = new AirshipConfig(); config.DevelopmentAppKey = "DevelopmentAppKey"; config.DevelopmentAppSecret = "DevelopmentAppSecret"; config.ProductionAppKey = "ProductionAppKey"; config.productionAppSecret = "ProductionAppSecret"; #if DEBUG config.InProduction = false; #else config.InProduction = true; #endif UAirship.TakeOff(config); ``` ## 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`). 1. On the *Declarations* tab, Add a *Background Task*. 1. Set the task type to *System event*. 1. Set the *Entry Point* to `UrbanAirship.Push.WNSChannelRenewalTask`. ![Background task declaration in the app manifest](https://www.airship.com/docs/images/w8_manifest_background_task_hu_d24a795919af8465.webp) *Background task declaration in the app manifest* # Push Notifications > Airship's SDK provides a simple interface for managing push notifications within your Windows app.> **Important:** Windows platform support is deprecated. ## Enabling and Disabling Notifications ```c# 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 ```c# //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`** ```c# protected override void OnLaunched(LaunchActivatedEventArgs args) { Logger.Debug("Toast Launch String: " + args.Arguments); // Additional launch actions here } ``` ## Windows Push {#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} 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](https://docs.microsoft.com/en-us/uwp/schemas/tiles/toastschema/schema-root). ```json { "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. ```json { "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. ```json { "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. ```json { "audience": "all", "notification": { "wns": { "toast": { "duration": "short" }, "binding": { "text": [ "Hello Airship!" ], "template": "ToastText01" } } }, "device_types": ["wns"] } ``` #### Templates {#toast-templates} Windows devices have the ability to specify a templated toast notification from Microsoft's list of [Toast Templates](https://docs.microsoft.com/en-us/uwp/api/Windows.UI.Notifications.ToastTemplateType) document. ```json { "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. ```json { "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. ```json { "audience": "all", "notification": { "wns": { "badge": { "glyph": "busy" } } }, "device_types": ["wns"] } ``` ### Tiles {#live-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. ```json { "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"] } ``` ```json { "audience": "all", "notification": { "wns": { "tile": { "binding": [ { "text": [ "TileWideImageAndText01" ], "image": [ "/Assets/1.jpg" ], "template": "TileWideImageAndText01" } ] } } }, "device_types": ["wns"] } ``` # Segmentation > You can define your audience based on tags, alias, and APID.> **Important:** Windows platform support is deprecated. ## Setting Tags and an Alias ```c# using UrbanAirship.Push; // Create a list of tags (tags must be an IList) List tagList = new List(); 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.