IM 即时通讯
Android
开发指南

集成谷歌推送(FCM)

更新时间: 2023/06/29 11:03:27

NIM SDK 4.6.0 之后版本新增支持谷歌推送。

Google 推送 FCM(Firebase Cloud Messaging)是谷歌推出的推送服务,支持海外用户推送离线消息,提供广泛的消息传递功能。

谷歌推送 FCM 是 GCM 的升级版,适用于海外用户,FCM 成功推送需要两个条件

  • 手机安装并成功运行谷歌移动框架
  • 手机连接海外网络
  • 在部分国产手机上,虽然满足以上两个条件,FCM 成功推送,但是推送通知栏可能未显示。
  • 如果应用面向国内用户,则不需要集成 FCM。

本文主要介绍如何接入谷歌厂商的离线推送通道,使消息通过谷歌推送服务离线推送至未在线的用户。

集成 FCM

步骤 1:创建 Firebase 项目并注册应用

若已在 Firebase 平台注册应应用,请忽略该步骤。更多 FCM 推送服务的信息请参考推送服务启用指南

  1. 使用 Google 帐户登录 Firebase

  2. Firebase 控制台 创建一个 Firebase 项目。

    具体操作步骤
    1. Firebase 控制台,单击添加项目
      • 要将 Firebase 资源添加到现有 Google Cloud 项目,则输入该项目名称或从下拉菜单中选择该项目。
      • 如需要创建新项目,则输入项目名称。您还可以选择编辑项目名称下方显示的项目 ID。
    2. 如果出现提示,请查看并接受 Firebase 条款,然后单击继续
    3. 单击创建项目 。 如果使用现有的 Google Cloud 项目,则单击添加 Firebase

    Firebase 会自动为您的 Firebase 项目配置资源。该过程完成后,您将转到 Firebase 控制台中 Firebase 项目的概览页面。

  3. 在 Firebase 项目中注册应用。

    具体操作步骤
    1. 在 Firebase 控制台中 Firebase 项目的概览页面,单击添加应用或 Android 图标 ()。
    2. 输入 Android 应用的相关信息后,单击注册应用

步骤 2:在云信控制台添加谷歌推送证书

您需要向云信提供 FCM 项目的服务账号授权凭证,手动将该凭证上传到云信控制台。

云信支持两种授权方式:

  • (新版)通过 JSON 格式的私钥文件授权

    1. 在 Firebase 控制台中,打开设置 -> 服务帐号
    2. 单击生成新的私钥
    3. 保存生成的包含密钥的 JSON 文件。

    FCM.png

  • (旧版)通过 Server Key 授权

    1. 在 Firebase 控制台中,打开设置 -> 云消息传递
    2. 记录服务器密钥

    FireBase服务器秘钥.png

  • 2020 年 3 月开始,FCM 已停止创建旧服务器密钥。详情请参考官方文档授权旧版协议发送请求迁移到 HTTP v1 API
  • 自 V9.11.0 开始,云信已支持 FCM 新版推送证书,若需要上传新版 FCM 推送证书,请联系云信商务经理或技术支持。

将获取到的凭证上传至云信控制台:

  1. 云信控制台首页应用管理选择应用进入应用配置页面,单击证书管理页签。

  2. Android推送证书下单击添加证书,选择证书类型为 Google(FCM),配置谷歌推送相关信息。 谷歌推送.png

    云信推送证书字段对应 Firebase 应用的字段信息
    证书名称用户自定义推送证书名称,最大 32 字符
    对应初始化 NIM SDK 时需传入的推送证书信息中的 fcmCertificateName
    应用包名对应 Firebase 应用的软件包名称,最大 1000 字符
    AppSecret对应 Firebase 应用的 服务器密钥,最大 5000 字符
  3. 根据界面提示,在该对话框内配置证书类型和证书名称等信息。

步骤 3:添加 Firebase 配置文件

  1. 在 Firebase 项目中注册应用,单击下载 google-services.json 配置文件。
  2. 将配置文件添加至应用的 app 根目录下。
  3. 若需要在应用中启用 Firebase ,则需要将 google-services 插件添加到 Gradle 文件中。
    • 在项目级 Gradle 文件 (build.gradle)中配置 Google 的 Maven 代码库,以导入 Google 服务 Gradle 插件。
    buildscript {
    
    repositories {
      // Make sure that you have the following two repositories
      google()  // Google's Maven repository
      mavenCentral()  // Maven Central repository
        }
    
    dependencies {
      ...
    
      // Add the dependency for the Google services Gradle plugin
      classpath 'com.google.gms:google-services:4.3.15'
        }
    }
    
    allprojects {
    ...
    
    repositories {
        // Make sure that you have the following two repositories
        google()  // Google's Maven repository
        mavenCentral()  // Maven Central repository
        }
    }
    
    • 在应用级 Gradle 文件(app/build.gradle)中,添加 Google 服务 Gradle 插件:
    plugins {
    id 'com.android.application'
    
    // Add the Google services Gradle plugin
    id 'com.google.gms.google-services'
    ...
    }
    

步骤 4:导入 FCM 推送 Firebase SDK

  1. 在应用级 Gradle 文件(app/build.gradle)中,增加 Firebase 相关依赖和 Google 推送依赖。

    dependencies {
    // firebase-messaging
    implementation 'com.google.firebase:firebase-messaging:23.0.0'
    // firebase-analytics 
    implementation 'com.google.firebase:firebase-analytics:20.0.0'
    }
    

    NIM SDK 开发版和稳定版当前兼容的 FCM 推送版本如下:

    implementation 'com.google.firebase:firebase-messaging:23.0.0'
    implementation 'com.google.firebase:firebase-analytics:20.0.0'
    
  2. 同步您的应用以确保所有依赖项都具有所需的版本。

步骤 5:AndroidManifest.xml 配置

在 app/src/main 目录中,打开 AndroidManifest.xml 配置文件,添加对应权限。

<!-- fcm -->
<service android:name="com.netease.nimlib.mixpush.fcm.FCMTokenService">
    <intent-filter>
        <action android:name="com.google.firebase.INSTANCE_ID_EVENT" />
    </intent-filter>
</service>

您还可以设置收到 FCM 通知展示的图标和颜色。

    android:resource="@drawable/改成你的通知图标" />
<meta-data
    android:name="com.google.firebase.messaging.default_notification_color"
    android:resource="@color/改成你的通知字体颜色" />

如果您的应用使用了代码混淆,在 proguard-rules.pro 配置文件中添加以下配置以防止 FCM SDK 的代码被混淆:

-dontwarn com.google.**
-keep class com.google.** {*;}

谷歌推送 FCM 平台限制

消息类型

使用 FCM,您可以向客户端发送两种类型的消息:

  • 通知消息,有时被认为是“显示消息”。这些由 FCM SDK 自动处理。
  • 由客户端应用程序处理的数据消息。

通知消息包含一组预定义的用户可见键。相比之下,数据消息仅包含用户定义的自定义键值对。通知消息可以包含可选的数据负载。两种消息类型的最大负载均为 4000 字节,但从 Firebase 控制台发送消息时除外,它强制执行 1024 个字符的限制。

消息类型 使用场景 如何发送
通知消息 FCM 代表客户端应用程序自动向最终用户设备显示消息。通知消息具有一组预定义的用户可见键和自定义键值对的可选数据负载。 1. 在 Cloud Functions 或您的应用程序服务器等受信任的环境中,使用 Admin SDK 或 FCM 服务器协议:设置 notification 键。可能有可选的数据负载。总是可折叠的。查看显示通知和发送请求负载的一些示例。
2. 使用通知编辑器:输入消息文本、标题等,然后发送。通过提供自定义数据来添加可选的数据负载。
数据信息 客户端应用程序负责处理数据消息。数据消息只有自定义键值对,没有保留键名。 在 Cloud Functions或您的应用程序服务器等受信任的环境中,使用Admin SDK或FCM 服务器协议:仅设置data密钥。

消息推送类型配置

为了确保推送能正常提醒用户,需设置推送消息的类型 android_channel_id,该字段的配置可通过云信 NIM SDK 中消息体的 pushPayload 来实现。

示例代码:

// fcmField 结构示例
//     "fcmField": {
//         "android_channel_id":""
//     }

pushPayload.put("pushTitle", "Set push title here");
pushPayload.put("fcmField", fcmField);

对于传给 FCM 推送平台的消息类型有以下逻辑:

  • 您上传的消息体的 pushPayload中有分类(android_channel_id)字段,则使用 pushPayload中的字段值。
  • 如果消息体的 pushPayload中未传入分类(android_channel_id)字段,则使用云信默认的推送消息类型(android_channel_id="0"),若需要修改云信默认的推送消息类型请联系商务经理或技术支持。

推送消息自定义配置

在云信 NIM SDK 的消息体IMMessage 的 pushPayload 字段可配置一个key为fcmField,值为 map 或者 JSONObject 的 Entry,实现推送标题、图标等配置。具体的值请参考谷歌 FCM 官方文档

示例代码如下:

{
  "title": string,//通知的标题
  "body": string,//通知的正文
  "icon": string,//通知的图标
  "color": string,//通知的图标颜色
  "sound": string,//通知的提示声音
  "tag": string,//通知的标识符
  "click_action": string,//通知的点击跳转
  "image": string,//通知中的图片URL
  ...
}

设置消息的优先级

您有两个选项可以为下游消息分配传递优先级:正常优先级和高优先级。虽然跨平台的行为略有不同,但正常和高优先级消息的传递如下:

  • 正常优先级 当应用程序在前台时,普通优先级消息会立即传递。对于后台应用程序,交付可能会延迟。对于时间敏感度较低的消息,例如新电子邮件通知、保持 UI 同步或在后台同步应用程序数据,请选择正常传递优先级。
  • 高优先级 即使设备处于打盹模式,FCM 也会尝试立即传递高优先级消息。高优先级消息用于时间敏感的、用户可见的内容。

上行消息限制

  • 将每个项目的上游消息限制为 1,500,000 条/分钟,以避免上游目标服务器过载。
  • 将每台设备的上行消息限制为 1,000 条/分钟,以防止电池因不良应用行为而耗尽。

主题消息限制

主题订阅添加/删除速率限制为每个项目 3,000 QPS。 有关消息发送速率,请参阅扇出限制

此文档是否对你有帮助?
有帮助
去反馈
  • 集成 FCM
  • 步骤 1:创建 Firebase 项目并注册应用
  • 步骤 2:在云信控制台添加谷歌推送证书
  • 步骤 3:添加 Firebase 配置文件
  • 步骤 4:导入 FCM 推送 Firebase SDK
  • 步骤 5:AndroidManifest.xml 配置
  • 谷歌推送 FCM 平台限制
  • 消息类型
  • 消息推送类型配置
  • 推送消息自定义配置
  • 设置消息的优先级
  • 上行消息限制
  • 主题消息限制