要开始使用 FCM,请构建最简单的用例:当应用程序在设备后台运行时,将测试通知消息从通知编辑器发送到开发设备。此页面列出了实现此目的的所有步骤,从设置到验证——如果您已经为 FCM设置了 Android 客户端应用程序,它可能涵盖您已经完成的步骤。
设置开发工具包
如果您已经为您的应用启用了其他 Firebase 功能,本部分涵盖您可能已经完成的任务。
在你开始之前
安装或更新Android Studio到其最新版本。
确保您的项目满足以下要求:
- 目标 API 级别 19 (KitKat) 或更高级别
- 使用 Android 4.4 或更高版本
- 使用Jetpack (AndroidX) ,其中包括满足以下版本要求:
-
com.android.tools.build:gradle
v3.2.1 或更高版本 compileSdkVersion
28 或更高版本
-
设置物理设备或使用模拟器来运行您的应用程序。
请注意,依赖于 Google Play 服务的 Firebase SDK要求设备或模拟器安装 Google Play 服务。使用您的 Google 帐户登录 Firebase 。
如果您还没有 Android 项目并且只想试用 Firebase 产品,您可以下载我们的快速入门示例之一。
创建一个 Firebase 项目
在将 Firebase 添加到您的 Android 应用程序之前,您需要创建一个 Firebase 项目以连接到您的 Android 应用程序。访问了解 Firebase 项目以了解有关 Firebase 项目的更多信息。
向 Firebase 注册您的应用
要在您的 Android 应用程序中使用 Firebase,您需要向您的 Firebase 项目注册您的应用程序。注册您的应用程序通常称为将您的应用程序“添加”到您的项目中。
转到Firebase 控制台。
在项目概览页面的中央,单击Android图标 (
) 或添加应用程序以启动设置工作流程。在Android 程序包名称字段中输入您的应用程序的程序包名称。
包名称在设备和 Google Play 商店中唯一标识您的应用程序。
包名称通常称为应用程序 ID 。
在模块(应用程序级)Gradle 文件中找到应用程序的包名称,通常是
app/build.gradle
(例如包名称:com.yourcompany.yourproject
)。请注意,包名称值区分大小写,并且在您的 Firebase 项目中注册后,无法更改此 Firebase Android 应用程序。
(可选)输入其他应用信息:应用昵称和调试签名证书 SHA-1 。
应用昵称:仅在 Firebase 控制台中对您可见的内部便利标识符
调试签名证书 SHA-1 :Firebase 身份验证(使用Google 登录或电话号码登录时)和Firebase 动态链接需要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
) 中,将 Google 服务插件添加为构建脚本依赖项: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 云消息传递的最佳体验,我们建议在您的 Firebase 项目中启用 Google Analytics ,并将适用于 Google Analytics 的 Firebase SDK 添加到您的应用程序中。
Java
dependencies { // Import the BoM for the Firebase platform implementation platform('com.google.firebase:firebase-bom:31.2.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.1' implementation 'com.google.firebase:firebase-analytics:21.2.0' }
Kotlin+KTX
dependencies { // Import the BoM for the Firebase platform implementation platform('com.google.firebase:firebase-bom:31.2.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.1' implementation 'com.google.firebase:firebase-analytics-ktx:21.2.0' }
将您的 Android 项目与 Gradle 文件同步。
使用 Android Gradle 插件 (AGP) v4.2 或更早版本的 Gradle 构建需要启用 Java 8 支持。否则,这些 Android 项目在添加 Firebase SDK 时会出现构建失败。
要修复此构建失败,您可以遵循以下两个选项之一:
- 将错误消息中列出的
compileOptions
添加到您的应用程序级build.gradle
文件中。 - 将 Android 项目的
minSdkVersion
增加到 26 或更高。
在此常见问题解答中了解有关此构建失败的更多信息。
- 将错误消息中列出的
访问注册令牌
要向特定设备发送消息,您需要知道该设备的注册令牌。由于您需要在通知控制台的字段中输入令牌才能完成本教程,因此请务必复制令牌或在检索后安全地存储它。
在您的应用程序初始启动时,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 控制台中,打开消息页面。
如果这是您的第一条消息,请选择创建您的第一个营销活动。
- 选择Firebase Notification messages并选择Create 。
否则,在“活动”选项卡上,选择“新建活动” ,然后选择“通知”。
输入消息文本。所有其他字段都是可选的。
从右窗格中选择发送测试消息。
在标记为添加 FCM 注册令牌的字段中,输入您在本指南上一节中获得的注册令牌。
选择测试。
选择测试后,目标客户端设备(应用程序在后台)应该会收到通知。
要深入了解向您的应用程序发送的消息,请参阅FCM 报告仪表板,它记录了在 Apple 和 Android 设备上发送和打开的消息数量,以及 Android 应用程序的“印象”(用户看到的通知)数据。
下一步
向前台应用程序发送消息
在应用程序处于后台时成功发送通知消息后,请参阅在 Android 应用程序中接收消息以开始向前台应用程序发送消息。
超越通知消息
要超越通知消息并向您的应用程序添加其他更高级的行为,请参阅: