App Center Push for Universal Windows Platform

App Center Push enables you to send push notifications to users of your app from the App Center portal and relies on Windows Notification Services (WNS) to push notifications to the devices.

Note

The device displays a toast only if the application is in background at the moment the Push is received.

Prerequisite - Register your app for Windows Notification Services (WNS)

Before you can send notification using WNS, your app must be registered with the Windows Store. This will provide you with credentials for your app that App Center will use to authenticate with WNS. These credentials consist of a Package Security Identifier (SID) and an application secret key. To perform this registration, you need to associate your app with the Windows Store in Visual Studio.

1. Windows Store Association in Visual Studio

  1. In Visual Studio Solution Explorer, right-click the UWP project, then select Store -> Associate App with the Store...

    uwp store association

  2. In the wizard, click Next, sign in with your Windows developer account, type a name for your app in Reserve a new app name, then click Reserve.

  3. After completing the app registration, select the new app name, click Next, and then click Associate. This adds the required Windows Store registration information to the application manifest.

Note

You must have a Windows Developer account to send push notifications to your UWP app. You can register a Microsoft developer account if you don't already have one.

2. Get the Package SID and Application secret from the Partner Center

  1. Navigate to the Microsoft Partner Center, sign-in with the same account you used when you reserved the app name. Click the Windows Store app you associated in the previous step.

  2. Go to the WNS/MPNS section of the Product Management page and click on the Live Services link. It will display the old Microsoft Application Registration portal settings page.

    uwp app registration

  3. Below at this page in the Platforms > Windows store section, copy the value of the Package SID as you will use it later.

    uwp app registration sid

  4. At the top of this page, copy the value under Application Secrets as you will use it later.

    uwp app registration

  5. Prepend the copied on the 2nd step Package SID with the ms-app:// value.

  6. Use the Application secret and Package SID values to configure your App Center Push backend.

3. Configure Package SID and Security Key in App Center portal

  1. Login to App Center.
  2. Select the application in the left navigator, then select the Push section.
  3. Click Next button to get to the configuration page.
  4. Enter Package SID and Security key that you obtained from the Microsoft Application Registration Portal in the previous step.
  5. Click Apply changes.

Add App Center Push to your app

Please follow the Get started section if you haven't set up and started the SDK in your application.

1. Add the App Center Push package

The App Center SDK is designed with a modular approach – a developer only needs to integrate the modules of the services that they're interested in. It can be integrated using Visual Studio or Package Manager Console.

Visual Studio for Mac

  • Open Visual Studio for Mac.
  • Click File > Open and choose your solution.
  • In the solution navigator, right click the Packages section, and choose Add NuGet packages....
  • Search for App Center, and install App Center Push.
  • Click Add Packages.

Visual Studio for Windows

  • Open Visual Studio for Windows.
  • Click File > Open and choose your solution.
  • In the solution navigator, right-click References and choose Manage NuGet Packages.
  • Search for App Center, and install Microsoft.AppCenter.Push.

Package Manager Console

  • Open the console in Visual Studio. To do this, choose Tools > NuGet Package Manager > Package Manager Console.
  • If you're working in Visual Studio for Mac, make sure you have NuGet Package Management Extensions installed. For this, choose Visual Studio > Extensions, search for NuGet and install, if necessary.
  • Type the following command in Package Manager Console:
Install-Package Microsoft.AppCenter.Push

Note

If you use the App Center SDK in a portable project (such as Xamarin.Forms), you must install the packages in each of the projects: the portable, Android, and iOS ones. To do that, you should open each sub-project and follow the corresponding steps described in Visual Studio for Mac or Visual Studio for Windows sections.

Note

If your Android project does not target the Mono framework version 9.0 or higher, you will not be able to install the package. You can safely bump this version in Options > General > Target framework as this has no impact on minimum API level or target API level fields.

Now that you've integrated App Center Push in your application, it's time to start the SDK and make use of App Center.

2. Start App Center Push

In order to use App Center, you must opt in to the module(s) that you want to use. By default no modules are started and you will have to explicitly call each of them when starting the SDK.

Add the following using statement to the top of the file you are referencing Push from:

using Microsoft.AppCenter.Push

Next, add typeof(Push) to your AppCenter.Start() method to start App Center Push.

AppCenter.Start("{Your App Secret}", typeof(Push));

Make sure you have replaced {Your App Secret} in the code sample above with your app secret.

Note

If your UWP project is part of a Xamarin.Forms application, it is not necessary to add the call to AppCenter.Start() in the UWP portion of the project. The method call can instead be made from the PCL or shared project portion of your Xamarin.Forms application in the OnStart callback.

Intercept push notifications

App Center Push makes it possible to intercept push notifications but there is some setup required to enable this feature in UWP.

Additional setup

Call Push.CheckLaunchedFromNotification(e); at the end of the OnLaunched method in your UWP application source file (not in the portable application file if you use Xamarin.Forms).

protected override void OnLaunched(LaunchActivatedEventArgs e)
{
    // other code...

    // This should be the last instruction
    Push.CheckLaunchedFromNotification(e);
}

Note

  • If you use Xamarin.Forms, make sure the AppCenter.start call is made in the OnStart callback of the Xamarin.Forms application class.
  • If you don't use Xamarin.Forms, make sure the AppCenter.start call is made in the application constructor or before Push.CheckLaunchedFromNotification.

Subscribe to the push event

You can subscribe to the Push.PushNotificationReceived event to be notified whenever a push notification is received in the foreground or a background push notification has been clicked by the user.

Note

No toast is shown when the push is received in foreground.

Note

If the push is received in background, the event is NOT triggered at receive time. The event is triggered when you click on the notification.

Note

UWP toasts do NOT expose title and message to the background notification click callback. Title and message are only available in foreground pushes.

The following example demonstrates how to use the push event.

// This should come before AppCenter.Start() is called
// Avoid duplicate event registration:
if (!AppCenter.Configured)
{
    Push.PushNotificationReceived += (sender, e) =>
    {
        // Add the notification message and title to the message
        var summary =  $"Push notification received:" +
                            $"\n\tNotification title: {e.Title}" +
                            $"\n\tMessage: {e.Message}";
    
        // If there is custom data associated with the notification,
        // print the entries
        if (e.CustomData != null)
        {
            summary += "\n\tCustom data:\n";
            foreach (var key in e.CustomData.Keys)
            {
                summary += $"\t\t{key} : {e.CustomData[key]}\n";
            }
        }

        // Send the notification summary to debug output
        System.Diagnostics.Debug.WriteLine(summary);
    };
}

// AppCenter.start after
AppCenter.Start(..., ... ,typeof(Push), ...);

Custom data in your notifications

You can send optional custom data as part of the push payload. The data will be sent in the key-value format. This custom data can be intercepted in the app through Push SDK callback.

There are few reserved keywords that can be set via custom data.

Reserved keywords in Windows platform

  • audio: Add this key when you want the to play a sound. this will modify the audio attribute for toast notifications.
  • image: Add this key when you want to modify the image attribute for tile and toast notifications.

Enable or disable App Center Push at runtime

You can enable and disable App Center Push at runtime. If you disable it, the SDK will stop updating the registration identifier that is used to push notifications, but the existing one will continue to work. In other words, disabling the App Center Push in the SDK will NOT stop your application from receiving push notifications.

Push.SetEnabledAsync(false);

To enable App Center Push again, use the same API but pass true as a parameter.

Push.SetEnabledAsync(true);

You don't need to await this call to make other API calls (such as IsEnabledAsync) consistent.

The state is persisted in the device's storage across application launches.

Note

This method must only be used after Push has been started.

Check if App Center Push is enabled

You can also check if App Center Push is enabled or not:

bool isEnabled = await Push.IsEnabledAsync();

Note

This method must only be used after Push has been started, it will always return false before start.