开始使用 FCM 时,您可以构建一个最简单的应用场景:当应用在设备后台运行时,通过 Notifications Composer 向开发设备发送一条测试通知消息。 本页面列出了实现这一目标所需执行的,从设置到验证的所有步骤。如果您已针对 FCM 设置了 Android 客户端应用,那么您可能已经完成了本页面中的一些步骤。
设置 SDK
如果您已经为应用启用了其他 Firebase 功能,那么您可能已经完成了本部分将要介绍的一些任务。
准备工作
安装最新版本的 Android Studio,或将其更新为最新版本。
确保您的项目满足以下要求:
- 目标 API 级别为 19 (KitKat) 或更高
- 使用 Android 4.4 或更高版本
- 使用 Jetpack (AndroidX),这需要满足以下版本要求:
com.android.tools.build:gradle
3.2.1 或更高版本compileSdkVersion
28 或更高版本
设置一台实体设备或使用模拟器运行您的应用。
请注意,依赖于 Google Play 服务的 Firebase SDK 要求设备或模拟器上必须安装 Google Play 服务。使用您的 Google 帐号登录 Firebase。
如果您还没有 Android 项目,只是想试用某一 Firebase 产品,可以下载一个我们的快速入门示例。
创建 Firebase 项目
您必须先创建一个要关联到 Android 应用的 Firebase 项目,然后才能将 Firebase 添加到您的 Android 应用。如需详细了解 Firebase 项目,请访问了解 Firebase 项目。
在 Firebase 中注册您的应用
如需在 Android 应用中使用 Firebase,您需要在 Firebase 项目中注册您的应用。注册应用的过程通常称为将应用“添加”到项目中。
前往 Firebase 控制台。
在项目概览页面的中心位置,点击 Android 图标 (
) 或添加应用,启动设置工作流。在 Android 软件包名称字段中输入应用的软件包名称。
(可选)输入其他应用信息:应用别名和调试签名证书 SHA-1。
点击注册应用。
添加 Firebase 配置文件
下载 Firebase Android 配置文件 (
),然后将其添加到您的应用:google-services.json 点击下载 google-services.json 以获取 Firebase Android 配置文件。
将配置文件移到应用的模块(应用级)根目录中。
为了确保 Firebase SDK 可以访问
配置文件中的值,您需要具有 Google 服务 Gradle 插件 (google-services.json google-services
)。在您的根级(项目级)Gradle 文件 (
<project>/build.gradle
) 中,将 Google 服务插件添加为 buildscript 依赖项: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 文件(通常是
<project>/<app-module>/build.gradle
)中,添加 Google 服务插件:plugins { id 'com.android.application' // Add the Google services Gradle plugin id 'com.google.gms.google-services' ... }
将 Firebase SDK 添加至您的应用
在您的模块(应用级)Gradle 文件(通常是
<project>/<app-module>/build.gradle
)中,添加 Firebase Cloud Messaging Android 库的依赖项。我们建议使用 Firebase Android BoM 来实现库版本控制。为了获得最佳的 Firebase Cloud Messaging 使用体验,我们建议您在 Firebase 项目中启用 Google Analytics(分析),并将 Firebase SDK for Google Analytics 添加到您的应用中。
Java
dependencies { // Import the BoM for the Firebase platform implementation platform('com.google.firebase:firebase-bom:32.1.0') // Add 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' }
借助 Firebase Android BoM,可确保您的应用使用的始终是 Firebase Android 库的兼容版本。
(替代方法) 在不使用 BoM 的情况下添加 Firebase 库依赖项
如果您选择不使用 Firebase BoM,则必须在每个 Firebase 库的依赖项行中指定相应的库版本。
请注意,如果您在应用中使用多个 Firebase 库,我们强烈建议您使用 BoM 来管理库版本,从而确保所有版本都兼容。
dependencies { // Add the dependencies for the Firebase Cloud Messaging and Analytics libraries // When NOT using the BoM, you must specify versions in Firebase library dependencies implementation 'com.google.firebase:firebase-messaging:23.1.2' implementation 'com.google.firebase:firebase-analytics:21.3.0' }
Kotlin+KTX
dependencies { // Import the BoM for the Firebase platform implementation platform('com.google.firebase:firebase-bom:32.1.0') // Add 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-ktx' implementation 'com.google.firebase:firebase-analytics-ktx' }
借助 Firebase Android BoM,可确保您的应用使用的始终是 Firebase Android 库的兼容版本。
(替代方法) 在不使用 BoM 的情况下添加 Firebase 库依赖项
如果您选择不使用 Firebase BoM,则必须在每个 Firebase 库的依赖项行中指定相应的库版本。
请注意,如果您在应用中使用多个 Firebase 库,我们强烈建议您使用 BoM 来管理库版本,从而确保所有版本都兼容。
dependencies { // Add the dependencies for the Firebase Cloud Messaging and Analytics libraries // When NOT using the BoM, you must specify versions in Firebase library dependencies implementation 'com.google.firebase:firebase-messaging-ktx:23.1.2' implementation 'com.google.firebase:firebase-analytics-ktx:21.3.0' }
将您的 Android 项目与 Gradle 文件同步。
获取注册令牌
如需将消息发送到特定的设备,您需要知道该设备的注册令牌。您需要在 Notifications 控制台的相应字段中输入该令牌才能完成本教程,因此请确保在获得令牌后即复制该令牌或将其妥善存储。
初次启动您的应用时,FCM SDK 会为客户端应用实例生成一个注册令牌。如果您希望指定单一目标设备或者创建设备组,需要扩展 FirebaseMessagingService
并重写 onNewToken
来获取此令牌。
本部分介绍如何检索令牌以及如何监控令牌的变更。因为令牌可能会在初始启动后轮替,所以我们强烈建议您检索最近更新的注册令牌。
注册令牌可能会在发生下列情况时更改:
- 应用在新设备上恢复
- 用户卸载/重新安装应用
- 用户清除应用数据。
检索当前注册令牌
如果需要检索当前令牌,请调用 FirebaseMessaging.getInstance().getToken()
。
Kotlin+KTX
FirebaseMessaging.getInstance().token.addOnCompleteListener(OnCompleteListener { task -> if (!task.isSuccessful) { Log.w(TAG, "Fetching FCM registration token failed", task.exception) return@OnCompleteListener } // Get new FCM registration token val token = task.result // Log and toast val msg = getString(R.string.msg_token_fmt, token) Log.d(TAG, msg) Toast.makeText(baseContext, msg, Toast.LENGTH_SHORT).show() })
Java
FirebaseMessaging.getInstance().getToken() .addOnCompleteListener(new OnCompleteListener<String>() { @Override public void onComplete(@NonNull Task<String> task) { if (!task.isSuccessful()) { Log.w(TAG, "Fetching FCM registration token failed", task.getException()); return; } // Get new FCM registration token String token = task.getResult(); // Log and toast String msg = getString(R.string.msg_token_fmt, token); Log.d(TAG, msg); Toast.makeText(MainActivity.this, msg, Toast.LENGTH_SHORT).show(); } });
监控令牌的生成
每当生成新令牌时,都会触发 onNewToken
回调函数。
Kotlin+KTX
/** * Called if the FCM registration token is updated. This may occur if the security of * the previous token had been compromised. Note that this is called when the * FCM registration token is initially generated so this is where you would retrieve the token. */ override fun onNewToken(token: String) { Log.d(TAG, "Refreshed token: $token") // If you want to send messages to this application instance or // manage this apps subscriptions on the server side, send the // FCM registration token to your app server. sendRegistrationToServer(token) }
Java
/** * There are two scenarios when onNewToken is called: * 1) When a new token is generated on initial app startup * 2) Whenever an existing token is changed * Under #2, there are three scenarios when the existing token is changed: * A) App is restored to a new device * B) User uninstalls/reinstalls the app * C) User clears app data */ @Override public void onNewToken(@NonNull String token) { Log.d(TAG, "Refreshed token: " + token); // If you want to send messages to this application instance or // manage this apps subscriptions on the server side, send the // FCM registration token to your app server. sendRegistrationToServer(token); }
获取令牌后,可以将其发送到您的应用服务器,并使用您首选的方法进行存储。
发送测试通知消息
在目标设备上安装并运行该应用。在 Apple 设备上,您需要接受权限请求,才能收到远程通知。
确保应用在设备的后台运行。
在 Firebase 控制台中,打开“Messaging”(消息功能)页面。
如果这是您的第一条消息,请选择制作首个宣传活动。
- 选择 Firebase 通知消息,然后选择创建。
否则,请在宣传活动标签页上选择新建宣传活动,然后选择通知。
输入消息内容。所有其他字段都是选填字段。
从右侧窗格中选择发送测试消息。
在标签为添加 FCM 注册令牌的字段中,输入您根据本指南的前一部分获得的注册令牌。
选择测试。
在您选择测试后,目标客户端设备(在后台中运行应用)应该会接收到通知。
如需详细了解发送到应用的消息,请参阅 FCM 报告信息中心。该信息中心会记录在 Apple 和 Android 设备上发送和打开的消息数量,以及 Android 应用的“展示次数”(用户看到的通知条数)数据。
后续步骤
向前台应用发送消息
您在应用处于后台运行的情况下成功发送通知消息后,可参阅在 Android 应用中接收消息,尝试向前台应用发送消息。
除通知消息之外的其他功能
除了通知消息之外,如果您还要为应用添加其他更高级的行为,可参阅以下内容: