Google push channel integration
Learn how to integrate the Google push channel.
This topic applies to Android SDK 3.x and 4.x. The vendor platform setup and console configuration are the same for both versions. However, you must select the SDK dependency version, logging method, and notification tap handling based on your specific SDK version. For details about migration differences for 4.x, see Android SDK 4.x upgrade guide.
Prerequisites
-
You have integrated the Mobile Push SDK by following the documentation for your version: Android SDK integration (3.x) or Android SDK integration (4.x).
-
You have created a project in Firebase. If not, sign in to Firebase to create one. After creating the project, add an app to it and download the
google-services.jsonfile. From this file, record the values of the following keys:project_number,mobilesdk_app_id,project_id, andcurrent_key. These values correspond tosendId,applicationId,projectId, andapiKey, respectively.
-
In the Firebase console, navigate to Project settings > Service accounts. Generate a new private key, download the file, and store it securely.

-
You have uploaded the FCM service account key JSON file to the EMAS console. If you have not done this, log on to the EMAS Mobile Push console and upload the file you downloaded from Firebase. For instructions, see Configure keys for vendor channels.
Step 1: Add the SDK
1.1 Configure Maven repository
The following sections describe the recommended configuration methods: the dependencyResolutionManagement block for Gradle 7.0 and later, and the allprojects block for earlier versions.
1.1.1 Use dependencyResolutionManagement
In your root-level (project-level) Gradle file (<project>/settings.gradle), add the Maven repository URL to the repositories block inside dependencyResolutionManagement.
dependencyResolutionManagement {
repositories {
google()
}
}
1.1.2 Use allprojects
In your root-level (project-level) Gradle file (<project>/build.gradle), add the Maven repository URL to the repositories block inside allprojects.
allprojects {
repositories {
google()
}
}
1.2 Add SDK dependencies
In your module-level (app-level) Gradle file (usually <project>/<app-module>/build.gradle), add the SDK dependencies to the dependencies block.
-
See the Android SDK release notes to use the correct SDK version.
In the following example, replace x.x.x with the version numbers for the vendor push SDKs that correspond to your main SDK version, as specified in the release notes.
dependencies {
implementation 'com.aliyun.ams:alicloud-android-third-push:x.x.x'
implementation 'com.aliyun.ams:alicloud-android-third-push-fcm:x.x.x'
}
The Mobile Push SDK for vendor channels only supports Maven dependencies.
Step 2: Configure the SDK
2.1 Initialize SDK
-
Before you integrate with FCM, ensure that Google Play services is installed and running correctly on the device.
-
In your
Applicationclass, initialize the vendor channel SDK after initializing the Mobile Push SDK. -
If you are upgrading from a Mobile Push SDK version earlier than 3.7.7, you must update the
sendId,applicationId,projectId, andapiKeyparameters in your code. For these values, see Prerequisites.
Initialize the SDK as follows:
// Register the GCM/FCM vendor channel.
// See the Prerequisites section for sendId, applicationId, projectId, and apiKey.
GcmRegister.register(applicationContext, sendId, applicationId, projectId, apiKey); // Register the GCM/FCM vendor channel.
// See the Prerequisites section for sendId, applicationId, projectId, and apiKey.
GcmRegister.register(applicationContext, sendId, applicationId, projectId, apiKey);The registration method does not automatically check if the device supports Google push notifications. You must perform this check yourself or call this method only after attempts to initialize other vendor channels fail.
2.2 Configure obfuscation
If your project uses code obfuscation, add the following ProGuard rules for the vendor channel.
# GCM/FCM channel
-keep class com.google.firebase.**{*;}
-dontwarn com.google.firebase.**
Step 3: Verify integration
3.1 Enable SDK logging (3.x/4.x)
In your debug build, first call PushServiceFactory.init, then add the following logging configuration. Place this configuration before the Mobile Push register call and the vendor channel registration. To troubleshoot underlying connection issues in 4.x, set the log level before starting the registration.
CloudPushService pushService = PushServiceFactory.getCloudPushService();
// This line is for debug builds only and not needed for release builds.
pushService.setLogLevel(CloudPushService.LOG_DEBUG); val pushService = PushServiceFactory.getCloudPushService()
// This line is for debug builds only and not needed for release builds.
pushService.setLogLevel(CloudPushService.LOG_DEBUG)
The setDebug(true) method enables the access component and parameter checks, but does not enable DEBUG logs. To view detailed logs, explicitly call setLogLevel(CloudPushService.LOG_DEBUG).
3.2 Check registration result
SDK 4.x
The following log keywords are based on SDK 4.0.0. In Logcat, filter by the TAG EMAS_PUSH, then locate logs by searching for the module name and keywords in the log body. The module name in square brackets is part of the log body, not a separate TAG.
In the log body, search for [GcmRegister] fcm token is and confirm that the token is not empty. If you see Fetching FCM registration token failed, check the exception details to troubleshoot the issue.
Search for [AgooFirebaseMessagingService] onMessageReceived payload msg: to find logs for received data messages. Verify notification display and taps by checking the device UI and your business callbacks.
After you obtain a valid vendor token, verify that it is reported to EMAS. Then, send a test notification from the console or by using an OpenAPI operation to check its display and tap handling.
Mobile Push SDK logs use the EMAS_PUSH TAG. For logs from the native vendor SDK, the Android system, or your app, check their respective TAGs.
For more information about log configuration, see Android SDK 4.x log configuration.
SDK 3.x
The following log keywords and screenshots apply to SDK 3.x.
If the GCM/FCM channel is initialized successfully, a log entry similar to the following appears:
05-19 19:18:44.530 19153-19177/com.xxx D/MPS:GcmRegister: fcm token is eWIXLYCNP0Q:APA91bFUAgxj6XYf5okyoCBnRPw1UwITndzXrvPDgbdI2N44PYm17hFEBiNXNQJrJ8bOG_xjw3c3UPDAhzNMTLNjlAKcjUanKyLA6E3k4wEmgZuhgUT02UMmMvH2LVA1L2Z4-l-cT_Ug
When a message is received through the GCM/FCM channel, a log entry similar to the following appears:
05-19 19:20:04.900 19153-20391/com.alibaba.push2 D/MPS:GcmRegister: onReceiveMessage payload msg:[......]
Next steps
SDK 3.x: A helper activity processes the business logic for handling notification taps from vendor channels. For integration instructions, see Integrate a helper activity (3.x).
SDK 4.x: The FCM adapter passes the payload of a data message to the Mobile Push SDK for decryption and processing. The SDK then triggers the appropriate callback or builds a notification based on the message type. The MessageReceiver.onNotificationOpened and AliyunMessageIntentService.onNotificationOpened callbacks handle notification taps. The legacy onSysNoticeOpened callback is no longer used. For more information, see Message and notification handling interfaces (4.x). A helper activity is not required to process FCM data messages. If your app also integrates with other vendor channels, configure a helper activity as required by those vendors.
In Android SDK 4.x, the business callbacks for MessageReceiver and AliyunMessageIntentService have the following scope:
The ACCS proprietary channel and FCM support full business callbacks, including message received (
onMessage), notification arrived (onNotification), notification tapped (onNotificationOpened), and notification cleared (onNotificationRemoved).Other Android vendor channels (excluding FCM) support only the
onNotificationOpened(notification tapped) callback. These channels do not trigger callbacks for message received, notification arrived, or notification cleared.
-
If your app integrates with other vendor channels that use a helper activity, such as Xiaomi, Huawei, Honor, OPPO, vivo, or Meizu, you must still configure the vendor notification content and the tap-to-open Activity on the server as described in their respective documentation. The Mobile Push SDK handles FCM data messages directly.
GCM/FCM use cases
On a stock Android system
-
Under normal conditions, the GCM/FCM channel can deliver pushes whether your app is in the foreground, running in the background, or closed from the recent apps screen (which may kill the process).
-
If you force stop the app from Settings > App management, the system cannot restart the app automatically. As a result, it will not receive push notifications. You will see a log entry similar to the following, which indicates that a force-stopped app cannot be woken up:
GCM: broadcast intent callback: result=CANCELLED forIntent { act=com.google.android.c2dm.intent.RECEIVE flg=0x10000000 pkg=com.aliyun.emas.pocdemo (has extras) } -
When Battery optimization is enabled, you can control whether the app is allowed to run in the background. If background activity is allowed, the push channel is unaffected, and the app can receive pushes even after you kill the process. If background activity is not allowed, the system treats killing the process as a force stop, which may prevent the app from receiving pushes.
On a customized Android system
Some device manufacturers in the Chinese mainland have customized their Android systems to treat killing a process as a force stop. This can prevent message delivery through the GCM/FCM channel. In this case, we recommend integrating the specific vendor channel, such as Huawei or Xiaomi, to improve the push notification delivery rate after the app process is killed.
Vendor channel FAQ
Troubleshooting vendor channels and helper activities on Android
Conflicts between the Android vendor channel SDK and other vendor SDKs
Tapping a vendor channel notification does not open the correct activity on Android
Helper activity fails to start and reports a body parsing error on Android
Log shows "register not in main process, return" after integrating a Mobile Push vendor channel
Get vendor token on demand (4.x)
Starting from vendor extension package version 4.0.0, you can call getToken to read the most recent local FCM registration token. This API is optional and is designed for on-demand token queries.
Class: com.alibaba.sdk.android.push.register.GcmRegister.
Method signature
public static String getToken(Context context);
Parameter: context (Context). Pass a valid application context. Using the applicationContext is recommended. The context in the example represents a valid Context object from your app.
Return value: String. Returns null if no token is saved locally or if context is null. In Kotlin, this is represented as String?. This method reads from the local cache and does not refresh the token. To verify the token upload result, check the SDK upload logs and the device information in the console.
Code examples
String token = GcmRegister.getToken(context);
if (token == null || token.isEmpty()) {
// No FCM token is saved yet. You can query again after the vendor channel obtains and saves a token.
} else {
// Use the saved token as needed for your business logic.
}val token: String? = GcmRegister.getToken(context)
if (token.isNullOrEmpty()) {
// No FCM token is saved yet. You can query again after the vendor channel obtains and saves a token.
} else {
// Use the saved token as needed for your business logic.
}