FCM push

Message Push Service supports the Firebase Cloud Messaging (FCM) channel for Android apps on devices outside China.

This topic describes how to integrate the FCM push channel into an mPaaS-based Android app.

Prerequisites

Before you begin, ensure that you have:

• Native AAR integration (FCM does not support Portal & Bundle integration)

• Gradle 4.1 or later

• AndroidX enabled in your project

• com.android.tools.build:gradle 3.2.1 or later

• compileSdkVersion 28 or later

Integrate the FCM SDK

1. Register your app in the Firebase console.

   Log in to the Firebase console and register your application. See the Firebase documentation for details.

2. Add the Firebase configuration file to your app.

   Download the google-services.json configuration file and place it in the app module directory of your project.

3. Add the Google Services plugin to the buildScript dependencies in the root-level build.gradle file.

   // FILE: build.gradle (root-level)
   // PURPOSE: Add Google Services plugin and Maven repository
   buildscript {
   
     repositories {
       // Check that you have the following line (if not, add it):
       google()  // Google's Maven repository
     }
   
     dependencies {
       // ...
   
       // Add the following line:
       classpath 'com.google.gms:google-services:4.3.4'  // Google Services plugin
     }
   }
   
   allprojects {
     // ...
   
     repositories {
       // Check that you have the following line (if not, add it):
       google()  // Google's Maven repository
       // ...
     }
   }

4. Apply the Google Services plugin in the app module's build.gradle file.

   // FILE: build.gradle (app-level)
   // PURPOSE: Enable Google Services plugin for this module
   apply plugin: 'com.android.application'
   // Add the following line:
   apply plugin: 'com.google.gms.google-services'  // Google Services plugin
   
   android {
     // ...
   }

5. Add the FCM SDK dependency in the app module's build.gradle file.

   // FILE: build.gradle (app-level)
   // PURPOSE: Add FCM SDK and Analytics dependencies via Firebase BoM
   dependencies {
       // Import the BoM for the Firebase platform
       implementation platform('com.google.firebase:firebase-bom:26.1.1')
   
       // Declare the dependencies for the Firebase Cloud Messaging and Analytics libraries
       // When using the BoM, you don't specify versions in Firebase library dependencies
       implementation 'com.google.firebase:firebase-messaging'
       implementation 'com.google.firebase:firebase-analytics'
   }

Integrate mPaaS

1. Add the FCM Adapter dependency in the app module's build.gradle file.

   // FILE: build.gradle (app-level)
   // PURPOSE: Add mPaaS FCM Adapter to bridge FCM with Message Push Service
   dependencies {
       implementation 'com.mpaas.push:fcm-adapter:0.0.2'
   }

2. Integrate the MPS component. The required mPaaS baseline version depends on the adapter version:

   • com.mpaas.push:fcm-adapter:0.0.2: baseline version 10.1.68.34 or later

   • com.mpaas.push:fcm-adapter:0.0.1: baseline version 10.1.68.19 or later

3. Understand message delivery behavior.

   The FCM SDK delivers messages through different channels depending on the app state:

   App state	Delivery channel	Display behavior
   Background or process killed	FCM channel	Displayed in the notification bar, same as other vendor channels
   Foreground	Self-built channel	FCM passes the message to the app, which receives it via the self-built channel

   • When the app is in the background or the process is killed, messages are delivered through the FCM channel and displayed in the notification bar.

   • When the app is in the foreground, FCM passes messages to the app, which receives them through the self-built channel.

4. (Optional) Register an error receiver to handle FCM initialization failures.

   If FCM initialization fails, a broadcast with the action action.mpaas.push.error.fcm.init is sent. Register a BroadcastReceiver to catch it and retrieve the error code. For the full list of error codes, see the ConnectionResult error code documentation.

   1. Declare the receiver in AndroidManifest.xml:

      // FILE: AndroidManifest.xml
      // PURPOSE: Register FCM error broadcast receiver
      <receiver android:name=".push.FcmErrorReceiver" android:exported="false">
          <intent-filter>
              <action android:name="action.mpaas.push.error.fcm.init" />
          </intent-filter>
      </receiver>

   2. Implement the receiver class:

      // FILE: FcmErrorReceiver.java
      // PURPOSE: Receive and handle FCM initialization error broadcasts
      package com.mpaas.demo.push;
      
      import android.content.BroadcastReceiver;
      import android.content.Context;
      import android.content.Intent;
      import android.widget.Toast;
      
      public class FcmErrorReceiver extends BroadcastReceiver {
          @Override
          public void onReceive(Context context, Intent intent) {
              String action = intent.getAction();
              if ("action.mpaas.push.error.fcm.init".equalsIgnoreCase(action)) {
                  Toast.makeText(context, "fcm error " + intent.getIntExtra("error", 0), Toast.LENGTH_SHORT).show();
              }
          }
      }