Google push channel integration

Updated at:

Learn how to integrate the Google push channel.

Important

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.json file. From this file, record the values of the following keys: project_number, mobilesdk_app_id, project_id, and current_key. These values correspond to sendId, applicationId, projectId, and apiKey, respectively.

    image

  • In the Firebase console, navigate to Project settings > Service accounts. Generate a new private key, download the file, and store it securely.

    image

  • 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.

Important

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'
}
Note

The Mobile Push SDK for vendor channels only supports Maven dependencies.

Step 2: Configure the SDK

2.1 Initialize SDK

Important
  • Before you integrate with FCM, ensure that Google Play services is installed and running correctly on the device.

  • In your Application class, 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, and apiKey parameters 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);
Note

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.

Note

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.

Important

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.

Important
  • 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.
}