Overview

As of April 10, 2018, Google officially deprecated the GCM push service and APIs and announced that GCM support could disappear as early as April 11, 2019. For this reason, Acoustic expects most Acoustic Mobile App Messaging users will want to migrate to FCM.

Prerequisites

An existing Acoustic Mobile App Messaging integration that uses Google Cloud Messaging (GCM) using the minimum SDK version 3.7.1.2.3.

Things to consider before migrating to Firebase Cloud Messaging (FCM)

There are some challenges when migrating from GCM to FCM. You should not create a new app key for FCM. If you create a new FCM app key, then customers with your existing GCM app will not receive messages. Acoustic recommends that you take the following actions to enable both GCM and FCM versions of your app to coexist and receive messages until Google turns off GCM permanently. You can use the same app key for GCM and FCM versions of your app. You do not need to create a new app key.

Step-by-step

1. Import your GCM project into FCM

Google has provided tools to import your GCM project into FCM. Use these tools to create an FCM project from your GCM project.

2. Change your project to use the FCM server key

Modify the GCM app key to use the server key (not legacy server key) from your Firebase console.

Note: you do not need to create a new app key. Google has maintained compatibility between GCM and FCM, so you can continue to use the same app key for both GCM and FCM after migrating it with the Google tools. Please contact support if you are unsure about migration.

3. Update your AndroidManifest.xml file for FCM support

Add the following XML to the node of your AndroidManifest.xml file for FCM support:

<!-- FCM Registration -->
<!-- FCM Messages -->
<service
     android:name="co.acoustic.mobile.push.sdk.fcm.FcmMessagingService">
     <intent-filter>
           <action android:name="com.google.firebase.MESSAGING_EVENT"/>
     </intent-filter>
</service>

4. Remove the following GCM-only code from your AndroidManifest.xml:

<!-- GcmReceiver is required for handling GCM messages. Remove for FCM messages -->
<receiver android:name="com.google.android.gms.gcm.GcmReceiver" android:priority="999"> 
<intent-filter android:permission="com.google.android.c2dm.permission.SEND" > 
<action android:name="com.google.android.c2dm.intent.RECEIVE" /> 
<category android:name="YOUR_APP_PACKAGE_NAME" />
</intent-filter> 
<intent-filter android:permission="com.google.android.c2dm.permission.SEND" android:priority="999"> 
<action android:name="com.google.android.c2dm.intent.REGISTRATION" /> 
<category android:name="YOUR_APP_PACKAGE_NAME" /> 
</intent-filter> 
</receiver>
<!-- MceGcmListenerService is required for GCM handling. Remove for FCM messages --> 
<service android:name="co.acoustic.mobile.push.sdk.gcm.MceGcmListenerService" android:exported="false" > 
<intent-filter> 
<action android:name="com.google.android.c2dm.intent.RECEIVE" /> 
</intent-filter> 
</service>

Also remove all references to C2D.

<permission android:name="YOUR_APP_PACKAGE_NAME.permission.C2D_MESSAGE" android:protectionLevel="signature" />
<uses-permission android:name="YOUR_APP_PACKAGE_NAME.permission.C2D_MESSAGE" />
<uses-permission android:name="com.google.android.c2dm.permission.RECEIVE" />

Note: If you are starting from a version of the SDK earlier than 3.7.1.0.2, you won't have GcmReceiver and MceGcmListenerService sections. Remove the <receiver GcmBroadcastReceiver and the <service GcmIntentService sections instead.

5. Build and test an FCM-enabled version of your app.

Now you're ready to build and test an FCM-enabled version of your app. Instructions for doing this can be found at Getting started with Acoustic Mobile App Messaging in Android (FCM).

After installing FCM over an existing GCM integration, you must update a few things. Be sure to come back here after adding Firebase support.

In your MceConfig.json:
Replace the senderId with an empty string

""
Change the messagingService to

"fcm"

(add a line that reads:

"messagingService":"fcm",

after the senderId line if it is not already there).

Next, add the Firebase code in Android Studio.

If adding the Firebase code didn't do it automatically, remove the GCM dependency from your app's build.gradle:

'implementation 'com.google.android.gms:play-services-gcm:11.8.0''

If you are using a class that extends MceApplication, you can add it in onCreate as below. If you are using MceApplication, you will need to create a new application class that overrides MceApplication:

import android.content.Context;

import co.acoustic.mobile.push.sdk.api.MceApplication;
import co.acoustic.mobile.push.sdk.api.MceSdkConfiguration;


public class SampleApplication extends MceApplication {

    @Override
    public void onCreate() {
        super.onCreate();
	 
    }
}

If you are using your own application class (not as common), call it after you call onCreate():

@Override public void onCreate() {
        super.onCreate(); 
        MceAplication.init(this, ...);
    }

This will ensure that upgraded devices know to use FCM.

Finally, delete google_app_id from your strings file (mce_sample_strings.xml in the sample app) if it exists; it is added to values/values.xml by FCM.

When testing, ensure that you test both the new install case and the migration from the GCM case. The invalidateExistingUser option in MceConfig.json might help with testing. For information about this option, see Assign new MUIDs to devices when reinstalling apps

6. Release an FCM-enabled version of your app.

As your users upgrade, they will migrate from using the GCM app key to the FCM app key.

If you use multiple senders, you can use the co.acoustic.mobile.push.sdk.api.fcm.FcmApi (and in particular, isFcmMessage and handleMceFcmMessage) as described in Getting started with Mobile App Messaging in Android Apps that use Firebase Cloud Messaging (FCM) .