跳到主要内容

集成 FCM 推送

  • FCM 推送通道适用于海外正式发售的 Android 设备（内置 Google GMS 服务），且会在海外网络环境下启用。
  • 建议您在集成后根据测试 FCM 推送 中描述的条件与步骤进行测试。

融云服务端已集成与 FCM 后端通信的功能组件。在消息接收者设备上运行的 App 被杀进程或者在后台被挂起，IM SDK 长连接通道会断开。此时如有消息需要送达，融云服务端会向 FCM 后端发送消息请求，然后由 FCM 后端再将消息发送到用户设备上运行的客户端应用。

Android 项目集成 FCM​

本节内容将遵照 Google 推荐的设置工作流，描述如何通过 Firebase 控制台 将 Firebase 添加到您的 Android 项目。在此过程中，您必须手动将插件和配置文件添加到您的项目。

为帮助您快速以下步骤已经简化。如需详细步骤，您可以参考 Google 文档，或 Firebase 中文文档。

前提条件​

  • 安装最新版本的 Android Studio，或将其更新为最新版本。
    • 确保您的项目满足以下要求：
    • （SDK ≧ 5.6.3）使用 Android 5.0（API 21）或更高版本；
    • （SDK < 5.6.3）使用 Android 4.4（API 19）或更高版本；
    • 使用 Jetpack (AndroidX)，这需要满足以下版本要求：
      • com.android.tools.build:gradle 3.2.1 或更高版本
      • compileSdkVersion 28 或更高版本
  • 设置一台实体设备或使用模拟器运行您的应用。 请注意，FCM 客户端属于 依赖于 Google Play 服务的 Firebase SDK，需要在设备或模拟器上安装 Google Play 服务。
  • 使用您的 Google 帐号登录 Firebase。

如要将 Firebase 添加到您的应用，您需要在 Firebase 控制台和打开的 Android 项目中执行若干任务（例如，从控制台下载 Firebase 配置文件，然后将配置文件移动到 Android 项目中）。

第 1 步：创建 Firebase 项目​

  1. 在Firebase 控制台中，点击添加项目。

    • 如需创建新项目，请输入要使用的项目名称。您也可以视需要修改项目名称下方显示的项目 ID。
    • 如需将 Firebase 资源添加到现有 Google Cloud 项目，请输入该项目的名称或从下拉菜单中选择该项目。

  2. 点击继续。最后，点击创建项目（如果使用现有的 Google Cloud 项目，则点击添加 Firebase）。

Firebase 会自动为您的 Firebase 项目预配资源。完成此过程后，您将进入 Firebase 控制台中 Firebase 项目的概览页面。

Firebase 项目实际上只是一个启用了额外的 Firebase 特定配置和服务的 Google Cloud 项目。在创建新的 Firebase 项目时，您实际上是在幕后创建 Google Cloud 项目。详情可参考 Firebase 中文文档 Firebase 项目与 Google Cloud 之间的关系。

第 2 步：在 Firebase 中注册您的 Android 应用​

如需在 Android 应用中使用 Firebase，您需要向 Firebase 项目注册您的应用。注册应用的过程通常称为将应用“添加”到项目中。

  1. 前往 Firebase 控制台。

  2. 在项目概览页面的中心位置，点击 Android 图标或添加应用，启动设置工作流。

  3. 在 Android 软件包名称字段中输入应用的软件包名称。

    • 软件包名称是您的应用在设备上和 Google Play 商店中的唯一标识符。
    • 软件包名称通常称为应用 ID。
    • 在模块（应用级）Gradle 文件（通常是 app/build.gradle）中查找应用的软件包名称（示例软件包名称：com.yourcompany.yourproject）。
    • 请注意，软件包名称值区分大小写，并且当您在 Firebase 项目中注册此 Firebase Android 应用后，将无法更改其软件包名称。

  4. 如有需要，可完成其他可选配置。然后点击注册应用。

    (width=600)

第 3 步：在 Android Studio 项目中添加 Firebase 配置文件​

本步骤描述如何将 Firebase Android 配置文件添加到您的应用。

  1. 注册应用后，点击下载 google-services.json 以获取 Firebase Android 配置文件 (google-services.json)。

    (width=600)

  2. 将配置文件移到应用的模块（应用级）目录中。

    (width=250)

    • 如需详细了解此配置文件，请访问了解 Firebase 项目。
    • 您可以随时再次下载 Firebase 配置文件。
    • 请确保该配置文件名未附加其他字符，如 (2)。

  3. 如需在应用中启用 Firebase 产品，请将 google-services 插件添加到 Gradle 文件中。

    注意，所有 Firebase SDK 都使用 google-services Gradle 插件（ google-services），但该插件与 Google Play 服务没有任何关系）。

    • 方法 1：使用 Gradle 的 buildscript 块添加插件。Google 文档 与 Firebase 中文文档 均使用该方法。

      1. 修改根级（项目级）Gradle 文件 (build.gradle) ，在 buildscript 块中添加规则，以导入 Google 服务 Gradle 插件。请确认您添加了 Google 的 Maven 代码库。

        Groovy
        buildscript {

          repositories {
            // 请检查是否有此行 (如果没有，请添加):
            google()  // Google's Maven repository
          }

          dependencies {
            // ...

            // 请添加以下配置:
            classpath 'com.google.gms:google-services:4.3.13'  // Google Services plugin
          }
        }

        allprojects {
          // ...

          repositories {
            // 请检查是否有此行 (如果没有，请添加):
            google()  // Google's Maven repository
            // ...
          }
        }

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

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

        android {
          // ...
        }

    • 方法 2：使用 Gradle 的 plugins DSL。如果您熟悉 Gradle 的 plugins DSL 语法，且已在项目中使用，可使用该方法。

      1. 默认情况下 plugins DSL 仅支持已发布在 Gradle Plugin Portal 的核心插件。因为 google-services 插件不在该仓库中，所以您需要先添加 Google 的插件仓库地址。

        在根级（项目级）Gradle 设置文件 (settings.gradle) 中声明 Google 的 Maven 代码库。

        Groovy
        pluginManagement {
            // （可选）在声明仓库时即可引入 google-services plugin 并声明版本
            //plugins {
            //    id 'com.google.gms.google-services' version '4.3.13'
            //}
            repositories {
                google()
                gradlePluginPortal()
            }
        }
        rootProject.name='exampleProject'
        include ':app'

      2. 在您的模块（应用级）Gradle 文件（通常是 app/build.gradle）中，应用 Google 服务 Gradle 插件google-services 插件，并声明版本：

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

        注意：如果在 settings.gradle 的 pluginManagement {} 块中已使用 plugins DSL 引入了 google-services 插件，并且声明了版本，则可直接在模块（应用级）app/build.gradle 文件中应用插件，无需再声明版本：

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

第 4 步：将 Firebase SDK 添加到您的 Android 应用​

1.在模块（应用级）Gradle 文件（通常为 app/build.gradle）中声明依赖项,并开启 fcm 推送。

Groovy
android {
 defaultConfig {
    //...
    manifestPlaceholders = [
        FCM_PUSH_ENABLE : "true"
    ]
 }
}
dependencies {
    // x.y.z 为当前 IM SDK 版本号
    implementation 'cn.rongcloud.sdk.push:fcm:x.y.z'
}

如需了解更多细节，可参考 Firebase 中文文档 设置 Firebase Cloud Messaging 客户端应用 (Android)。

至此，您已经成功将 Firebase 集成到 Android 项目中。

请继续完成后续步骤，在控制台授权 FCM 请求。

在控制台授权 FCM 请求​

从融云发送到 FCM 的请求必须经过授权。因此，您需要向融云提供 FCM 项目相关的服务账号授权凭证。您需要手动将该凭证上传到控制台。

第 1 步：获取 Google 服务账号凭证​

Firebase 项目支持 Google 服务帐号。您需要从您的 Google 服务帐号获取凭据，然后授权融云服务器这些帐号凭据调用 Firebase 服务器 API。

如需对服务帐号进行身份验证并授予其访问 Firebase 服务的权限，您必须生成 JSON 格式的私钥文件。如需为您的服务帐号生成 JSON 格式的私钥文件，请执行以下操作：

  1. 在 Firebase 控制台中，打开设置 > 服务帐号。
  2. 点击生成新的私钥，然后点击生成密钥进行确认。
  3. 妥善存储包含密钥的 JSON 文件。稍后需要在融云控制台上传该文件。

(width=600)

第 2 步：在控制台上传 FCM 凭证​

前往融云控制台，在应用标识 > Android > Google（FCM） 标签页中，填写上一步在获取的凭证。

  • 选择鉴权方式：

    • 证书（推荐）：上传从您的服务帐号生成的私钥 JSON 文件。

    • API 密钥（使用旧版 Server Key 授权方式和旧版 FCM API）：填入从您的服务帐号获取的服务器密钥。

      警告

      如果您的项目中配置的鉴权方式中为 API 密钥，请注意自 2023 年 6 月 20 日起，使用 FCM XMPP 和 HTTP 旧版 API 发送消息（包括上游消息）已被 FCM 官方弃用，并将于 2024 年 6 月移除，融云的推送服务后台届时将同步移除该能力。因此，您需要尽快迁移到使用证书（FCM 的 JSON 格式私钥文件）的鉴权方式，详细方法请参考上文获取 Google 服务账号凭证。

  • 推送方式（详见 Firebase 中文文档 FCM 消息类型）：

    • 透传消息方式：IMLib SDK 接收到透传数据后，进行数据解析并弹出通知。开发者也可以自定义处理。融云下发包含 FCM「数据消息」和「通知消息」的数据。
    • 通知消息方式：由 Android OS 直接在通知面板弹出通知。融云仅下发对应 FCM「数据消息」类型的数据。

  • intent：自定义用户点击通知相关联的操作，对应 FCM 的 click_action 字段。如果指定，当用户单击通知时，默认将启动匹配该 Intent 的 Activity。最好将应用的软件包名称用作前缀，以确保唯一性。

    例如，在控制台指定 Intent 为：

    com.yourapp.demo.ExampleActivity

    在您 App 的 AndroidManifest.xml 中需要指定可以匹配该 Intent 的 Activity。

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

  • 优先级（详见 Firebase 中文文档 设置消息的优先级）

    • 普通：应用在前台运行时，普通优先级消息会被立即传递。当应用在后台运行时，消息传递可能会延迟。如果是对时间不太敏感的消息（例如新电子邮件通知、使界面保持同步或在后台同步应用数据），建议您选择普通传递优先级。
    • 高：即使设备处于低电耗模式，FCM 也会立即尝试传递高优先级消息。 高优先级消息适用于对时间敏感的用户可见内容。

  • 推送通知标题：在调用服务端 API 接口 /push.json、/push/user.json、 /push/custom.json 接口推送通知时，如未传入通知栏标题，则使用下方设置的“推送通知标题”。从服务端发消息时，如果发送用户 ID 在融云服务端没有用户名，也会使用此 “推送通知标题”。一般情况下客户端发送消息转 Push 时不显示此标题。

  • 推送通道类型：GCM 推送融云默认使用的是默认推送通道，如需要使用私有推送通道，可选择私有通道并设置 Channel ID 即可。

客户端启用 FCM 推送服务​

  1. 在 SDK init 之前，初始化 RongPushPlugin 模块。

    Java
    RongPushPlugin.init(getContext());

    如果找不到 RongPushPlugin 模块，请检查是否已经集成融云自建推送通道。

  2. （可选）启用 FCM 推送后，如需重新启用 Analytics 数据收集，请调用 FirebaseAnalytics 类的 setAnalyticsCollectionEnabled() 方法。例如：

    Java
    setAnalyticsCollectionEnabled(true);
提示

如果不需要接收推送，可以通过设置 SDK 的初始化配置中的 enablePush 参数为 false，向融云服务申请禁用推送服务（当前设备）。您也可以在断开连接时设置不接收推送（当前设备）。

测试 FCM 推送​

在完成上述步骤之后，可直接测试推送是否集成成功。

设备条件​

建议直接使用在海外正式发售的 Android 设备测试 FCM 推送通知的接收。针对测试设备的详细要求如下：

  1. 测试设备必须使用真机。模拟器收不到远程推送。
  2. 测试设备必须支持 Google GMS 服务（Google Mobile Services）。您可以直接使用在海外正式发售的 Android 设备。注意，在中国大陆地区发售的设备一般均未预装 GMS 服务。部分品牌的设备因无法获得授权，无法自行安装 GMS 服务。
  3. 应谷歌的合规性要求，国内手机厂商对 GMS 的使用作了更严格的限制。某些厂商把部分通过了谷歌认证的手机，禁止了 GMS 的使用，所以导致现在很多国内手机即便安装了 Google 服务框架，并开启了 VPN，依然无法收到 FCM 推送。

网络条件​

建议在模拟的海外网络环境下进行测试。详细条件如下：

  1. 如果在中国大陆地区进行测试，要求测试设备必须使用国外 IP 地址与融云建立 IM 连接，并使用海外 IP 访问融云服务。如果使用国内 IP，融云服务端认为该设备处于国内，且不会启用 FCM 通道。
  2. 测试设备所处的网络环境必须可以正常访问 Google 网络服务。否则即使触发 FCM 推送，该设备也无法从 Google 的 FCM 服务收取推送。

测试步骤​

假设在开发环境下进行测试。App 使用测试环境的 App Key。

具体步骤如下：

  1. APP 连接融云成功之后杀掉 APP 进程。
  2. 访问控制台的 IM Server API 调试页面，切换到 App 的开发环境，找到消息 > 消息服务 > 发送单聊消息，直接发送一条单聊消息内容。
  3. 查看手机是否收到本 APP 的推送。

故障排除​

  • 如果测试使用的 App 属于融云的海外数据中心（北美或新加坡），请检查是否已在 SDK 初始化之前执行 setServerInfo 设置海外数据中心的导航域名。详见海外数据中心。
  • 从 Google FCM 服务后台直接发送消息到设备。如果未收到，请先根据上述文档自查是否正确集成。
  • 检查 App 是否被设备为后台受限应用。在 Android P 或更高版本 上，FCM 将不会向被用户添加了后台限制（例如，通过设置 > 应用和通知 > [appname] > 电池实施后台限制）的应用发送推送通知。详见 Android 开发者文档 后台受限应用。
  • 不要频繁发同一内容的消息到同一台手机，有可能会被 FCM 服务端屏蔽导致无法收到推送。
  • 检查测试设备是否为国行手机的 ROM。部分品牌已不支持自行安装 GMS 服务。建议您替换为海外发售的设备，或更新测试设备的系统。

如果问题无法解决，可提交工单并提供您的消息 ID。

混淆脚本​

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

处理推送通知的点击事件​

  • 自定义推送通知点击事件：介绍如何实现 SDK 默认跳转行为，以及如何自定义处理点击事件。详见自定义推送通知点击事件。
  • 自定义推送通知样式：仅在控制台 FCM 的消息推送方式为透传消息方式时支持。详见自定义推送通知样式。

针对 CallKit SDK 客户的说明​

在控制台 FCM 的消息推送方式为透传消息方式时，IMKit/IMLib 默认不会为音视频信令消息（呼叫邀请、挂断等）弹出通知。可通过以下方式解决：

IM SDK 接收的 FCM 透传消息会拉起应用，可在 Application 的 onCreate 方法中即调用 IM 的连接方法。连接成功后 SDK 会主动弹出通知。

针对 CallLib SDK 客户的说明​

在控制台 FCM 的消息推送方式为透传消息方式时，IMKit/IMLib 默认不会为音视频信令（呼叫邀请、挂断等）弹出通知。您可以通过自定义推送通知样式，重写 PushEventListener 的 preNotificationMessageArrived 方法，在该方法自行实现通知弹出逻辑。

最后于 更新