Skip to end of metadata
Go to start of metadata

Android SDK Integration Guide - Mobile Engagement

This guide is a quick start to adding the Phunware Mobile Engagement SDK to an Android app to power Phunware's Marketing Automation module which allows you to create and send broadcast, geofence, and beacon campaigns to your mobile app users.

Android Studio is the recommended development environment for building an app with the Phunware Mobile Engagement SDK.


Step 1: Add the Phunware Maven remote repository

Insert this block into allprojects -> repositories:

allprojects {
    repositories {
        maven {
           	url ""


Step 2: Add the Mobile Engagement SDK as a dependency in your app's build.gradle file

This will automatically import the required dependency for Phunware Core

apply plugin: ''

android {

dependencies {
    compile 'com.phunware.engagement:mobile-engagement:3.1.2'


Step 3: (Optional) Add beacon support if you are using beacons

If you would like to take advantage of the Mobile Engagement SDK's beacon support, simply add the beacon-location-manager dependency.

With properly configured beacons in your environments, no other code changes are required to take advantage of beacon-based messaging.

dependencies {
  compile 'com.phunware.engagement:mobile-engagement:3.1.2'
  compile 'com.phunware.engagement:beacon-location-manager:3.1.2' {
		exclude group: 'com.phunware.engagement', module: 'mobile-engagement'


Step 4: Retrieve App ID, Access Key and Signature Key from MaaS Portal

Navigate to Phunware's MaaS portal to find your App ID, Access Key and Signature key. 

GCM setup (deprecated, see FCM): 

FCM setup:

Part of the GCM setup is managed through the Mobile Engagement SDK including:

  • Add the play-services-gcm to your application gradle
  • changes required to the AndroidManifest 


Step 5: Add Phunware key resources to strings.xml for App Id, Access Key, Signature Key

Add the keys obtained in step 4 to strings.xml

<string name="app_id">APPID</string>
<string name="access_key">ACCESSKEY</string>
<string name="sig_key">SIGKEY</string>


Step 6: Add Phunware keys for App Id, Access Key, and Signature Key to Manifest

Add the keys obtained in step 4 to Manifest.

<meta-data android:name="com.phunware.APPLICATION_ID" android:value="@string/app_id" />
<meta-data android:name="com.phunware.ACCESS_KEY" android:value="@string/access_key" />
<meta-data android:name="com.phunware.SIGNATURE_KEY" android:value="@string/signature_key" />


Step 7: Add Location and Storage permissions to Manifest

This allows you to utilize location-based messages and beacon messaging.

NOTE: Background location notifications currently cannot work with runtime permissions required for apps targeting Android SDK level 23 and higher, so your targetSdkVersion in your build.gradle file must be 22 or lower.
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION"/>


Step 8: Configure the Mobile Engagement SDK with your environment.

You should only initialize the Mobile Engagement SDK once, after you initialize PwCoreSession.  Once it's complete, you can access the Location, Message and Attribute managers directly.

Once initialization is complete, users will be automatically notified with your custom broadcast messages.  If you have location and storage permissions they will also be able to receive messages for location events, like entering a retail store.

public class MyApplication extends Application {

  public void onCreate() {
	//initialize PwCoreSession
	//initialize Engagement
    new Engagement.Builder(this)
			.appId(/*your app ID from the MaaS portal, as a long*/)
	//start location manager to receive location based events



Step 9: Designate an Activity to launch from notifications

Notifications can be customized by extending the NotificationCustomizationService. The intent which launches your activity from a notification will have extras with message and promo information.

    android:name=".MessageActivity" >
        <action android:name="android.intent.action.VIEW" />
        <category android:name="android.intent.category.DEFAULT" />
        <data android:mimeType="engagement/message" />


if (getIntent().getAction() == Intent.ACTION_VIEW) {

    Message intentMessage = getIntent().getParcelableExtra(MessageManager.EXTRA_MESSAGE);,

    boolean hasPromo = getIntent()
            .getBooleanExtra(MessageManager.EXTRA_HAS_EXTRAS, false);
    if (hasPromo) {
        long messageId = intentMessage.campaignId();
		Engagement.messageManager().getMessage(messageId, new Callback<Message>() {
    		public void onSuccess(Message data) {
      		  //do something with the message

    		public void onFailed(Throwable e) {
        		Log.e(TAG, "Failed to get message for id: " + messageId, e);


Step 10: Show Messages

Using the MessageManager you can easily show a list of available messages.  

NOTE: Calls to the MessageManager are asynchronous, and may require loading data from the network.
public class MessageListFragment extends Fragment {
  public void onActivityCreated(@Nullable Bundle savedInstanceState) {

    Engagement.messageManager().getMessages(new Callback<List<Message>>() {
      public void onSuccess(List<Message> data) {
        //do something with the Messages

      public void onFailed(Throwable e) {



Step 11: Customizing Notifications

This service allows app developers to customize notifications. It must be implemented initially even if the user would like to just use standard out of the box notifications

 <manifest ...>
    <service android:name=".MyNotificationEditService" android:exported="false">
        <action android:name="com.phunware.engagement.EDIT_NOTIFICATION" />
public class MyNotificationEditService extends NotificationCustomizationService {
  @Override public void editNotification(Notification.Compat.Builder notificationBuilder) {

Step 12: Enabling Push Notifications


New in Version 3.1.2 is the ability to use the SDK with or without push notifications as a feature. Enabling push notifications is as easy as enabling them through a simple call to the Engagement API

  • No labels