Skill Level: Intermediate


Not what you’re looking for? Check out all our available tutorials for mobile app messaging here.


  1. Simple integration

    1. Make sure you’re using AAR format. If you aren’t, switch to that before going forward. See https://developer.ibm.com/customer-engagement/tutorials/migrating-a-project-from-jar-to-aar-in-android/ for more instructions about how to migrate your project to the newer format.
    2. Replace the library AAR files with the 3.8.0 AAR files. Typically, this requires that you drag and drop the new release of the bin/acoustic-mobile-push-android-sdk .aar in the app/libs folder in the Project Files view, and any of the stock plugins you use from plugins/acoustic-mobile-push-android .aar. Then delete ibm-mobile-push*.aar files from your libs directory. Invalidate caches and restart.
    3. Globally replace (select the app and Edit->Find->Replace in Path…) all code references and config file references that are currently com.ibm.mce.sdk with co.acoustic.mobile.push.sdk. This includes:

      ·       Package imports
      ·       API you call
      ·       Classes you inherit from
      ·       References in MceConfig.json and AndroidManifest.xml.

    4. Make sure you have upgraded to Android Studio 3.5.2 or higher.
    5. This version of the SDK now supports (and requires) AndroidX. In your app’s build.gradle, set compileSdk to at least 29 and buildToolsVersion to at least 29.0.2.
    6. In your project’s build.gradle, set the com.android.tools.build:gradle dependency to at least:
      classpath ‘com.android.tools.build:gradle:3.5.0’.
    7. Select your app and choose Refactor -> Migrate to AndroidX. Save the backup and click Do Refactor.
    8. If you implement it in your notifier class, rename onDeliveryChannelRegistered to onMessagingServiceRegistered.
    9. Update the AndroidManifest.xml for new package names. Change the name of the FcmMessagingService to co.acoustic.mobile.push.sdk.messaging.fcm.FcmMessagingService (add “messaging”). Delete the service FcmInstanceIdService, which is no longer required.
    10. Update your MceConfig.json file with any desired new options. New options include:

      ·      “messagingService”:”custom” intended for when someone else (not the Acoustic Mobile Push SDK) registers with FCM,
      ·      “inboxControl”:”” see Inbox section for more details
      ·      “location”: { “request”: { a number of options are added, and you will need to delete “providerPreferences”. See the Location section for more details.

    11. The SDK shipped with an issue when upgrading queues. Implement the code in https://developer.ibm.com/customer-engagement/2019/11/21/error-messages-when-upgrading-to-android-sdk-3-8-0/ before shipping an upgrade. New releases do not need to follow this step.
    12. The SDK as shipped emits an error message as documented in https://developer.ibm.com/customer-engagement/2019/11/21/error-messages-when-upgrading-to-android-sdk-3-8-0/. This is cosmetic and can be ignored safely.
  2. If you are using inbox messages

    No changes other than package name are required. Note that some new API has been added to allow you to have more flexibility with what’s in the inbox. See https://developer.ibm.com/customer-engagement/tutorials/inbox-control-api-additions-for-android/ for more details.

  3. If you are using in-app messages

    No changes other than package name are required.

  4. If you are using geofences/beacons

    1.  Remove providerPreferences from your MceConfig.json file. Replace it with “request”:  {. Under “request” are the following options:

        "The request key is used to configure the sdk location request properties": "",
        "request" : {
          "interval between location updates in seconds": "minimum is 1",
          "interval": 5,
          "fastest interval between location updates in seconds":  "minimum is 1",
          "fastestInterval": 1,
          "The smallest displacement in meters to generate a location request": "overrides the interval values",
          "smallestDisplacement": 100,
          "The priority of the location request": "can be either highAccuracy, balanced, lowPower or noPower",
          "priority": "highAccuracy"
    • interval is the maximum time in seconds between location updates. Setting this to a lower value will ask the OS to send more frequent updates when the app is in the foreground, at the expense of higher battery usage when the app is in the foreground.
    • fastestInterval is the minimum amount of time in seconds between two location updates.
    • smallestDisplacement overrides the “interval” and “fastestInterval” values. This tells the SDK to update its list of nearby interesting points based on how far the device has moved (in metres) since the last update. If smallestDisplacement is 100, the list of interesting points will be updated when the device has moved at least 100 metres from the previous location. This saves power if the device doesn’t move for a while, and is the recommended way to trigger location updates.

    2. Update AndroidManifest.xml for location.

    • Add <uses-permission android:name=”android.permission.ACCESS_BACKGROUND_LOCATION” />
      to AndroidManifest.xml if it’s not already there.
    • A global search and replace of com.ibm.mce.sdk with co.acoustic.mobile.push.sdk should have already renamed most of the location services.
      • Delete the service GeofenceIntentService and the receiver LocationUpdateCaller.
    • Add two new receivers:
      • <receiver android:name=”co.acoustic.mobile.push.sdk.location.LocationBroadcastReceiver” android:enabled=”true” android:exported=”true”/>
      • <receiver android:name=”co.acoustic.mobile.push.sdk.location.GeofenceBroadcastReceiver” android:enabled=”true” android:exported=”true”/>
  5. If you are using attributes

    No additional changes other than package name are required.

  6. If you are using events

    No additional changes other than package name are required.

Expected outcome

Need more help? Check out all of our available tutorials for mobile app messaging here.

Join The Discussion

Your email address will not be published. Required fields are marked *