Skip to main content

Integrate FCM push

  • The FCM push channel applies to Android devices officially sold outside China (with Google GMS services built in) and is activated in overseas network environments.
  • After integration, test FCM push following the conditions and steps described in Test FCM Push.

The server includes built-in components for communicating with the FCM backend. When the app running on the message recipient's device is killed or suspended in the background, the SDK's persistent connection drops. When a message needs to be delivered, the server sends a request to the FCM backend, which then delivers the message to the client application on the user's device.

Integrate FCM into your Android project​

This section follows Google's recommended setup workflow and describes how to add Firebase to your Android project using the Firebase console. During this process, you manually add the plugin and configuration file to your project.

The steps below have been simplified for quick reference. For detailed steps, see the Google documentation or the Firebase documentation.

Prerequisites​

  • Install or update Android Studio to the latest version.
    • Ensure your project meets the following requirements:
    • Android 5.0 (API 21) or higher
    • Jetpack (AndroidX) with the following version requirements:
      • com.android.tools.build:gradle 3.2.1 or higher
      • compileSdkVersion 28 or higher
  • Set up a physical device or use an emulator to run your app. Note that the FCM client is a Firebase SDK that depends on Google Play services and requires Google Play services to be installed on the device or emulator.
  • Sign in to Firebase with your Google account.

To add Firebase to your app, perform several tasks in the Firebase console and in your open Android project (for example, download a Firebase config file from the console and move it into your Android project).

Step 1: Create a Firebase project​

  1. In the Firebase console, click Add project.

    • To create a new project, enter the project name you want to use. You can also optionally change the project ID shown below the project name.
    • To add Firebase resources to an existing Google Cloud project, enter the project name or select it from the dropdown menu.

  2. Click Continue, then click Create project (or Add Firebase if using an existing Google Cloud project).

Firebase automatically provisions resources for your Firebase project. When the process completes, you are taken to the overview page of your Firebase project in the Firebase console.

A Firebase project is essentially a Google Cloud project with additional Firebase-specific configuration and services enabled. When you create a new Firebase project, you are creating a Google Cloud project behind the scenes. See the Firebase documentation for the relationship between Firebase projects and Google Cloud.

Step 2: Register your Android app with Firebase​

To use Firebase in your Android app, register your app with your Firebase project. Registering is often called "adding" your app to the project.

  1. Go to the Firebase console.

  2. In the center of the project overview page, click the Android icon or Add app to start the setup workflow.

  3. Enter your app's package name in the Android package name field.

    • The package name uniquely identifies your app on the device and in the Google Play Store.
    • The package name is often called the application ID.
    • Find your app's package name in the module-level (app-level) Gradle file, usually app/build.gradle (example package name: com.yourcompany.yourproject).
    • The package name value is case-sensitive and cannot be changed after you register the Firebase Android app in your Firebase project.

  4. Complete any other optional fields as needed, then click Register app.

    (width=600)

Step 3: Add the Firebase configuration file to your Android Studio project​

This step describes how to add the Firebase Android configuration file to your app.

  1. After registering your app, click Download google-services.json to obtain the Firebase Android configuration file (google-services.json).

    (width=600)

  2. Move the configuration file into your app's module (app-level) directory.

    (width=250)

    • To learn more about this configuration file, see Understanding Firebase Projects.
    • You can download the Firebase configuration file again at any time.
    • Make sure the configuration filename has no extra characters appended, such as (2).

  3. To enable Firebase products in your app, add the google-services plugin to your Gradle files.

    Note: All Firebase SDKs use the google-services Gradle plugin, which is unrelated to Google Play services.

    • Option 1: Add the plugin using Gradle's buildscript block. Both the Google documentation and Firebase documentation use this approach.

      1. Modify the root-level (project-level) Gradle file (build.gradle) to include rules for importing the Google Services Gradle plugin. Confirm you have added Google's Maven repository.

        Groovy
        buildscript {

          repositories {
            // Check that you have this line (if not, add it):
            google()  // Google's Maven repository
          }

          dependencies {
            // ...

            // Add the following:
            classpath 'com.google.gms:google-services:4.3.13'  // Google Services plugin
          }
        }

        allprojects {
          // ...

          repositories {
            // Check that you have this line (if not, add it):
            google()  // Google's Maven repository
            // ...
          }
        }

      2. In your module (app-level) Gradle file (usually app/build.gradle), apply the Google Services Gradle plugin:

        Groovy
        apply plugin: 'com.android.application'
        // Add the following line:
        apply plugin: 'com.google.gms.google-services'  // Google Services plugin

        android {
          // ...
        }

    • Option 2: Use Gradle's plugins DSL. Use this approach if you are familiar with the Gradle plugins DSL syntax and already use it in your project.

      1. By default, the plugins DSL only supports core plugins published to the Gradle Plugin Portal. Because the google-services plugin is not in that repository, you need to add Google's plugin repository.

        Declare Google's Maven repository in the root-level (project-level) Gradle settings file (settings.gradle).

        Groovy
        pluginManagement {
            // (Optional) You can declare and version the google-services plugin here
            //plugins {
            //    id 'com.google.gms.google-services' version '4.3.13'
            //}
            repositories {
                google()
                gradlePluginPortal()
            }
        }
        rootProject.name='exampleProject'
        include ':app'

      2. In your module (app-level) Gradle file (usually app/build.gradle), apply the google-services plugin and declare the version:

        Groovy
        plugins {
            id 'com.google.gms.google-services' version '4.3.13'
        }

        Note: If you already declared the google-services plugin with a version in the pluginManagement {} block of settings.gradle, you can apply it in app/build.gradle without specifying the version:

        Groovy
        plugins {
            id 'com.google.gms.google-services'
        }

Step 4: Add the Firebase SDK to your Android app​

  1. Declare the dependencies in the module (app-level) Gradle file (usually app/build.gradle) and enable FCM push.
Groovy
android {
 defaultConfig {
    //...
    manifestPlaceholders = [
        FCM_PUSH_ENABLE : "true"
    ]
 }
}
dependencies {
    // x.y.z is the current SDK version number
    implementation 'ai.nexconn.chat:nexconn-push-fcm:x.y.z'
}

For more details, see the Firebase documentation Set up a Firebase Cloud Messaging client app on Android.

You have successfully integrated Firebase into your Android project.

Continue to the next step to authorize FCM requests in the console.

Authorize FCM requests in the console​

Requests from the server to FCM must be authorized. You need to provide the console with the service account credentials for your FCM project. Upload the credentials manually.

Step 1: Get Google service account credentials​

Firebase projects support Google service accounts. You need to obtain credentials from your Google service account to authorize the server to call the Firebase server API using those account credentials.

To authenticate a service account and grant it access to Firebase services, generate a private key file in JSON format. To generate a JSON-format private key file for your service account:

  1. In the Firebase console, open Settings > Service accounts.
  2. Click Generate new private key, then click Generate key to confirm.
  3. Store the JSON file containing the key securely. You will need to upload it to the console.

(width=600)

Step 2: Upload the FCM credentials in the console​

Go to the console, and in the Application Identifier > Android > Google (FCM) tab, enter the credentials obtained in the previous step.

  • Authentication Method:

    • Certificate (recommended): Upload the private key JSON file generated from your service account.

    • API Key (uses the legacy Server Key authorization method and legacy FCM API): Enter the server key obtained from your service account.

      Warning

      If your project uses the API Key authentication method, note that sending messages via the FCM XMPP and HTTP legacy APIs (including upstream messages) was officially deprecated by FCM on June 20, 2023 and will be removed in June 2024, at which point the push service backend will also remove this capability. Migrate to certificate-based authentication (FCM JSON private key file) as soon as possible. For details, see Get Google Service Account Credentials above.

  • Push Method (see Firebase documentation About FCM messages):

    • Data Message: After the SDK receives the data message, it parses the data and displays the notification. Developers can also handle it with custom logic. The server sends data containing both FCM "data messages" and "notification messages".
    • Notification Message: The Android OS displays the notification directly in the notification panel. The server only sends data corresponding to the FCM "data message" type.

  • Intent: Define the action associated with a user clicking the notification — corresponds to the FCM click_action field. When specified, clicking the notification launches the Activity that matches this Intent by default. Prefix with your app's package name to ensure uniqueness.

    For example, specify the Intent in the console as:

    com.yourapp.demo.ExampleActivity

    In your app's AndroidManifest.xml, specify an Activity that matches the Intent:

    xml
    <activity android: name = ".ExampleActivity">
        <intent-filter>
            <action android: name = "com.yourapp.demo.ExampleActivity" />
            ...
        </intent-filter>
    </activity>

  • Priority (see Firebase documentation Setting the priority of a message):

    • Normal: Normal priority messages are delivered immediately when the app is in the foreground. When the app is in the background, delivery may be delayed. Choose normal priority for messages that are not time-sensitive (for example, new email notifications, UI sync, or background data sync).
    • High: FCM immediately attempts to deliver high priority messages even when the device is in Doze mode. High priority messages are suitable for time-sensitive, user-visible content.

  • Push Notification Title: When calling server-side push notification APIs without a notification title, the title configured here is used. If the sending user ID has no username on the server, this title is also used. In general, this title is not used when the client sends messages that are converted to push notifications.

  • Push Channel Type: By default, GCM push uses the default channel. To use a private channel, select private channel and specify the Channel ID.

Enable FCM push service on the client​

After you complete the FCM dependency and console configuration, initialize the SDK in your app so it can register with FCM and report the device token to the server.

If you need to re-enable Analytics data collection after enabling FCM push, call the setAnalyticsCollectionEnabled() method of the FirebaseAnalytics class. For example:

Java
setAnalyticsCollectionEnabled(true);
tip

If you do not need to receive push notifications, set the enablePush initialization parameter to false to request that the server disable push for the current device. You can also disable push for the current device when disconnecting.

Test FCM push​

After completing the steps above, you can test whether the push integration is working.

Device requirements​

It is recommended to test FCM push notification reception on an Android device officially sold outside China. Detailed device requirements are as follows:

  1. Use a physical device for testing. Emulators cannot receive remote push notifications.
  2. The device must support Google GMS (Google Mobile Services). Devices officially sold outside China typically come with GMS pre-installed. Devices sold in mainland China generally do not have GMS pre-installed, and some brands cannot install GMS due to authorization restrictions.
  3. Due to Google compliance requirements, some Chinese device manufacturers have imposed stricter restrictions on GMS usage. Certain devices that passed Google certification have had GMS disabled, meaning many Chinese-market phones cannot receive FCM push notifications even with the Google Services Framework installed and a VPN enabled.

Network requirements​

It is recommended to test in a simulated overseas network environment. Detailed requirements are as follows:

  1. When testing in mainland China, the test device must establish the IM connection using a foreign IP address and access the service via an overseas IP. If a domestic IP is used, the server treats the device as being in China and will not enable the FCM channel.
  2. The test device's network environment must have normal access to Google network services. Otherwise, even if FCM push is triggered, the device cannot receive push notifications from Google's FCM service.

Test steps​

Assume you are testing in the development environment with a development-environment App Key.

Steps:

  1. After successfully connecting the app, kill the app process.
  2. Go to IM Server API Debug in the console, switch to the development environment for your app, find Messages > Message Service > Send One-to-One Message, and send a one-to-one message directly.
  3. Check whether the device receives the push notification from this app.

Troubleshooting​

  • If the app being tested belongs to an overseas data center (North America or Singapore), verify that the naviServer property of InitParams is set to the correct navigation domain before SDK initialization.
  • Send a message directly from the Google FCM service backend to the device. If it is not received, first check your integration against the documentation above.
  • Check whether the app is classified as a background-restricted app on the device. On Android P and higher, FCM will not send push notifications to apps that the user has added background restrictions to (for example, via Settings > Apps & notifications > [appname] > Battery). See the Android developer documentation on background-restricted apps.
  • Avoid sending the same message content to the same device too frequently, as the FCM backend may block these and prevent delivery.
  • Check whether the test device is running a Chinese-market ROM. Some brands no longer support self-installing GMS. Replace the test device with one sold overseas or update its system firmware.

If the issue cannot be resolved, submit a ticket and provide your message ID.

ProGuard rules​

Groovy
-keep public class com.google.firebase.* {*;}

Handle push notification click events​

Note for CallKit SDK users​

When the FCM push method in the console is set to Data Message, the SDK does not display notifications for audio/video signaling messages (call invitations, hang-ups, etc.) by default. To resolve this:

The FCM data message received by the SDK wakes up the app. Call the connect method in the Application's onCreate method. After a successful connection, the SDK displays the notification automatically.

Note for CallLib SDK users​

When the FCM push method in the console is set to Data Message, the SDK does not display notifications for audio/video signaling (call invitations, hang-ups, etc.) by default. You can override the preNotificationMessageArrived method of PushEventListener via Customize Push Notification Style and implement the notification display logic there.

Last updated on