Get Started with Azure Mobile Engagement for iOS Apps in Swift

This topic shows you how to use Azure Mobile Engagement to understand your app usage and send push notifications to segmented users to an iOS application. In this tutorial, you create a blank iOS app that collects basic data and receives push notifications using Apple Push Notification System (APNS).

This tutorial requires the following:

  • XCode 8, which you can install from your MAC App Store
  • the Mobile Engagement iOS SDK
  • Push notification certificate (.p12) that you can obtain on your Apple Dev Center


This tutorial uses Swift version 3.0.

Completing this tutorial is a prerequisite for all other Mobile Engagement tutorials for iOS apps.


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.

Setup Mobile Engagement for your iOS 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 iOS SDK integration

We will create a basic app with XCode to demonstrate the integration:

Create a new iOS project

  1. Start Xcode and in the pop-up, select Create a new Xcode project.

  2. Select Single View Application, and then click Next.

  3. Fill in the Product Name, Organization Name, and Organization Identifier. Select Objective-C or Swift in the Language selection based on your app.


Make sure that the Bundle Identifier matches with what you have defined in the Apple Developer console for AppId and that you have a corresponding certificate for it.

Xcode will create the demo app into which we integrate Mobile Engagement.

Connect your app to Mobile Engagement backend

  1. Download the Mobile Engagement iOS SDK
  2. Extract the .tar.gz file to a folder in your computer
  3. Right click the project and select "Add files to ..."

  4. Navigate to the folder where you extracted the SDK and select the EngagementSDK folder then press OK.

  5. Open the Build Phases tab and in the Link Binary With Libraries menu add the frameworks as shown below:

  6. Create a Bridging header to be able to use the SDK's Objective C APIs by choosing File > New > File > iOS > Source > Header File.

  7. Edit the bridging header file to expose Mobile Engagement Objective-C code to your Swift code, add the following imports :

     /* Mobile Engagement Agent */
     #import "AEModule.h"
     #import "AEPushMessage.h"
     #import "AEStorage.h"
     #import "EngagementAgent.h"
     #import "EngagementTableViewController.h"
     #import "EngagementViewController.h"
     #import "AEUserNotificationHandler.h"
     #import "AEIdfaProvider.h"
  8. Under Build Settings, make sure the Objective-C Bridging Header build setting under Swift Compiler - Code Generation has a path to this header. Here is a path example: $(SRCROOT)/MySuperApp/MySuperApp-Bridging-Header.h (depending on the path)

  9. Go back to the Azure portal in your app's Connection Info page and copy the Connection String

  10. Now paste the connection string in the didFinishLaunchingWithOptions delegate

    func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplicationLaunchOptionsKey: Any]?) -> Bool

Enabling real-time monitoring

In order 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. Open the ViewController.swift file and replace the base class of ViewController to be EngagementViewController:

    class ViewController : EngagementViewController {

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.

Enabling Push Notifications and in-app messaging

Mobile Engagement allows you to interact and REACH with 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 will setup your app to receive them.

Enable your app to receive Silent Push Notifications


To receive Push Notifications from Mobile Engagement, you need to enable Silent Remote Notifications in your application. You need to add the remote-notification value to the UIBackgroundModes array in your Info.plist file.

  1. Open info.plist file in the project
  2. Right click on the top item in the list (Information Property List) and add a new row

  3. In the new row enter Required background modes

  4. Click on the left arrow to expand the row
  5. Add the following value to the item 0 App downloads content in response to push notifications

  6. Once you make the change, the info.plist XML should contain the following key and value:

  7. If you are using Xcode 7+ and iOS 9+:

    • Enable Push Notifications in Targets > Your Target Name > Capabilities.

Add the Reach library to your project

  1. Right click your project
  2. Select Add file to ...
  3. Navigate to the folder where you extracted the SDK
  4. Select the EngagementReach folder
  5. Click Add
  6. Edit the bridging header file to expose Mobile Engagement Objective-C Reach headers and add the following imports :

     /* Mobile Engagement Reach */
     #import "AEAnnouncementViewController.h"
     #import "AEAutorotateView.h"
     #import "AEContentViewController.h"
     #import "AEDefaultAnnouncementViewController.h"
     #import "AEDefaultNotifier.h"
     #import "AEDefaultPollViewController.h"
     #import "AEInteractiveContent.h"
     #import "AENotificationView.h"
     #import "AENotifier.h"
     #import "AEPollViewController.h"
     #import "AEReachAbstractAnnouncement.h"
     #import "AEReachAnnouncement.h"
     #import "AEReachContent.h"
     #import "AEReachDataPush.h"
     #import "AEReachDataPushDelegate.h"
     #import "AEReachModule.h"
     #import "AEReachNotifAnnouncement.h"
     #import "AEReachPoll.h"
     #import "AEReachPollQuestion.h"
     #import "AEViewControllerUtil.h"
     #import "AEWebAnnouncementJsBridge.h"

Modify your Application Delegate

  1. Inside the didFinishLaunchingWithOptions - create a reach module and pass it to your existing Engagement initialization line:

     func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplicationLaunchOptionsKey: Any]?) -> Bool 
         let reach = AEReachModule.module(withNotificationIcon: UIImage(named:"icon.png")) as! AEReachModule
         EngagementAgent.init("Endpoint={YOUR_APP_COLLECTION.DOMAIN};SdkKey={YOUR_SDK_KEY};AppId={YOUR_APPID}", modulesArray:[reach])
         return true

Enable your app to receive APNS Push Notifications

  1. Add the following line to the didFinishLaunchingWithOptions method:

     if #available(iOS 8.0, *)
         if #available(iOS 10.0, *)
             UNUserNotificationCenter.current().requestAuthorization(options: [.alert, .badge, .sound]) { (granted, error) in }
             let settings = UIUserNotificationSettings(types: [.alert, .badge, .sound], categories: nil)
         application.registerForRemoteNotifications(matching: [.alert, .badge, .sound])
  2. Add the didRegisterForRemoteNotificationsWithDeviceToken method as follows:

     func application(_ application: UIApplication, didRegisterForRemoteNotificationsWithDeviceToken deviceToken: Data) {
  3. Add the didReceiveRemoteNotification:fetchCompletionHandler: method as follows:

     func application(_ application: UIApplication, didReceiveRemoteNotification userInfo: [AnyHashable : Any], fetchCompletionHandler completionHandler: @escaping (UIBackgroundFetchResult) -> Void) {
         EngagementAgent.shared().applicationDidReceiveRemoteNotification(userInfo, fetchCompletionHandler:completionHandler)

Grant access to your Push Certificate to Mobile Engagement

To allow Mobile Engagement to send Push Notifications on your behalf, you need to grant it access to your certificate. This is done by configuring and entering your certificate into the Mobile Engagement portal. Make sure you obtain your .p12 certificate as explained in Apple's documentation

  1. Navigate to your Mobile Engagement portal. Ensure you're in the correct and then click on the Engage button at the bottom:

  2. Click on the Settings page in your Engagement Portal. From there click on the Native Push section to upload your p12 certificate:

  3. Select your p12, upload it and type your password:

Send a notification to your app

We will now create a simple Push Notification campaign that will send a push to our app:

  1. Navigate to the Reach tab in your Mobile Engagement portal.
  2. Click New Announcement to create your push campaign

  3. Setup the first fields of your campaign:

    • Provide a Name for your campaign
    • Select the Delivery time as Out of app only: this is the simple Apple push notification type that features some text.
    • In the notification text, type first the Title which will be the first line in the push.
    • Then type your Message which will be the second line
  4. Scroll down, and in the content section select Notification only

  5. You're done setting the most basic campaign. Now scroll down and click on Create button to save your push notification campaign.
  6. Finally - click on Activate to send push notification.

  7. You will be able receive the notification on your iOS device in the notification center like the following:

  8. If you have an Apple Watch paired with this iOS device then you will see the notification on your Apple Watch: