Get started with Azure Mobile Engagement for Windows Universal Apps

This topic shows you how to use Azure Mobile Engagement to understand your app usage and send push notifications to segmented users of a Windows Universal application. This tutorial demonstrates the simple broadcast scenario using Mobile Engagement. You create a blank Windows Universal App that collects basic app usage data and receives push notifications using Windows Notification Service (WNS).


The Azure Mobile Engagement service will be retired March 2018 and is currently only available to existing customers. For more information, see Mobile Engagement.


This tutorial requires the following:


To complete this tutorial, you must have an active Azure account. If you don't have an account, you can create a free trial account in just a couple of minutes. For details, see Azure Free Trial.

Set up Mobile Engagement for your Windows Universal app

  1. Log on to the Azure Portal.
  2. Click Create a resource, then Web + Mobile, and then Mobile Engagement.

  3. In the New Mobile Engagement App Collection blade that appears, you will be creating an App Collection. Enter the following information:

    • Name: Name of your application collection
    • Platforms: Select target platforms for your app on the Platforms blade which will open up. E.g. if you want an app for both iOS & Android then select both platforms and you will get two apps created under this app collection.

    • Subscription: Select the Azure subscription.
    • Resource group: Select the Azure Resource group in which you want this Azure resource (Mobile Engagement App Collection). You can choose to create a new one.
    • Location: Region where the data about this app collection & app will be stored.
  4. Browse through the Mobile Engagement app collections by clicking Browse and search for Mobile Engagement

  5. You will be shown a list of Mobile Engagement App Collections - make sure you have the same Azure subscription where you created your App Collection.

  6. Click on the App Collection that you created in the prior step to open up the App Collection resource blade which will show the different apps present inside this app collection.

  7. Click on the App created for the platform you are developing for.

  8. Click on Connection Info command button at the top to open up the Connection Info blade and copy the connection string from there.

Connect your app to the Mobile Engagement backend

This tutorial presents a "basic integration," which is the minimal set required to collect data and send a push notification. The complete integration documentation can be found in the Mobile Engagement Windows Universal SDK integration.

You create a basic app with Visual Studio to demonstrate the integration.

Create a Windows Universal App project

The following steps assume the use of Visual Studio 2015 though the steps are similar in earlier versions of Visual Studio.

  1. Start Visual Studio, and in the Home screen, select New Project.
  2. In the pop-up, select Windows -> Universal -> Blank App (Universal Windows). Fill in the app Name and Solution name, and then click OK.

You have now created a Windows Universal App project into which you next integrate the Azure Mobile Engagement SDK.

Connect your app to Mobile Engagement backend

  1. Install the MicrosoftAzure.MobileEngagement Nuget package in your project. If you are targeting both Windows and Windows Phone platforms, you need to do this for both projects. For Windows 8.x and Windows Phone 8.1, the same Nuget package places the correct platform-specific binaries in each project.
  2. Open Package.appxmanifest and make sure that the following capability is added there:

     Internet (Client)

  3. Now copy the connection string that you copied earlier for your Mobile Engagement App and paste it in the Resources\EngagementConfiguration.xml file, between the <connectionString> and </connectionString> tags:


    If your App targets both Windows and Windows Phone platforms, you should still create two Mobile Engagement Applications - one for each supported platform. Having two apps ensures that you can create correct segmentation of the audience and can send appropriately targeted notifications for each platform.


    NuGet does not automatically copy the SDK resources in your Windows 10 UWP application. You have to do it manually following the steps which show up (readme.txt) when the Nuget package is installed.

  4. In the App.xaml.cs file:

    a. Add the using statement:

         using Microsoft.Azure.Engagement;

    b. Add a method that initializes the Engagement:

        private void InitEngagement(IActivatedEventArgs e)
          //... rest of the code

    c. Initialize the SDK in the OnLaunched method:

         protected override void OnLaunched(LaunchActivatedEventArgs e)
           //... rest of the code

    c. Insert the following in the OnActivated method and add the method if it is not already present:

         protected override void OnActivated(IActivatedEventArgs e)
           //... rest of the code

Enable real-time monitoring

To start sending data and ensuring that the users are active, you must send at least one screen (Activity) to the Mobile Engagement backend.

  1. In the MainPage.xaml.cs, add the following using statement:

    using Microsoft.Azure.Engagement.Overlay;

  2. Change the base class of MainPage from Page to EngagementPageOverlay:

     class MainPage : EngagementPageOverlay
  3. In the MainPage.xaml file:

    a. Add to your namespaces declarations:


    b. Replace the Page in the XML tag name with engagement:EngagementPageOverlay


If your page overrides the OnNavigatedTo method, be sure to call base.OnNavigatedTo(e). Otherwise, the activity is not reported EngagementPage calls StartActivity inside its OnNavigatedTo method). This is especially important in a Windows Phone project where the default template has an OnNavigatedTo method.

For Windows 10 Universal apps, use the method recommended in the "Recommended method: overload your Page classes" section of Advanced Reporting with the Windows Universal Apps Engagement SDK, rather than the one mentioned above.

Connect app with real-time monitoring

This section shows you how to connect your app to the Mobile Engagement backend by using the Mobile Engagement's real-time monitoring feature.

  1. In your Azure Mobile Engagement account, make sure you select the app you wish to monitor and manage in the Mobile Engagement portal. Navigate to your Mobile Engagement portal by clicking the Engage button at the bottom.

  2. You will land in the Mobile Engagement portal. If the Monitor tab is not selected, click on the Monitor.
  3. The monitor is ready to show you any device in real time, which will start your app.
  4. Start your app now. You should see one session in the monitor if your integration is correct which means that your app is now connected to the Mobile Engagement backend and is sending data to it.

Enable push notifications and in-app messaging

Mobile Engagement allows you to interact and reach your users with push notifications and in-app messaging in the context of campaigns. This module is called REACH in the Mobile Engagement portal. The following sections set up your app to receive them.

Enable your app to receive WNS Push Notifications

  1. In the Package.appxmanifest file, in the Application tab, under Notifications, set Toast capable: to Yes

Initialize the REACH SDK

In App.xaml.cs, call EngagementReach.Instance.Init(e); in the InitEngagement function right after the agent initialization:

    private void InitEngagement(IActivatedEventArgs e)

You're ready to send a toast. Next we verify that you have correctly carried out this basic integration.

Grant access to Mobile Engagement to send notifications

  1. Open Windows Store Dev Center in your web browser, login, and create an account if necessary.
  2. Click Dashboard at the top right corner and then click Create a new app from the left panel menu.

  3. Create your app by reserving its name.

  4. Once the app has been created, navigate to Services -> Push notifications from the left menu.

  5. In the Push notifications section, click the Live Services site link.

  6. You navigate to the Push credentials section. Make sure you are in the App Settings section and then copy your Package SID and Client secret

  7. Navigate to the Settings of your Mobile Engagement portal, and click the Native Push section on the left. Then, click the Edit button to enter your Package security identifier (SID) and your Secret Key as shown:

  8. Finally make sure that you have associated your Visual Studio app with this created app in the App store. Click Associate App with Store in Visual Studio.

Send a notification to your app

We will now create a simple push notification campaign that sends a push notification to our app.

  1. Navigate to the REACH tab in your Mobile Engagement portal.
  2. Click New announcement to create your push notification campaign.

  3. Set up the first field of your campaign through the following steps:

    a. Provide a Name for your campaign.

    b. Select Delivery time as Any time.

    d. In the notification text - type the Title which will be in bold in the push.

    e. Then type your Message

  4. Scroll down, and in the Content section, select Notification only.

  5. You're done setting the most basic campaign possible. Now scroll down again and click the Create button to save your campaign.
  6. Last step: Click Activate to activate your campaign and to send push notifications.

If the app is running, you see an in-app notification. otherwise if the app is closed, you see a toast notification. If you see an in-app notification but not a toast notification, and you are running the app in debug mode in Visual Studio, then try Lifecycle events -> Suspend in the toolbar to ensure that the app is suspended. If you clicked the Home button while debugging the application in Visual Studio, then it doesn't always get suspended and while you see the notification as in-app, it doesn't show up as a toast notification.