开始使用 FCM 时,您可以构建一个最简单的用例:当应用在设备后台运行时,通过 Notifications Composer 向开发设备发送一条测试通知消息。本页面列出了实现上述目标所需执行的步骤,包括从设置到验证的所有步骤。如果您已针对 FCM 设置了 Android 客户端应用,您可能已经完成了本页面中的一些步骤。
设置 SDK
如果您已经为应用启用了其他 Firebase 功能,那么您可能已经完成了本部分将要介绍的一些任务。
准备工作
安装最新版本的 Android Studio,或更新为最新版本。
请确保您的项目满足以下要求(请注意,某些产品可能具有更严格的要求):
- 目标 API 级别为 21 (Lollipop) 或更高
- 使用 Android 5.0 或更高版本
- 使用 Jetpack (AndroidX),同时需要满足以下版本要求:
com.android.tools.build:gradle
v7.3.0 或更高版本compileSdkVersion
28 或更高版本
设置一台实体设备或使用模拟器运行您的应用。
请注意,依赖于 Google Play 服务的 Firebase SDK 要求设备或模拟器上必须安装 Google Play 服务。使用您的 Google 账号登录 Firebase。
如果您还没有 Android 项目,只是想试用某一 Firebase 产品,可以下载一个我们的快速入门示例。
创建 Firebase 项目
您必须先创建一个要关联到 Android 应用的 Firebase 项目,然后才能将 Firebase 添加到您的 Android 应用。如需详细了解 Firebase 项目,请访问了解 Firebase 项目。
创建 Firebase 项目
-
在 Firebase 控制台中,点击添加项目。
-
如需将 Firebase 资源添加到现有 Google Cloud 项目,请输入该项目的名称或从下拉菜单中选择该项目。
-
如需创建新项目,请输入要使用的项目名称。您也可以视需要修改项目名称下方显示的项目 ID。
-
-
如果看到相关提示,请查看并接受 Firebase 条款。
-
点击继续。
-
(可选)为您的项目设置 Google Analytics,以便在使用下列 Firebase 产品时能获得最佳体验:
选择现有的 Google Analytics 账号,或者创建一个新账号。
如果您选择创建一个新账号,请选择 Analytics 报告位置,然后接受项目的数据共享设置和 Google Analytics 条款。
-
点击创建项目(或者,如果您使用的是现有 Google Cloud 项目,则点击添加 Firebase)。
Firebase 会自动为您的 Firebase 项目预配资源。完成此过程后,您将进入 Firebase 控制台中该 Firebase 项目的概览页面。
在 Firebase 中注册您的应用
如需在 Android 应用中使用 Firebase,您需要在 Firebase 项目中注册您的应用。注册应用的过程通常称为将应用“添加”到项目中。
前往 Firebase 控制台。
在项目概览页面的中心位置,点击 Android 图标 (
) 或添加应用,启动设置工作流。在 Android 软件包名称字段中输入应用的软件包名称。
软件包名称是什么?在哪里可以找到它?
软件包名称是您的应用在设备上和 Google Play 商店中的唯一标识符。
软件包名称通常称为应用 ID。
在模块(应用级)Gradle 文件(通常是
app/build.gradle
)中查找应用的软件包名称(示例软件包名称:com.yourcompany.yourproject
)。请注意,软件包名称值区分大小写,并且当您在 Firebase 项目中注册此 Firebase Android 应用后,将无法更改其软件包名称。
(可选)输入其他应用信息:应用别名和调试签名证书 SHA-1。
应用别名和调试签名证书 SHA-1 在 Firebase 中的作用是什么?
应用别名:方便内部使用的标识符,只有您能在 Firebase 控制台中看到
调试签名证书 SHA-1:Firebase Authentication(使用 Google 登录或电话号码登录时)和 Firebase Dynamic Links 需要 SHA-1 哈希。
点击注册应用。
添加 Firebase 配置文件
下载 Firebase Android 配置文件 (
),然后将其添加到您的应用:google-services.json 点击下载 google-services.json 以获取 Firebase Android 配置文件。
将配置文件移到应用的模块(应用级)根目录中。
关于此配置文件,您需要了解哪些信息?
此 Firebase 配置文件包含项目的唯一但非机密的标识符。如需详细了解此配置文件,请访问了解 Firebase 项目。
您可以随时再次下载 Firebase 配置文件。
请确保该配置文件名未附加其他字符,如
(2)
。
为了确保 Firebase SDK 可以访问
配置文件中的值,您需要具有 Google 服务 Gradle 插件 (google-services.json google-services
)。在您的根级(项目级)Gradle 文件(
<project>/build.gradle.kts
或<project>/build.gradle
)中,将 Google 服务插件添加为依赖项:plugins { id("com.android.application") version "7.3.0" apply false // ... // Add the dependency for the Google services Gradle plugin id("com.google.gms.google-services") version "4.4.2" apply false }
plugins { id 'com.android.application' version '7.3.0' apply false // ... // Add the dependency for the Google services Gradle plugin id 'com.google.gms.google-services' version '4.4.2' apply false }
在您的模块(应用级)Gradle 文件(通常是
<project>/<app-module>/build.gradle.kts
或<project>/<app-module>/build.gradle
)中,添加 Google 服务插件:plugins { id("com.android.application") // Add the Google services Gradle plugin id("com.google.gms.google-services") // ... }
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.kts
或<project>/<app-module>/build.gradle
)中,添加 Firebase Cloud Messaging 库的依赖项。我们建议使用 Firebase Android BoM 来实现库版本控制。为了获得最佳的 Firebase Cloud Messaging 使用体验,我们建议您在 Firebase 项目中启用 Google Analytics,并将 Firebase SDK for Google Analytics 添加到您的应用中。
dependencies { // Import the BoM for the Firebase platform implementation(platform("com.google.firebase:firebase-bom:33.7.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 库的兼容版本。
是否想要查找 Kotlin 专用的库模块? 从 2023 年 10 月 (Firebase BoM 32.5.0) 开始,Kotlin 和 Java 开发者可以依赖于主库模块(如需了解详情,请参阅关于此计划的常见问题解答)。(替代方法) 在不使用 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:24.1.0") implementation("com.google.firebase:firebase-analytics:22.1.2") }
将您的 Android 项目与 Gradle 文件同步。
您是否收到了关于调用自定义 (invoke-custom) 支持和启用脱糖 (desugaring) 的构建失败消息?解决方法如下。
使用 Android Gradle 插件 (AGP) 4.2 或更早版本的 Gradle build 需要启用 Java 8 支持。否则,这些 Android 项目在添加 Firebase SDK 时会遇到构建失败问题。
为解决此构建失败问题,您可以采用以下两种方案中的一种:
- 将错误消息中列出的
compileOptions
添加到您的应用级build.gradle.kts
或build.gradle
文件中。 - 将 Android 项目的
minSdk
提升到 26 或更高。
如需详细了解此构建失败问题,请参阅此常见问题解答。
- 将错误消息中列出的
获取注册令牌
如需将消息发送到特定的设备,您需要知道该设备的注册令牌。您需要在 Notifications 控制台的相应字段中输入该令牌才能完成本教程,因此请确保在获得令牌后即复制该令牌或将其妥善存储。
初次启动您的应用时,FCM SDK 会为客户端应用实例生成一个注册令牌。如果您希望指定单一目标设备或者创建设备组,需要扩展 FirebaseMessagingService
并重写 onNewToken
来获取此令牌。
本部分介绍如何检索令牌以及如何监控令牌的变更。因为令牌可能会在初始启动后轮替,所以我们强烈建议您检索最近更新的注册令牌。
注册令牌可能会在发生下列情况时更改:
- 应用在新设备上恢复
- 用户卸载/重新安装应用
- 用户清除应用数据。
检索当前注册令牌
如果需要检索当前令牌,请调用 FirebaseMessaging.getInstance().getToken()
。
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() })
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
回调函数。
/** * 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) }
/** * 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 应用中接收消息,尝试向前台应用发送消息。
除通知消息之外的其他功能
除了通知消息之外,如果您还要为应用添加其他更高级的行为,可参阅以下内容: