Get started with Azure Mobile Engagement for Android apps

This topic shows you how to use Azure Mobile Engagement to understand your app usage and how to send push notifications to segmented users of an Android application. This tutorial demonstrates the simple broadcast scenario using Mobile Engagement. In it, you create a blank Android app that collects basic data and receives push notifications using Google Cloud Messaging (GCM).


Completing this tutorial requires the Android Developer Tools, which includes the Android Studio integrated development environment, and the latest Android platform.

It also requires the Mobile Engagement Android SDK.


To complete this tutorial, you need 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 Android 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. You create a basic app with Android Studio to demonstrate the integration.

The complete integration documentation can be found in the Mobile Engagement Android SDK integration.

Create an Android project

  1. Start Android Studio, and in the pop-up, select Start a new Android Studio project.

  2. Provide an app name and company domain. Make a note of what you are filling, because you need it later. Click Next.

  3. Select the target form factor and API level, and click Next.


    Mobile Engagement requires API level 10 minimum (Android 2.3.3).

  4. Select Blank Activity here, which is the only screen for this app and click Next.

  5. Finally, leave the defaults as is and click Finish.

Android Studio now creates the demo app into which we integrate Mobile Engagement.

Include the SDK library in your project

  1. Download the Mobile Engagement Android SDK.
  2. Extract the archive file to a folder in your computer.
  3. Identify the .jar library for the current version of this SDK and copy it to the Clipboard.

  4. Navigate to the Project section (1) and paste the .jar in the libs folder (2).

  5. To load the library, sync the project .

Connect your app to Mobile Engagement backend with the Connection String

  1. Copy the following lines of code into the activity creation (must be done only in one place of your application, usually the main activity). For this sample app, open up the MainActivity under src -> main -> java folder and add the following:

     EngagementConfiguration engagementConfiguration = new EngagementConfiguration();
  2. Resolve the references by pressing Alt + Enter or adding the following import statements:

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

  4. Paste it into the setConnectionString parameter, replacing the entire string shown in the following code:


Add permissions and a service declaration

  1. Add these permissions to the Manifest.xml of your project immediately before or after the <application> tag:

     <uses-permission android:name="android.permission.INTERNET"/>
     <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE"/>
     <uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE"/>
     <uses-permission android:name="android.permission.RECEIVE_BOOT_COMPLETED" />
     <uses-permission android:name="android.permission.VIBRATE" />
     <uses-permission android:name="android.permission.DOWNLOAD_WITHOUT_NOTIFICATION"/>
  2. To declare the agent service, add this code between the <application> and </application> tags:

          android:label="<Your application name>"
  3. In the code you pasted, replace "<Your application name>" in the label, which is displayed in the Settings menu where you can see services running on the device. You can add the word "Service" in that label for example.

Send a screen to Mobile Engagement

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

Go to and add the following to replace the base class of MainActivity to EngagementActivity:

public class MainActivity extends EngagementActivity {


If your base class is not Activity, consult Advanced Android Reporting for how to inherit from different classes.

Comment out the following line for this simple sample scenario:

// setSupportActionBar(toolbar);

If you want to keep the ActionBar in your app, see Advanced Android Reporting.

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

During a campaign, Mobile Engagement lets you interact with and REACH your users with push notifications and in-app messaging. This module is called REACH in the Mobile Engagement portal. The following section sets up your app to receive them.

Copy SDK resources in your project

  1. Navigate back to your SDK download content and copy the res folder.

  2. Go back to Android Studio, select the main directory of your project files, and then paste it to add the resources to your project.

Create a Google Firebase project with API key


To complete this procedure, you must have a Google account that has a verified email address. To create a new Google account, go to

  1. Navigate to the Firebase Console and sign-in with your Google account credentials.
  2. Click on Create new Project button to create a new project. Alternatively, you can also click on Import Google Project to import and existing project.
  3. If you opted for creating a new project then provide a Project name and choose a Country/Region.
  4. On your project page, click the Settings cog wheel at the top left. In the menu, click on Project settings.
  5. Click on the Cloud Messaging tab at the top.
  6. Make a note of the Server Key and the Sender ID that you will use later in the Android Manifest file.

Update manifest file to enable notifications

Copy the in-app messaging resources below into your Manifest.xml between the <application> and </application> tags.

    <activity android:name="" android:theme="@android:style/Theme.Light" android:exported="false">
            <action android:name=""/>
            <category android:name="android.intent.category.DEFAULT" />
            <data android:mimeType="text/plain" />
    <activity android:name="" android:theme="@android:style/Theme.Light" android:exported="false">
            <action android:name=""/>
            <category android:name="android.intent.category.DEFAULT" />
            <data android:mimeType="text/html" />
    <activity android:name="" android:theme="@android:style/Theme.Light" android:exported="false">
            <action android:name=""/>
            <category android:name="android.intent.category.DEFAULT" />
    <activity android:name="" android:theme="@android:style/Theme.Dialog" android:exported="false">
            <action android:name=""/>
            <category android:name="android.intent.category.DEFAULT"/>
    <receiver android:name="" android:exported="false">
            <action android:name="android.intent.action.BOOT_COMPLETED"/>
            <action android:name=""/>
            <action android:name=""/>
            <action android:name=""/>
            <action android:name=""/>
            <action android:name=""/>
    <receiver android:name="">
            <action android:name="android.intent.action.DOWNLOAD_COMPLETE"/>

Specify an icon for notifications

Paste the following XML snippet in your Manifest.xml between the <application> and </application> tags.

    <meta-data android:name="engagement:reach:notification:icon" android:value="engagement_close"/>

This defines the icon that is displayed both in system and in-app notifications. It is optional for in-app notifications however mandatory for system notifications. Android will rejects system notifications with invalid icons.

Make sure you are using an icon that exists in one of the drawable folders (like engagement_close.png). mipmap folder isn't supported.


You should not use the launcher icon. It has a different resolution and is usually in the mipmap folders, which we don't support.

For real apps, you can use an icon that is suitable for notifications per Android design guidelines.


To be sure to use correct icon resolutions, you can look at these examples. Scroll down to the Notification section, click an icon, and then click PNGS to download the icon drawable set. You can see what drawable folders with which resolution to use for each version of the icon.

Enable your app to receive GCM push notifications

  1. Paste the following into your Manifest.xml between the <application> and </application> tags after replacing the Sender ID obtained from your Firebase project console. The \n is intentional so make sure that you end the project number with it.

     <meta-data android:name="engagement:gcm:sender" android:value="************\n" />
  2. Paste the code below into your Manifest.xml between the <application> and </application> tags. Replace the package name .

     <receiver android:name=""
             <action android:name="" />
     <receiver android:name="" android:permission="">
             <action android:name="" />
             <action android:name="" />
             <category android:name="<Your package name>" />
  3. Add the last set of permissions that are highlighted before the <application> tag. Replace <Your package name> by the actual package name of your application.

     <uses-permission android:name="" />
     <uses-permission android:name="<Your package name>.permission.C2D_MESSAGE" />
     <permission android:name="<Your package name>.permission.C2D_MESSAGE" android:protectionLevel="signature" />

Grant Mobile Engagement access to your GCM API Key

To allow Mobile Engagement to send push notifications on your behalf, you need to grant it access to your API Key. This is done by configuring and entering your key into the Mobile Engagement portal.

  1. From the Azure portal, ensure you're in the app we're using for this project, and then click the Engage button at the bottom:

  2. Then click the Settings -> Native Push section to enter your GCM Key:

  3. Click the Edit icon in front of API Key in the GCM Settings section as shown below:

  4. In the pop-up, paste the GCM Server Key you obtained before and then click Ok.

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. Name your campaign.

    b. Select the Delivery type as System notification -> Simple: This is the simple Android push notification type that features a title and a small line of text.

    c. Select Delivery time as Any time to allow the app to receive a notification whether the app is started or not.

    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 to send push notifications.

Next steps

Go to Android SDK to get detailed knowledge about the SDK integration.