集成 FCM 推送
- FCM 推送通道适用于海外正式发售的 Android 设备(内置 Google GMS 服务),且会在海外网络环境下启用。
- 建议您在集成后根据测试 FCM 推送 中描述的条件与步骤进行测试。
融云服务端已集成与 FCM 后端通信的功能组件。在消息接收者设备上运行的 App 被杀进程,或者在后台被挂起,或者在后台存活超过 2 分钟的情况下,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 项目
-
在Firebase 控制台中,点击添加项目。
- 如需创建新项目,请输入要使用的项目名称。您也可以视需要修改项目名称下方显示的项目 ID。
- 如需将 Firebase 资源添加到现有 Google Cloud 项目,请输入该项目的名称或从下拉菜单中选择该项目。
-
点击继续。最后,点击创建项目(如果使用现有的 Google Cloud 项目,则点击添加 Firebase)。
Firebase 会自动为您的 Firebase 项 目预配资源。完成此过程后,您将进入 Firebase 控制台中 Firebase 项目的概览页面。
Firebase 项目实际上只是一个启用了额外的 Firebase 特定配置和服务的 Google Cloud 项目。在创建新的 Firebase 项目时,您实际上是在幕后创建 Google Cloud 项目。详情可参考 Firebase 中文文档 Firebase 项目与 Google Cloud 之间的关系。
第 2 步:在 Firebase 中注册您的 Android 应用
如需在 Android 应用中使用 Firebase,您需要向 Firebase 项目注册您的应用。注册应用的过程通常称为将应用“添加”到项目中。
-
前往 Firebase 控制台。
-
在项目概览页面的中心位置,点击 Android 图标或添加应用,启动设置工作流。
-
在 Android 软件包名称字段中输入应用的软件包名称。
- 软件包名称是您的应用在设备上和 Google Play 商店中的唯一标识符。
- 软件包名称通常称为应用 ID。
- 在模块(应用级)Gradle 文件(通常是 app/build.gradle)中查找应用的软件包名称(示例软件包名称:com.yourcompany.yourproject)。
- 请注意,软件包名称值区分大小写,并且当您在 Firebase 项目中注册此 Firebase Android 应用后,将无法更改其软件包名称。
-
如有需要,可完成其他可选配置。然后点击注册应用。
第 3 步:在 Android Studio 项目中添加 Firebase 配置文件
本步骤描述如何将 Firebase Android 配置文件添加到您的应用。
-
注册应用后,点击下载 google-services.json 以获取 Firebase Android 配置文件 (
google-services.json
)。 -
将配置文件移到应用的模块(应用级)目录中。
- 如需详细了解此配置文件,请访问了解 Firebase 项目。
- 您可以随时再次下载 Firebase 配置文件。
- 请确保该配置文件名未附加其他字符,如 (2)。
-
如需在应用中启用 Firebase 产品,请将
google-services
插件添加到 Gradle 文件中。注意,所有 Firebase SDK 都使用 google-services Gradle 插件(
google-services
),但该插件与 Google Play 服务没有任何关系)。-
方法 1:使用 Gradle 的
buildscript
块添加插件。Google 文档 与 Firebase 中文文档 均使用该方法。-
修改根级(项目级)Gradle 文件 (
build.gradle
) ,在 buildscript 块中添加规则,以导入 Google 服务 Gradle 插件。请确认您添加了 Google 的 Maven 代码库。Groovybuildscript {
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
// ...
}
} -
在您的模块(应用级)Gradle 文件(通常是
app/build.gradle
)中,应用 Google 服务 Gradle 插件:Groovyapply 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 语法,且已在项目中使用,可使用该方法。
-
默认情况下 plugins DSL 仅支持已发布在 Gradle Plugin Portal 的核心插件。因为
google-services
插件不在该仓库中,所以您需要先添加 Google 的插件仓库地址。在根级(项目级)Gradle 设置文件 (
settings.gradle
) 中声明 Google 的 Maven 代码库。GroovypluginManagement {
// (可选)在声明仓库时即可引入 google-services plugin 并声明版本
//plugins {
// id 'com.google.gms.google-services' version '4.3.13'
//}
repositories {
google()
gradlePluginPortal()
}
}
rootProject.name='exampleProject'
include ':app' -
在您的模块(应用级)Gradle 文件(通常是
app/build.gradle
)中,应用 Google 服务 Gradle 插件google-services
插件,并声明版本:Groovyplugins {
id 'com.google.gms.google-services' version '4.3.13'
}注意:如果在
settings.gradle
的pluginManagement {}
块中已使用 plugins DSL 引入了google-services
插件,并且声明了版本,则可直接在模块(应用级)app/build.gradle
文件中应用插件,无需再声明版本:Groovyplugins {
id 'com.google.gms.google-services'
}
-
-
第 4 步:将 Firebase SDK 添加到您的 Android 应用
-
在模块(应用级)Gradle 文件(通常为
app/build.gradle
)中声明依赖项。-
如果您使用 Gradle 5.0+,推荐配合使用 Firebase Android BoM 声明您要在应用中使用的 Firebase 产品(可用的库)的依赖项(此处为
firebase-messaging
)。Groovydependencies {
// ...
// 导入 Firebase BoM。后续声明 Firebase 库依赖项时,您无需指定具体的库版本。
implementation platform('com.google.firebase:firebase-bom:30.1.0')
// firebase-messaging
implementation 'com.google.firebase:firebase-messaging'
// 根据自身需求,导入 其他 Firebase 产品
// implementation 'com.google.firebase:firebase-auth'
// implementation 'com.google.firebase:firebase-firestore'
// Google Play Service
implementation 'com.google.android.gms:play-services-gcm:17.0.0'
}使用 Firebase Android BoM 可确保您的应用使用的多个 Firebase 产品的 Android 库之间始终保持兼容。注意,BOM 仅管理 Firebase 库版本之间的兼容关系,不会将任何 Firebase 库自动添加到您的应用。如需添加库,请为其添加单独的依赖项行。
-
如果不想使用 Firebase Android BoM,您可以直接指定依赖项,并声明依赖项版本。
Groovydependencies {
// firebase-messaging
implementation 'com.google.firebase:firebase-messaging:22.0.0'
// Google Play Service
implementation 'com.google.android.gms:play-services-gcm:17.0.0'
}
提示为什么 firebase-messaging 需要 Google Play 服务?
- 详见 Firebase 中文文档 Firebase Android SDK 对 Google Play 服务的依赖。
- 您可以自行确定所需要的 Google Play 服务的版本。
-
-
同步您的应用以确保所有依赖项都具有所需的版本。
第 5 步:修改 Android 的应用清单(AndroidManifest.xml)
在主工程中的 AndroidManifest.xml
文件下增加如下两段配置:
-
阻止 FCM 自动初始化。
xml<meta-data
android:name="firebase_messaging_auto_init_enabled"
android:value="false" />
<meta-data
android:name="firebase_analytics_collection_enabled"
android:value="false" /> -
扩展 FirebaseMessagingService 的服务。除了接收通知外,如果您还希望在后台应用中进行消息处理,则必须添加此服务。如需在前台应用中接收通知、接收数据载荷以及发送上行消息等,您必须添加此扩展服务。
xml<service
android:name="io.rong.push.platform.google.RongFirebaseMessagingService"
android:stopWithTask="false"
android:exported="false">
<intent-filter>
<action android:name="com.google.firebase.MESSAGING_EVENT"/>
</intent-filter>
</service>
如需了解更多细节,可参考 Firebase 中文文档 设置 Firebase Cloud Messaging 客户端应用 (Android)。
至此,您已经成功将 Firebase 集成到 Android 项目中。
请继续完成后续步骤,在控制台授权 FCM 请求。
在控制台授权 FCM 请求
从融云发送到 FCM 的请求必须经过授权。因此,您需要向融云提供 FCM 项目相关的服务账号授权凭证。您需要手动将该凭证上传到控制台。
第 1 步:获取 Google 服务账号凭证
Firebase 项目支持 Google 服务帐号。您需要从您的 Google 服务帐号获取凭据,然后授权融云服务器这些帐号凭据调用 Firebase 服务器 API。
如需对服务帐号进行身份验证并授予其访问 Firebase 服务的权限,您必须生成 JSON 格式的私钥文件。如需为您的服务帐号生成 JSON 格式的私钥文件,请执行以下操作:
- 在 Firebase 控制台中,打开设置 > 服务帐号。
- 点击生成新的私钥,然后点击生成密钥进行确认。
- 妥善存储包含密钥的 JSON 文件。稍后需要在融云控制台上传该文件。
第 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 消息类型):
- 透传消息方式:由 Android OS 直接在通知面板弹出通知。融云仅下发对应 FCM「数据消息」类型的数据。
- 通知消息方式:IMLib SDK 接收到透传数据后,进行数据解析并弹出通知。开发者也可以自定义处理。融云下发包含 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 推送服务
-
在 SDK init 之前,配置使用 FCM 推送。
JavaPushConfig config = new PushConfig.Builder()
.enableFCM(true)
.build();
RongPushClient.setPushConfig(config); -
(可选)启用 FCM 推送后,如需重新启用 Analytics 数据收集,请调用
FirebaseAnalytics
类的setAnalyticsCollectionEnabled()
方法。例如:JavasetAnalyticsCollectionEnabled(true);
如果不需要接收推送,可以通过设置 SDK 的初始化配置中的 enablePush
参数为 false
,向融云服务申请禁用推送服务(当前设备)。您 也可以在断开连接时设置不接收推送(当前设备)。
测试 FCM 推送
在完成上述步骤之后,可直接测试推送是否集成成功。
设备条件
建议直接使用在海外正式发售的 Android 设备测试 FCM 推送通知的接收。针对测试设备的详细要求如下:
- 测试设备必须使用真机。模拟器收不到远程推送。
- 测试设备必须支持 Google GMS 服务(Google Mobile Services)。您可以直接使用在海外正式发售的 Android 设备。注意,在中国大陆地区发售的设备一般均未预装 GMS 服务。部分品牌的设备因无法获得授权,无法自行安装 GMS 服务。