向后台应用发送测试消息

开始使用 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 项目中注册您的应用。注册应用的过程通常称为将应用“添加”到项目中。

  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) 中,将 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
        }
      }
    2. 在您的模块(应用级)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 添加至您的应用

  1. 在您的模块(应用级)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'
    }

  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)
}

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);
}

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

发送测试通知消息

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

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

  3. 在 Firebase 控制台中,打开“Messaging”(消息功能)页面

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

    1. 选择 Firebase 通知消息,然后选择创建
  5. 否则,请在宣传活动标签页上选择新建宣传活动,然后选择通知

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

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

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

  9. 选择测试

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

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

后续步骤

向前台应用发送消息

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

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

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