Google 致力于为黑人社区推动种族平等。查看具体举措

在 Android 上设置 Firebase Cloud Messaging 客户端应用

如需编写 Android 版 Firebase Cloud Messaging 客户端应用,请将 FirebaseMessaging API 和 Android Studio 1.4 或更高版本与 Gradle 结合使用。本文中的说明假定您已完成将 Firebase 添加至您的 Android 项目中的步骤。

FCM 客户端需要在 Android 4.1 或更高版本且安装了 Google Play 商店应用的设备上运行,或者在 Android 4.1 版本且支持 Google API 的模拟器中运行。请注意,除了使用 Google Play 商店,您还可以通过其他方式部署您的 Android 应用。

设置 SDK

如果您的应用已经启用了其他 Firebase 功能,那么您可能已经完成了本部分将要介绍的一些任务。

准备工作

  • 安装最新版本的 Android Studio,或将其更新为最新版本。

  • 确保您的项目满足以下要求:

    • 目标 API 级别为 16 (Jelly Bean) 或更高
    • 使用 Gradle 4.1 或更高版本
    • 使用 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 中注册您的应用

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

  1. 转到 Firebase 控制台

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

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

  4. (可选)输入其他应用信息:应用别名调试签名证书 SHA-1

  5. 点击注册应用

添加 Firebase 配置文件

  1. 将 Firebase Android 配置文件添加到您的应用:

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

    2. 将配置文件移动到应用的模块(应用级)目录中。

  2. 如需在应用中启用 Firebase 产品,请将 Google 服务插件添加到 Gradle 文件中。

    1. 在根级(项目级)Gradle 文件 (build.gradle) 中添加规则,以纳入 Google 服务 Gradle 插件。此外,请确认您拥有 Google 的 Maven 代码库。

      buildscript {
      
        repositories {
          // Check that you have the following line (if not, add it):
          google()  // Google's Maven repository
        }
      
        dependencies {
          // ...
      
          // Add the following line:
          classpath 'com.google.gms:google-services:4.3.8'  // Google Services plugin
        }
      }
      
      allprojects {
        // ...
      
        repositories {
          // Check that you have the following line (if not, add it):
          google()  // Google's Maven repository
          // ...
        }
      }
      
    2. 在您的模块(应用级)Gradle 文件(通常是 app/build.gradle)中,应用 Google 服务 Gradle 插件:

      apply plugin: 'com.android.application'
      // Add the following line:
      apply plugin: 'com.google.gms.google-services'  // Google Services plugin
      
      android {
        // ...
      }
      

将 Firebase SDK 添加至您的应用

  1. 使用 Firebase Android BoM模块(应用级)Gradle 文件(通常为 app/build.gradle)中声明 Firebase Cloud Messaging Android 库的依赖项。

    为了获得最佳的 Firebase Cloud Messaging 使用体验,我们建议您在 Firebase 项目中启用 Google Analytics(分析),并将适用于 Google Analytics(分析)的 Firebase SDK 添加到您的应用中。

    Java

    dependencies {
        // Import the BoM for the Firebase platform
        implementation platform('com.google.firebase:firebase-bom:28.0.1')
    
        // Declare 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 {
        // Declare 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:22.0.0'
        implementation 'com.google.firebase:firebase-analytics:19.0.0'
    }
    

    Kotlin+KTX

    dependencies {
        // Import the BoM for the Firebase platform
        implementation platform('com.google.firebase:firebase-bom:28.0.1')
    
        // Declare 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 {
        // Declare 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:22.0.0'
        implementation 'com.google.firebase:firebase-analytics-ktx:19.0.0'
    }
    

  2. 同步您的应用以确保所有依赖项都具有所需的版本。

修改您的应用清单

将以下内容添加至您的应用的清单中:

  • 一项继承 FirebaseMessagingService 的服务。在后台应用中,如果除了接收通知外,您还希望进行任何消息处理,则必须添加此服务。如需在前台应用中接收通知、接收数据载荷以及发送上行消息等,您必须继承此服务。
  • <service
        android:name=".java.MyFirebaseMessagingService"
        android:exported="false">
        <intent-filter>
            <action android:name="com.google.firebase.MESSAGING_EVENT" />
        </intent-filter>
    </service>
  • (可选)应用组件中用于设置默认通知图标和颜色的元数据元素。如果传入的消息未明确设置图标和颜色,Android 就会使用这些值。
  • <!-- Set custom default icon. This is used when no icon is set for incoming notification messages.
         See README(https://goo.gl/l4GJaQ) for more. -->
    <meta-data
        android:name="com.google.firebase.messaging.default_notification_icon"
        android:resource="@drawable/ic_stat_ic_notification" />
    <!-- Set color used with incoming notification messages. This is used when no color is set for the incoming
         notification message. See README(https://goo.gl/6BKBk7) for more. -->
    <meta-data
        android:name="com.google.firebase.messaging.default_notification_color"
        android:resource="@color/colorAccent" />
  • (可选)从 Android 8.0(API 级别 26)和更高版本开始,我们支持并推荐使用通知渠道。FCM 提供具有基本设置的默认通知渠道。如果您希望创建和使用自己的默认渠道,请将 default_notification_channel_id 设置为您的通知渠道对象的 ID(如下所示);只要传入的消息未明确设置通知渠道,FCM 就会使用此值。如需了解详情,请参阅管理通知渠道
  • <meta-data
        android:name="com.google.firebase.messaging.default_notification_channel_id"
        android:value="@string/default_notification_channel_id" />

获取设备注册令牌

初次启动您的应用时,FCM SDK 会为客户端应用实例生成一个注册令牌。如果您希望指定单一目标设备或者创建设备组,则需要通过扩展 FirebaseMessagingService 并重写 onNewToken 来获取此令牌。

本部分介绍如何检索令牌以及如何监控令牌的变更。因为令牌会在初始启动后轮替,所以我们强烈建议您检索最近更新的注册令牌。

注册令牌可能会在发生下列情况时更改:

  • 应用在新设备上恢复
  • 用户卸载/重新安装应用
  • 用户清除应用数据。

检索当前注册令牌

如果需要检索当前令牌,请调用 FirebaseMessaging.getInstance().getToken()

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

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

监控令牌的生成

每当生成新令牌时,都会触发 onNewToken 回调函数。

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

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

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

检查 Google Play 服务

依靠 Play 服务 SDK 运行的应用在访问 Google Play 服务功能之前,应始终检查设备是否拥有兼容的 Google Play 服务 APK。我们建议您在以下两个位置进行检查:主 Activity 的 onCreate() 方法和 onResume() 方法。onCreate() 中的检查可确保该应用在检查成功之前无法使用。onResume() 中的检查可确保当用户通过一些其他方式返回正在运行的应用(比如通过返回按钮)时,检查仍将继续进行。

如果设备没有兼容的 Google Play 服务版本,您的应用可以调用 GoogleApiAvailability.makeGooglePlayServicesAvailable(),以便用户从 Play 商店下载 Google Play 服务。

防止自动初始化

在生成 FCM 注册令牌后,库会将标识符和配置数据上传到 Firebase。如果您希望阻止自动生成令牌,请通过将以下元数据值添加到 AndroidManifest.xml 来停用 Analytics 数据收集和 FCM 自动初始化功能(您必须同时停用这两项功能):

<meta-data
    android:name="firebase_messaging_auto_init_enabled"
    android:value="false" />
<meta-data
    android:name="firebase_analytics_collection_enabled"
    android:value="false" />

要重新启用 FCM 自动初始化功能,请执行运行时调用:

Java

FirebaseMessaging.getInstance().setAutoInitEnabled(true);

Kotlin+KTX

Firebase.messaging.isAutoInitEnabled = true

要重新启用 Analytics 数据收集,请调用 FirebaseAnalytics 类的 setAnalyticsCollectionEnabled() 方法。例如:

setAnalyticsCollectionEnabled(true);

这些值一经设置,即使应用重启也将持续生效。

后续步骤

客户端应用设置完成后,您就可以使用 Notifications Composer 开始发送下行消息。我们在可供您下载、运行和查看的快速入门示例中演示了此功能。

如需向您的应用添加其他更高级的行为,您可以声明 Intent 过滤器并实现 Activity 以响应传入的消息。如需了解详情,请参阅有关从应用服务器发送消息的指南:

请注意,如需利用这些功能,您需要完成服务器实现和使用服务器协议(HTTP 或 XMPP),或者实现 Admin SDK