Documentation
Help CenterCommunityDevelopersAcademyStatus

Add the Campaign SDK to your Android app

Suggest Edits

The Campaign SDK for Android lets you deliver personalized, interactive push notifications and messages to your Android app.

Requirements

Mobile app compatibility

  • Supported versions: Android 5.0 (API level 21) or later
  • Latest tested version: Android 14 (API level 34)

Development environment

  • Android Studio
  • Firebase libraries: com.google.firebase:firebase-core version 19.0.2 and com.google.firebase:firebase-messaging version 22.0.0
  • Google Mobile Services libraries: com.google.android.gms:play-services-base version 18.3.0

If you are going to use location-based messages, two additional GMS libraries are required. In that case, however, your mobile app will need to ask for an additional user permission - see Device Location Awareness (DLA) for instructions.

  • com.google.android.gms:play-services-location version 21.0.1
  • com.google.android.gms:play-services-maps version 17.0.1

For example, see configuration files from our demo app:

Before you begin

Before you begin, make sure the following conditions are met.

Acoustic Campaign

  • Your company has an active Acoustic Campaign subscription.
  • You have a developer account for Acoustic Campaign.
  • Your mobile app has been added to Acoustic Campaign. For instructions, see Add and configure mobile developer apps.
  • In Acoustic Campaign, mobile push notifications are enabled for your mobile app. For more information, see Get started with mobile campaign.

Your Android app

  • Your mobile app is registered and implemented (this is necessary for testing and creating notifications).
  • In your mobile app, Firebase Cloud Messaging is enabled. Go to the Firebase Console and download the Firebase Android configuration file (google-services.json). Add the file to your project folder: android/app/.

🚧

Attention

The legacy Google API key authentication will be deprecated on June 20th, 2024. If the push service type in your mobile app is set to "FCM", you must update to the latest Firebase Cloud Messaging API (v1).

  • The install location of your app is set to the internal memory of a mobile device, not to external storage cards.

Initial setup

There are two ways to add Campaign SDK to your Gradle project:

  • With the help of a dependency manager (Maven Central) - recommended
  • Manually by copying our AAR file

Always use the latest release of Campaign SDK for Android.

Here is how to add Campaign SDK to your Android app using Maven Central.

  1. In your project-level build.gradle file, add mavenCentral() as a new repository for global use in the project. 
repositories {
      google()
      mavenCentral()
      maven {
          url "https://plugins.gradle.org/m2/"
      }
      maven {
          url "https://maven.google.com"
          name 'Google'
      }
      // Use line below for latest beta version or remove to use production version
      maven { url "https://s01.oss.sonatype.org/content/repositories/staging" }
  }
  1. In the app-level build.gradle file, edit the Dependencies section to support Maven, Google Play Services and Firebase. Note that the plus sign in our example stands for the latest version of the SDK. You can enter a version number instead.
// Required base libraries
implementation "io.github.go-acoustic:acoustic-mobile-push-android-sdk:+"
implementation "io.github.go-acoustic:acoustic-mobile-push-android-inapp:+"
implementation "io.github.go-acoustic:acoustic-mobile-push-android-inbox:+"

// Use the following for the plugins needed
implementation "io.github.go-acoustic:acoustic-mobile-push-android-calendar:+"
implementation "io.github.go-acoustic:acoustic-mobile-push-android-carousel:+"
implementation "io.github.go-acoustic:acoustic-mobile-push-android-displayweb:+"
implementation "io.github.go-acoustic:acoustic-mobile-push-android-snooze:+"

/* If you are going to support location services, add this. */
implementation "com.google.android.gms:play-services-location:21.0.1"

/* To use our inbox plugin, you need Appcompat 1.6.0 or later: */
implementation "androidx.appcompat:appcompat:1.6.0"

/* Required for SDK encrypted preferences read/write */
implementation "androidx.security:security-crypto:1.1.0-alpha06"
  1. Build your project.

The manual steps are as follows:

  1. Create the libs/ directory next to your src/ directory if it is not there yet.
  2. Copy the Campaign SDK AAR file to the libs/ directory.
  3. In the app-level build.gradle file, edit the Dependencies section to support Google Play Services, crypto, and Firebase.
implementation fileTree(dir: 'libs', include: ['*.jar'])
implementation fileTree(dir: 'libs', include: ['*.aar'])
implementation 'com.google.android.gms:play-services-base:18.3.0'
implementation 'com.google.firebase:firebase-messaging:22.0.0'
implementation 'androidx.security:security-crypto:1.1.0-alpha06'

/* If you are going to support location services, add this. */
implementation 'com.google.android.gms:play-services-location:21.0.1'

Here is a sample build.gradle from our demo app.

Updating the SDK configuration

Replacing the default application class

By default, the application class in Campaign SDK is set to co.acoustic.mobile.push.sdk.api.MceApplication. If you want to replace it, set android:name in the AndroidManifest.xml file and set android:name to tools:replace.

<application
        tools:replace="android:name"
        android:name=".MyCoolApplication">

If you implement your own application class, replace YOUR_APP_PACKAGE_NAME with the name of your package.

You can use the following as a template for your application class. 

package YOUR_APP_PACKAGE_NAME;
import android.annotation.TargetApi;
import android.app.NotificationChannel;
import android.app.NotificationManager;
import android.content.Context;
import android.os.Build;
import co.acoustic.mobile.push.sdk.api.MceApplication;
import co.acoustic.mobile.push.sdk.api.MceSdk;
import co.acoustic.mobile.push.sdk.api.notification.NotificationsPreference;
public class MyApplication extends MceApplication {
  public void onCreate() {
    super.onCreate();
    if (Build.VERSION.SDK_INT & gt; = Build.VERSION_CODES.O) {
      createNotificationChannel(getApplicationContext());
    }
  }
  @
  TargetApi(26) private static void createNotificationChannel(Context context) {
    String MY_SAMPLE_NOTIFICATION_CHANNEL_ID = context.getString(R.string.notif_channel_id);
    NotificationManager notificationManager = (NotificationManager) context.getSystemService(Context.NOTIFICATION_SERVICE);
    NotificationChannel channel = notificationManager.getNotificationChannel(MY_SAMPLE_NOTIFICATION_CHANNEL_ID);
    if (channel == null) {
      CharSequence name = context.getString(R.string.notif_channel_name);
      String description = context.getString(R.string.notif_channel_description);
      int importance = NotificationManager.IMPORTANCE_HIGH;
      channel = new NotificationChannel(MY_SAMPLE_NOTIFICATION_CHANNEL_ID, name, importance);
      channel.setDescription(description);
      NotificationsPreference notificationsPreference = MceSdk.getNotificationsClient().getNotificationsPreference();
      notificationsPreference.setNotificationChannelId(context, MY_SAMPLE_NOTIFICATION_CHANNEL_ID);
      notificationManager.createNotificationChannel(channel);
    }
  }
}

package YOUR_APP_PACKAGE_NAME

import android.app.NotificationChannel
import android.app.NotificationManager
import android.content.Context
import android.os.Build
import androidx.annotation.RequiresApi
import co.acoustic.mobile.push.sdk.api.MceApplication
import co.acoustic.mobile.push.sdk.api.MceSdk
import co.acoustic.mobile.push.sdk.api.notification.NotificationsPreference

class MyCoolApplication : MceApplication() {
    override fun onCreate() {
        super.onCreate()
        if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.O) {
            createNotificationChannel(applicationContext)
        }
    }

    companion object {
        @RequiresApi(Build.VERSION_CODES.O)
        private fun createNotificationChannel(context: Context) {
            val channelId = context.getString(R.string.notif_channel_id)
            val notificationManager =
                context.getSystemService(Context.NOTIFICATION_SERVICE) as NotificationManager
            val existingChannel = notificationManager.getNotificationChannel(channelId)

            if (existingChannel == null) {
                val name = context.getString(R.string.notif_channel_name)
                val description = context.getString(R.string.notif_channel_description)
                val importance = NotificationManager.IMPORTANCE_HIGH

                val channel =
                    NotificationChannel(channelId, name, importance).apply {
                        this.description = description
                    }

                val notificationsPreference: NotificationsPreference =
                    MceSdk.getNotificationsClient().notificationsPreference
                notificationsPreference.setNotificationChannelId(context, channelId)

                notificationManager.createNotificationChannel(channel)
            }
        }
    }
}

The application class refers to the following strings that you will need to add to strings.xml.

<string name="notif_channel_id">my-notification-channel</string>
<string name="notif_channel_name">My sample notification channel</string>
<string name="notif_channel_description">My sample notification channel description</string>

Setting a default notification channel

You must set a default notification channel. Add the following to the <application> node in AndroidManifest.xml:

<meta-data android:name="com.google.firebase.messaging.default_notification_channel_id" android:value="@string/notif_channel_id" />

If you intend to send push notifications of the DIAL or URL type, add the following to AndroidManifest.xml at the same level as the node:

<queries>
	<!-- Required for handling notifications that open the devices dialer app -->
	<intent>
		<action android:name="android.intent.action.DIAL" />
	</intent>
	<!-- Required for handling notifications that open URLs -->
	<intent>
		<action android:name="android.intent.action.VIEW"/>
		<data android:scheme="https"/>
	</intent>
</queries>

You can selectively remove any of these nodes. If you remove a node and then send a push notification using the removed support, the push notification will only open the app. It will not invoke the expected action. This requirement was introduced in Android 12 (API level 31).

Customizing backup preferences

To prevent unexpected behaviour, we recommend excluding Campaign SDK files from your app backup. For more information, see Disable or modify automated backups for your Android app.

Enabling database encryption

You can encrypt the Campaign SDK database. For more information, see Android SDK database encryption.

Setting Campaign SDK properties

You can set Campaign SDK properties using either of the following:

  • The MceConfig.json properties file. The most common way is to copy MceConfig.json from one of our sample apps into your app/src/main/assets directory. We also provide an API option. For details, see Configuration (MceConfig.json).
  • The MceSdkConfiguration object. You must ensure that the application class is not MceApplication and that you call the MceApplication init method with the MceSdkConfiguration object. If you do not set a config property, a default value is used. For more information, see Modify the SDK initialization control for alternate Android integration.

Here is an example of theMceSdkConfiguration object:

package YOUR_APP_PACKAGE_NAME;
import android.annotation.TargetApi;
import android.app.NotificationChannel;
import android.app.NotificationManager;
import android.content.Context;
import android.os.Build;
import co.acoustic.mobile.push.sdk.api.MceApplication;
import co.acoustic.mobile.push.sdk.api.MceSdk;
import co.acoustic.mobile.push.sdk.api.notification.NotificationsPreference;
public class MyApplication extends MceApplication {
  public void onCreate() {
    super.onCreate();
    if (Build.VERSION.SDK_INT & gt; = Build.VERSION_CODES.O) {
      createNotificationChannel(getApplicationContext());
    }
  }
  @
  TargetApi(26) private static void createNotificationChannel(Context context) {
    String MY_SAMPLE_NOTIFICATION_CHANNEL_ID = context.getString(R.string.notif_channel_id);
    NotificationManager notificationManager = (NotificationManager) context.getSystemService(Context.NOTIFICATION_SERVICE);
    NotificationChannel channel = notificationManager.getNotificationChannel(MY_SAMPLE_NOTIFICATION_CHANNEL_ID);
    if (channel == null) {
      CharSequence name = context.getString(R.string.notif_channel_name);
      String description = context.getString(R.string.notif_channel_description);
      int importance = NotificationManager.IMPORTANCE_HIGH;
      channel = new NotificationChannel(MY_SAMPLE_NOTIFICATION_CHANNEL_ID, name, importance);
      channel.setDescription(description);
      NotificationsPreference notificationsPreference = MceSdk.getNotificationsClient().getNotificationsPreference();
      notificationsPreference.setNotificationChannelId(context, MY_SAMPLE_NOTIFICATION_CHANNEL_ID);
      notificationManager.createNotificationChannel(channel);
    }
  }
}

Additional options

Monitoring events

Implement MceBroadcastReceiver if you want to monitor events in Campaign SDK, such as SDK registration, FCM registration, and notification received. Create a new MceBroadcastReceiver implementation class. The following example shows how to create a new MceBroadcastReceiver implementation class with FCM.

package YOUR_APP_PACKAGE;
import android.content.Context;
import java.util.Date;
import android.content.Intent;
import android.location.Location;
import android.os.Bundle;
import android.util.Log;
import co.acoustic.mobile.push.sdk.api.MceBroadcastReceiver;
import co.acoustic.mobile.push.sdk.api.attribute.AttributesOperation;
import co.acoustic.mobile.push.sdk.api.event.Event;
import co.acoustic.mobile.push.sdk.api.notification.NotificationDetails;
import co.acoustic.mobile.push.sdk.location.MceLocation;
import co.acoustic.mobile.push.sdk.api.broadcast.EventBroadcastUtil;
import java.util.List;
public class MyMceBroadcastReceiver extends MceBroadcastReceiver {
  @Override
  public void onSdkRegistered(Context context) {
    // Handle the SDK registration event
    // context - The application context
  }
  @Override
  public void onMessagingServiceRegistered(Context context) {
    // Handle the FCM registration event
    // context - The application context
  }
  @Override
  public void onSdkRegistrationChanged(Context context) {
    // context - The application context
  }
  @Override
  public void onSdkRegistrationUpdated(Context context) {
    // context - The application context
  }
  @Override public void onMessage(Context context, NotificationDetails notificationDetails, Bundle extraPayload) {
    // Handle the notification received event
    // context - The application context
    // notificationDetails - The received notification
    // extraPayload- Additional payload that arrived with the notification
  }
  @Override
  public void onSessionStart(Context context, Date sessionStartDate) {
    // context - The application context
    // sessionStartDate- The new session start time
  }
  @Override
  public void onSessionEnd(Context context, Date sessionEndDate, long sessionDurationInMinutes) {
    // context - The application context
    // sessionEndDate- The session end time
    // sessionDurationInMinutes - The session duration in minutes 
  }
  @Override
  public void onNotificationAction(Context context, Date actionTime, String pushType, String actionType, String actionValue) {
    // context - The application context 
    // actionTime- The time the action was clicked on
    // pushType - always "simple"
    // actionType - The type of the action
    // actionValue - the value of the "value" key in the payload.
  }
  @Override
  public void onAttributesOperation(Context context, AttributesOperation attributesOperation) {
    // context - The application context
    // attributesOperation - The operation that was executed
  }
  @Override
  public void onEventsSend(Context context, List < Event > list) {
    // context - The application context
    // events- The events that were sent 
  }
  @Override
  public void onIllegalNotification(Context context, Intent intent) {
    // context - The application context
    // intent- The intent that contains the illegal notification
  }
  @Override
  public void onNonMceBroadcast(Context context, Intent intent) {
    // context - The application context
    // intent- The intent that contains the non MCE broadcast
  }
  /**
   * This method is called when a location event occurs
   * @param location The related location
   * @param locationType The related location type
   * @param locationEventType The related location event type
   */
  public void onLocationEvent(Context context, MceLocation location, LocationType locationType, LocationEventType locationEventType) {
    // do something interesting with the location event
  };
  /**
   * This method is called when the device location is updated
   * @param context The application's context
   * @param location The device location
   */
  public void onLocationUpdate(Context context, Location location) {
    // do something interesting with the location update
  }
  @Override
  public void onReceive(Context context, Intent intent) {
    Log.i(getClass().getSimpleName(), "Received intent: " + intent.toString());
    if (intent == null || intent.getAction() == null) {
      return;
    }
    try {
      EventBroadcastUtil.handleBroadcast(context, intent, this);
    } catch (Throwable t) {
      Log.e(getClass().getSimpleName(), "Unexpected error on receive: ", t);
    }
  }
  @Override
  public void onC2dmError(Context context, String errorId) {
    Log.i(getClass().getSimpleName(), "C2DM errorId: " + errorId);
  }
}

import android.content.Context
import android.content.Intent
import android.location.Location
import android.os.Bundle
import android.util.Log
import co.acoustic.mobile.push.sdk.api.MceBroadcastReceiver
import co.acoustic.mobile.push.sdk.api.attribute.AttributesOperation
import co.acoustic.mobile.push.sdk.api.broadcast.EventBroadcastHandler.LocationEventType
import co.acoustic.mobile.push.sdk.api.broadcast.EventBroadcastHandler.LocationType
import co.acoustic.mobile.push.sdk.api.broadcast.EventBroadcastUtil
import co.acoustic.mobile.push.sdk.api.event.Event
import co.acoustic.mobile.push.sdk.api.notification.NotificationDetails
import co.acoustic.mobile.push.sdk.location.MceLocation
import java.util.Date

class MyMceBroadcastReceiver : MceBroadcastReceiver() {
    override fun onSdkRegistered(context: Context) {
        // Handle the SDK registration event
        // context - The application context
    }

    override fun onMessagingServiceRegistered(context: Context) {
        // Handle the FCM registration event
        // context - The application context
    }

    override fun onSdkRegistrationChanged(context: Context) {
        // context - The application context
    }

    override fun onSdkRegistrationUpdated(context: Context) {
        // context - The application context
    }

    override fun onMessage(
        context: Context,
        notificationDetails: NotificationDetails,
        extraPayload: Bundle
    ) {
        // Handle the notification received event
        // context - The application context
        // notificationDetails - The received notification
        // extraPayload- Additional payload that arrived with the notification
    }

    override fun onSessionStart(context: Context, sessionStartDate: Date) {
        // context - The application context
        // sessionStartDate- The new session start time
    }

    override fun onSessionEnd(
        context: Context,
        sessionEndDate: Date,
        sessionDurationInMinutes: Long
    ) {
        // context - The application context
        // sessionEndDate- The session end time
        // sessionDurationInMinutes - The session duration in minutes
    }

    override fun onNotificationAction(
        context: Context,
        actionTime: Date,
        pushType: String,
        actionType: String,
        actionValue: String
    ) {
        // context - The application context
        // actionTime- The time the action was clicked on
        // pushType - always "simple"
        // actionType - The type of the action
        // actionValue - the value of the "value" key in the payload.
    }

    override fun onAttributesOperation(context: Context, attributesOperation: AttributesOperation) {
        // context - The application context
        // attributesOperation - The operation that was executed
    }

    override fun onEventsSend(context: Context, list: List<Event>) {
        // context - The application context
        // events- The events that were sent
    }

    override fun onIllegalNotification(context: Context, intent: Intent) {
        // context - The application context
        // intent- The intent that contains the illegal notification
    }

    override fun onNonMceBroadcast(context: Context, intent: Intent) {
        // context - The application context
        // intent- The intent that contains the non MCE broadcast
    }

    /**
     * This method is called when a location event occurs
     *
     * @param location The related location
     * @param locationType The related location type
     * @param locationEventType The related location event type
     */
    override fun onLocationEvent(
        context: Context,
        location: MceLocation,
        locationType: LocationType,
        locationEventType: LocationEventType
    ) {
        // do something interesting with the location event
    }

    /**
     * This method is called when the device location is updated
     *
     * @param context The application's context
     * @param location The device location
     */
    override fun onLocationUpdate(context: Context, location: Location) {
        // do something interesting with the location update
    }

    override fun onActionNotYetRegistered(p0: Context?, p1: String?) {
        TODO("Not yet implemented")
    }

    override fun onActionNotRegistered(p0: Context?, p1: String?) {
        TODO("Not yet implemented")
    }

    override fun onInboxCountUpdate(p0: Context?) {
        TODO("Not yet implemented")
    }

    override fun onReceive(context: Context, intent: Intent) {
        Log.i(javaClass.simpleName, "Received intent: $intent")
        if (intent?.action == null) {
            return
        }
        try {
            EventBroadcastUtil.handleBroadcast(context, intent, this)
        } catch (t: Throwable) {
            Log.e(javaClass.simpleName, "Unexpected error on receive: ", t)
        }
    }

    override fun onC2dmError(context: Context, errorId: String) {
        Log.i(javaClass.simpleName, "C2DM errorId: $errorId")
    }
}

After implementing MceBroadcastReceiver, add it to AndroidManifest.xml below the <application> node. 

<receiver android:name=".MyMceBroadcastReceiver">
	<intent-filter>
		<action android:name="co.acoustic.mobile.push.sdk.NOTIFIER" />
	</intent-filter>
</receiver>

Enabling multiple FCM providers

If your app must support push notifications from two sources (Acoustic Campaign and another source), then you can implement the following code to allow both of the push services to co-exist within your app.

  1. Add a class to support FCM messages. For example, create class MyFirebaseMessagingService extends FirebaseMessagingService.
  2. Add import co.acoustic.mobile.push.sdk.api.fcm.FcmApi;.
  3. Add the following code to the public void onMessageReceived(RemoteMessage remoteMessage) method.
If(FcmApi.isFcmMessage(remoteMessage)) {
  FcmApi.handleMceFcmMessage(getApplicationContext(), remoteMessage);
  return;
}
else {
  // this is not sdk message. Handle it here
}
  1. Replace FcmMessagingService in your manifest with your FCM message handler class. In this example, it’s MyFirebaseMessagingService.
<!-- FCM Messages -->
<service android: name = ".MyFirebaseMessagingService" >
  <
  !--replace android: name = "co.acoustic.mobile.push.sdk.fcm.FcmMessagingService"
With android: name = ".MyFirebaseMessagingService"
  -->
  <intent - filter >
  < action android: name = "com.google.firebase.MESSAGING_EVENT" / >
  </intent-filter> 
  </service>

When an FCM notification arrives, the following happens:

  • The OS calls MyFirebaseMessagingService::onMessageReceived().
  • The code checks if the message is from Acoustic. A message from Acoustic has "alert": in the sub-document message payload.
  • If the payload is from Acoustic, the SDK handles the message and returns it. Otherwise, the message is handled by MyFirebaseMessagingService.

For more information, see Android SDK messaging API.

Updated 3 months ago