As of April 10, 2018, Google has deprecated GCM. The GCM server and client APIs are deprecated and will be removed as soon as April 11, 2019. Migrate GCM apps to Firebase Cloud Messaging (FCM), which inherits the reliable and scalable GCM infrastructure, plus many new features. See the migration guide to learn more.

Migrate a GCM Client App for Android to Firebase Cloud Messaging

You can migrate an existing GCM client app on Android to Firebase Cloud Messaging (FCM) using the instructions in this guide. Before getting started, keep in mind:

  • GCM and FCM SDKs cannot co-exist within an application.
  • GCM tokens retrieved via GoogleCloudMessaging.register() or InstanceID.getToken() will continue to work in FCM without any modification or renewal.

To prepare for migration, you can review a video tutorial that walks through the same basic steps described in this guide. See also the GCM and FCM FAQ.

Import your GCM project as a Firebase project

The instructions in this section assume that you are adding Firebase to an existing Google Cloud project for GCM. If you already have an existing Firebase project into which you would like to migrate a GCM app and its users, see Migrate GCM to an existing Firebase project for important alternative instructions.

  1. In the Firebase console, select Add Project.

  2. Select your GCM project from the list of existing Google Cloud projects, and select Add Firebase.

  3. In the Firebase welcome screen, select Add Firebase to your Android App.

  4. Provide your package name and SHA-1, and select Add App. A new google-services.json file for your Firebase app is downloaded.

  5. Select Continue and follow the detailed instructions for adding the Google Services plugin in Android Studio.

Switch to FCM in the app-level build.gradle

Before

dependencies {
  compile "com.google.android.gms:play-services-gcm:15.0.1"
}

After

dependencies {
  compile "com.google.firebase:firebase-messaging:17.3.0"
}

Edit your app's manifest

The FCM SDK automatically adds all required permissions as well as the required receiver funtionality. Make sure to remove the following obsolete (and potentially harmful, as they may cause message duplication) elements from your app's manifest:

Remove from AndroidManifest.xml

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

...

<receiver
    android:name="com.google.android.gms.gcm.GcmReceiver"
    android:exported="true"
    android:permission="com.google.android.c2dm.permission.SEND" >
    <intent-filter>
        <action android:name="com.google.android.c2dm.intent.RECEIVE" />
        <category android:name="com.example.gcm" />
    </intent-filter>
</receiver>

Update server endpoints

Update your server code to use new FCM endpoints for sending messages via HTTP and XMPP. Note that the new FCM version of gcm-http.googleapis.com/gcm/ is fcm.googleapis.com/fcm/ (without "http"):

GCM endpoint FCM endpoint
gcm-http.googleapis.com/gcm/ fcm.googleapis.com/fcm/
gcm-xmpp.googleapis.com fcm-xmpp.googleapis.com

FCM supports HTTP and XMPP protocols that are virtually identical to the GCM server protocols, so you don't need to update your sending logic for the migration. Optionally, you may want to evaluate the FCM HTTP v1 API, which offers an improved security model and new capabilities for customizing messages across platforms.

Next steps and optional migration tasks

Depending on which GCM features your app uses, you may have additional migration tasks to perform. Most apps are likely to need to migrate an InstanceIDListenerService to work with FCM.

Usually required: migrate your InstanceIDListenerService

Perform this step if you need to access the device registration token because:

  • You send messages to specific devices
  • You send messages to device groups
  • You subscribe devices to topics with the subscription management API.

Optional: migrate your GcmListenerService

Perform this step if you need to handle incoming messages, such as when:

  • Your app receives data-only messages
  • your app receives notification payloads while the application is in foreground
  • Your app receives errors in case of upstream message failures.

Optional: update your usage of GcmPubSub

Perform this step if:

  • If you need to subscribe new devices to topics. Devices already subscribed to a topic prior to migration will continue to receive messages. For example, a device subscribed to /topics/news in GCM will continue to receive messages sent to /news after migration to FCM (note that the prefix "topics" is not required in FCM).

Special case: Migrate GCM to an existing Firebase project

Perform this step if:

  • You already have an existing Firebase project into which you would like to migrate a GCM app and its users. This situation requires additional tasks.

Send feedback about...

Cloud Messaging
Cloud Messaging