向后台应用发送测试消息

开始使用 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 中注册您的应用

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

  1. 前往 Firebase 控制台。

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

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

  4. （可选）输入其他应用信息：应用别名和调试签名证书 SHA-1。

  5. 点击注册应用。

添加 Firebase 配置文件

  1. 下载 Firebase Android 配置文件 (google-services.json)，然后将其添加到您的应用：

    1. 点击下载 google-services.json 以获取 Firebase Android 配置文件。

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

  2. 为了确保 Firebase SDK 可以访问 google-services.json 配置文件中的值，您需要具有 Google 服务 Gradle 插件 (google-services)。

    1. 在您的根级（项目级）Gradle 文件（<project>/build.gradle.kts 或 <project>/build.gradle）中，将 Google 服务插件添加为依赖项：

      Kotlin 

      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
}

      Groovy 

      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
}

    2. 在您的模块（应用级）Gradle 文件（通常是 <project>/<app-module>/build.gradle.kts 或 <project>/<app-module>/build.gradle）中，添加 Google 服务插件：

      Kotlin 

      plugins {
  id("com.android.application")

  // Add the Google services Gradle plugin
  id("com.google.gms.google-services")
  // ...
}

      Groovy 

      plugins {
  id 'com.android.application'

  // Add the Google services Gradle plugin
  id 'com.google.gms.google-services'
  // ...
}

将 Firebase SDK 添加至您的应用

  1. 在模块（应用级）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.6.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:24.1.0")
    implementation("com.google.firebase:firebase-analytics:22.1.2")
}
    是否想要查找 Kotlin 专用的库模块？从 2023 年 10 月 (Firebase BoM 32.5.0) 开始，Kotlin 和 Java 开发者可以依赖于主库模块（如需了解详情，请参阅关于此计划的常见问题解答）。

  2. 将您的 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)
}
MyFirebaseMessagingService.kt

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);
}
MyFirebaseMessagingService.java

获取令牌后，可以将其发送到您的应用服务器，并使用您首选的方法进行存储。

发送测试通知消息

  1. 在目标设备上安装并运行该应用。在 Apple 设备上，您需要接受权限请求，才能收到远程通知。

  2. 确保应用在设备的后台中运行。

  3. 在 Firebase 控制台中，打开“Messaging”（消息传递）页面。

  4. 如果这是您的第一条消息，请选择制作首个宣传活动。

    1. 选择 Firebase 通知消息，然后选择创建。

  5. 否则，请在宣传活动标签页上选择新建宣传活动，然后选择通知。

  6. 输入消息内容。所有其他字段都是选填字段。

  7. 从右侧窗格中选择发送测试消息。

  8. 在标签为添加 FCM 注册令牌的字段中，输入您根据本指南的前一部分获得的注册令牌。

  9. 选择测试。

在您选择测试后，目标客户端设备（在后台中运行应用）应该会接收到通知。

如需详细了解发送到您应用的消息，请参阅 FCM 报告信息中心。该信息中心会记录在 Apple 和 Android 设备上发送和打开的消息数量，以及 Android 应用的“展示次数”（用户看到的通知条数）数据。

后续步骤

向前台应用发送消息

您在应用处于后台运行的情况下成功发送通知消息后，可参阅在 Android 应用中接收消息，尝试向前台应用发送消息。

除通知消息之外的其他功能

除了通知消息之外，如果您还要为应用添加其他更高级的行为，可参阅以下内容：