跳到主要内容
版本：v3

FCM 推送指南

FCM 推送概述​

自 Android 8.0 之后，系统权限控制越来越严，第三方推送通道的生命周期受到较大限制。为此，我们推出 FCM 推送方案。这保障了主流 Android 系统上的推送到达率。

在 FCM 推送方案里，消息下发时使用的通道不再是我们自己维持的 WebSocket 长连接，而是借用 FCM 进行通信。 一条推送消息下发的步骤如下：

  1. 开发者调用云服务 Push API 请求对全部或特定设备进行推送；
  2. 云推送服务端将请求转发给 FCM；
  3. FCM 通过手机端的系统通道下发推送消息，同时手机端系统消息接收器将推送消息展示到通知栏；
  4. 终端用户点击消息之后唤起目标应用或者页面。

整个流程与苹果的 APNs 推送类似，SDK 在客户端基本不会得到调用。

Android FCM 推送功能仅对商用版应用开放，如果希望使用该功能，请进入 开发者中心 > 你的游戏 > 游戏服务 > 云服务 > 推送通知 > 设置 > FCM，打开 FCM 推送的开关。

注意，FCM 推送可以随时按需开关。当该选项关闭后，下一次 Android 推送会与普通推送一样自动选择自有通道送达客户端，除了会再次遇到上面提到的自有通道在部分 ROM 上会受到限制的问题之外，不会有别的影响。而当该选项再次开启后，Android 推送又会去选择厂商推送渠道。

开启了 FCM 推送之后，Installation 表中每一个设备对应的记录，会增加 registrationId 字段，用于记录厂商分配的注册 id（类似于 APNs 的 device token），同时还会增加一个 vendor 字段（如果没有这一字段，则说明客户端集成有问题），其值为 fcm。

推送提醒的红点或角标展示​

Android 系统默认支持根据 FCM 推送数量展示红点（桌面应用图标上显示）和角标（应用图标的长按菜单中显示）。

通知栏消息与透传消息​

当应用在前台时，FCM 支持透传消息给应用。

即时通讯的离线推送​

在即时通讯服务中，在 iOS 平台上如果用户下线，是可以启动离线消息推送机制的，对于 Android 用户来说，如果只是使用云推送自有通道，那么是不存在离线推送的，因为聊天和推送共享同一条 WebSocket 长链接，在即时通讯服务中用户下线了的话，那么推送也必然是不可达的。但是如果启用了 FCM 推送，因为推送消息走的是 FCM，这一点和 iOS 基本一致，所以这时候 Android 用户就存在离线推送的通知路径了。 也就是说，如果开启了 FCM 推送，那么即时通讯里面的离线推送和静音机制，对使用了 FCM 推送的 Android 用户也是有效的。

受限说明​

推送消息长度限制：

  • 消息中的应用包名最大支持 128 字节，消息内容最大支持 4KB。

最低 Android 版本要求：

  • FCM 推送支持 Android 4.1 或以上版本的手机系统（minSdkVersion：16）。

影响送达率的因素说明：

  • 终端设备是否在线。如果设备离线，推送服务会缓存消息，待设备上线后，再将消息推送给设备。
  • 终端设备上集成推送服务 SDK 的应用是否被卸载。
  • 终端设备的网络状况是否稳定。
  • 终端设备的安全控制策略。
  • 透传消息的送达受 Android 系统和应用是否驻留在后台影响。

推荐的接入方式​

FCM 推送本质上还是依赖于 FCM 的 SDK 和服务端能力，我们的客户端 SDK 只是对 FCM SDK 的包装，而实际的推送请求也是通过 LeanCloud 中转之后发送到 FCM 后台。我们的客户端 SDK 更新速度可能跟不上 FCM 的迭代速度，因此建议大家直接对接 FCM SDK，然后在客户端把 FCM 分配的「注册 id」与 FCM 标识（见上一章 vendor 的说明）保存到设备信息（Installation）中，这样之后一样可以通过我们的推送 API 来给所有设备正确发送推送信息。

客户端接入方法​

开发者从 FirebaseMessagingService 继承自己的实现类，然后在 onNewToken 回调函数中调用如上例代码进行保存（记得将 vendor 换成 fcm）。示例代码可以参考 LCFirebaseMessagingService。

发送 FCM 推送的服务端 API​

可以参考这里的说明来发送推送请求：推送 REST API 使用指南。

如果开发者要集成我们封装的 FCM 推送 SDK，可以继续往下阅读，如果自行接入 FCM SDK，则可以忽略下文。

FCM 推送 library 的构成​

FCM（Firebase Cloud Messaging）是 Google/Firebase 提供的一项将推送通知消息发送到手机的服务。接入时后台需要配置连接 FCM 服务器需要的推送 key 和证书，FCM 相关的 token 由 LeanCloud SDK 来申请。

环境要求​

FCM 客户端需要在运行 Android 4.1 或更高版本且安装了 Google Play 商店应用的设备上运行，或者在运行 Android 4.1 且支持 Google API 的模拟器中运行。具体要求参见 在 Android 上设置 Firebase 云消息传递客户端应用。

接入 SDK​

添加 Firebase 配置文件​

从 Firebase 控制台下载最新的配置文件（google-services.json），加入到应用的模块（应用级）目录中。

将 Google 服务插件添加到 Gradle 文件中​

首先，在根级（项目级）Gradle 文件 (build.gradle) 中添加规则，以纳入 Google 服务 Gradle 插件：

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.5'  // Google Services plugin
  }
}

allprojects {
  // ...

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

然后，在模块（应用级）Gradle 文件（通常是 app/build.gradle）中，应用 Google 服务 Gradle 插件：

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

android {
  // ...
}

导入 SDK FCM 包​

在模块（应用级）Gradle 文件（通常是 app/build.gradle）中，在 dependencies 中添加依赖：

dependencies {
  implementation 'cn.leancloud:leancloud-fcm:8.2.24@aar'
  // 即时通信与推送需要的包
  implementation 'cn.leancloud:realtime-android:8.2.24'
  implementation 'io.reactivex.rxjava2:rxandroid:2.1.0'

  // Import the BoM for the Firebase platform
  implementation platform('com.google.firebase:firebase-bom:27.0.0')
  // 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'
}

修改应用清单​

将以下内容添加至应用的 AndroidManifest 文件中：

  • PushService 服务。

    <service android:name="cn.leancloud.push.PushService"/>

  • LCFirebaseMessagingService 服务。如果你希望在后台进行除接收应用通知之外的消息处理，则必须添加此服务。要接收前台应用中的通知、接收数据有效负载以及发送上行消息等，必须继承此服务。

    <service
      android:name="cn.leancloud.LCFirebaseMessagingService"
      android:exported="false">
    <intent-filter>
      <action android:name="com.google.firebase.MESSAGING_EVENT"/>
    </intent-filter>
    </service>

  • （可选）应用组件中用于设置默认通知图标和颜色的元数据元素。如果传入的消息未明确设置图标和颜色，Android 就会使用这些值。

    <meta-data
      android:name="com.google.firebase.messaging.default_notification_icon"
      android:resource="@drawable/ic_launcher_background" />
    <meta-data
      android:name="com.google.firebase.messaging.default_notification_color"
      android:resource="@color/colorAccent" />

  • （可选）从 Android 8.0（API 级别 26）和更高版本开始，Android 系统支持并推荐使用通知渠道。FCM 提供具有基本设置的默认通知渠道。如果你希望创建和使用你自己的默认渠道，请将 default_notification_channel_id 设为你的通知渠道对象的 ID（如下所示）；如果传入的消息未明确设置通知渠道，FCM 就会使用此值。

    <meta-data
      android:name="com.google.firebase.messaging.default_notification_channel_id"
      android:value="@string/default_notification_channel_id"/>

  • 如果 FCM 对于 Android 应用的功能至关重要，请务必在应用的 build.gradle 中设置 minSdkVersion 16 或更高版本。这可确保 Android 应用无法安装在不能让其正常运行的环境中。

程序初始化​

使用 FCM 推送，客户端程序无需做特别的初始化。如果注册成功，_Installation 表中应该出现 vendor 这个字段为 fcm 的新记录。

配置控制台（设置 FCM 的 ProjectId 及 私钥文件）​

在 Firebase 控制台 > 项目设置 > 服务账号 > Firebase Admin SDK > 生成新的秘钥 可以获得服务端发送推送请求的私钥文件。将此 文件 及 ProjectId 通过 开发者中心 > 你的游戏 > 游戏服务 > 云服务 > 推送通知 > 设置 > FCM，与云服务应用关联。

取消 FCM 推送注册​

对于已经注册了 FCM 推送的用户，如果想取消 FCM 推送的注册而改走云服务自有的 WebSocket 的话，可以调用如下函数：

LCMixPushManager.unRegisterMixPush();

此函数为异步函数，如果取消成功会有 Registration canceled successfully 的日志输出，万一取消注册失败的话会有类似 unRegisterMixPush error 的日志输出。

错误排查建议​

  • 只要注册时有条件不符合，SDK 会在日志中输出导致注册失败的原因，例如 register error, mainifest is incomplete 代表 manifest 未正确填写。如果注册成功，_Installation 表中的相关记录应该具有 vendor 这个字段并且不为空值。

  • 如果注册一直失败的话，请提交工单或去论坛发帖，提供相关日志、具体机型以及系统版本号，我们会跟进协助来排查。