Get Started with Azure Mobile Engagement for iOS apps in Objective C

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:

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 the 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 then select Add files to.

  4. Navigate to the folder where you extracted the SDK, select the EngagementSDK folder, click Options on the bottom left corner and make sure that the checkbox Copy items if needed and the checkbox for your target are checked then press OK.

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

  6. Go back to the Azure portal in your app's Connection Info page and copy the connection string.

  7. Add the following line of code in your AppDelegate.m file.

    #import "EngagementAgent.h"
  8. Now paste the connection string in the didFinishLaunchingWithOptions delegate.

    - (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions
            [EngagementAgent init:@"Endpoint={YOUR_APP_COLLECTION.DOMAIN};SdkKey={YOUR_SDK_KEY};AppId={YOUR_APPID}"];
  9. setTestLogEnabled is an optional statement which enables SDK logs for you to identify issues.

Enable 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.h file and import EngagementViewController.h:

    #import "EngagementViewController.h"
  2. Now replace the super class of the ViewController interface by EngagementViewController:

    @interface 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.

Enable push notifications and in-app messaging

Mobile Engagement allows you to interact with your users and REACH 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 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.

Modify your Application Delegate

  1. Back in AppDeletegate.m file, import the Engagement Reach module.

    #import "AEReachModule.h"
    #import <UserNotifications/UserNotifications.h>
  2. Inside the application:didFinishLaunchingWithOptions method, create a Reach module and pass it to your existing Engagement initialization line:

    - (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
        AEReachModule * reach = [AEReachModule moduleWithNotificationIcon:[UIImage imageNamed:@"icon.png"]];
        [EngagementAgent init:@"Endpoint={YOUR_APP_COLLECTION.DOMAIN};SdkKey={YOUR_SDK_KEY};AppId={YOUR_APPID}" modules:reach, nil];
        return YES;

Enable your app to receive APNS Push Notifications

  1. Add the following line to the application:didFinishLaunchingWithOptions method:

    if (NSFoundationVersionNumber >= NSFoundationVersionNumber_iOS_8_0)
        if (NSFoundationVersionNumber > NSFoundationVersionNumber_iOS_9_x_Max)
            [UNUserNotificationCenter.currentNotificationCenter requestAuthorizationWithOptions:(UNAuthorizationOptionBadge | UNAuthorizationOptionSound | UNAuthorizationOptionAlert) completionHandler:^(BOOL granted, NSError * _Nullable error) {}];
            [application registerUserNotificationSettings:[UIUserNotificationSettings settingsForTypes:(UIUserNotificationTypeBadge | UIUserNotificationTypeSound | UIUserNotificationTypeAlert)   categories:nil]];
        [application registerForRemoteNotifications];
        [application registerForRemoteNotificationTypes:(UIRemoteNotificationTypeBadge | UIRemoteNotificationTypeSound | UIRemoteNotificationTypeAlert)];
  2. Add the application:didRegisterForRemoteNotificationsWithDeviceToken method as follows:

    - (void)application:(UIApplication *)application didRegisterForRemoteNotificationsWithDeviceToken:(NSData *)deviceToken
            [[EngagementAgent shared] registerDeviceToken:deviceToken];
        NSLog(@"Registered Token: %@", deviceToken);
  3. Add the didFailToRegisterForRemoteNotificationsWithError method as follows:

    - (void)application:(UIApplication*)application didFailToRegisterForRemoteNotificationsWithError:(NSError*)error
        NSLog(@"Failed to get token, error: %@", error);
  4. Add the didReceiveRemoteNotification:fetchCompletionHandler method as follows:

    - (void)application:(UIApplication *)application didReceiveRemoteNotification:(NSDictionary *)userInfo fetchCompletionHandler:(void (^)(UIBackgroundFetchResult result))handler
        [[EngagementAgent shared] applicationDidReceiveRemoteNotification:userInfo fetchCompletionHandler:handler];

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: