在 Android 上设置 Firebase 云消息传递客户端应用

如需编写 Android 版 Firebase 云消息传递客户端应用,请将 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 的模拟器映像。

  • 使用您的 Google 帐号登录 Firebase

如果您还没有 Android 项目,只是想试用某一 Firebase 产品,则可以下载我们的快速入门示例

创建 Firebase 项目

您必须先创建一个 Firebase 项目,并将其关联到您的 Android 应用,然后才能将 Firebase 添加到您的 Android 应用。如需了解详情,请访问了解 Firebase 项目

在 Firebase 中注册您的应用

创建 Firebase 项目后,您就可以向其中添加 Android 应用了。

请访问了解 Firebase 项目以详细了解将应用添加到 Firebase 项目的最佳做法和注意事项,包括如何处理多个构建变体。

  1. 访问 Firebase 控制台

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

    如果您已在 Firebase 项目中添加了应用,请点击添加应用以显示平台选项。

  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.3'  // 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. 在您的模块(应用级)Gradle 文件(通常是 app/build.gradle)中,添加要在应用中使用的 Firebase 产品的依赖项。

    您可以将任何支持的 Firebase 产品添加到 Android 应用中。

    为了获得最佳的 Firebase 云消息传递使用体验,我们建议您在项目中启用 Google Analytics(分析)。此外,在设置 Analytics(分析)时,您还需要将适用于 Analytics(分析)的 Firebase SDK 添加到您的应用中。

    已启用 Analytics(分析)

    dependencies {
      // ...
    // Add the Firebase SDK for Google Analytics implementation 'com.google.firebase:firebase-analytics:17.4.4'
    // Add the SDK for Firebase Cloud Messaging implementation 'com.google.firebase:firebase-messaging:20.2.3'
    // Getting a "Could not find" error? Make sure that you've added // Google's Maven repository to your root-level build.gradle file }

    未启用 Analytics(分析)

    dependencies {
      // ...
    // Add the SDK for Firebase Cloud Messaging implementation 'com.google.firebase:firebase-messaging:20.2.3'
    // Getting a "Could not find" error? Make sure that you've added // Google's Maven repository to your root-level build.gradle file }
  2. 同步您的应用以确保所有依赖项都具有必要的版本。

  3. 如果您添加了 Analytics(分析),请运行您的应用,向 Firebase 发送您已成功集成 Firebase 的验证信息。如果您没有添加 Analytics(分析),则可以跳过验证步骤。

    您的设备日志将显示 Firebase 验证信息,表明初始化已完成。如果您在具有网络访问权限的模拟器上运行应用,Firebase 控制台会通知您应用连接已完成。

修改您的应用清单

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

  • 一项继承 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 来获取此令牌。

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

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

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

检索当前注册令牌

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

Java

FirebaseInstanceId.getInstance().getInstanceId()
        .addOnCompleteListener(new OnCompleteListener<InstanceIdResult>() {
            @Override
            public void onComplete(@NonNull Task<InstanceIdResult> task) {
                if (!task.isSuccessful()) {
                    Log.w(TAG, "getInstanceId failed", task.getException());
                    return;
                }

                // Get new Instance ID token
                String token = task.getResult().getToken();

                // 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

FirebaseInstanceId.getInstance().instanceId
        .addOnCompleteListener(OnCompleteListener { task ->
            if (!task.isSuccessful) {
                Log.w(TAG, "getInstanceId failed", task.exception)
                return@OnCompleteListener
            }

            // Get new Instance ID token
            val token = task.result?.token

            // 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

/**
 * Called if InstanceID token is updated. This may occur if the security of
 * the previous token had been compromised. Note that this is called when the InstanceID token
 * is initially generated so this is where you would retrieve the token.
 */
@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
    // Instance ID token to your app server.
    sendRegistrationToServer(token);
}

Kotlin+KTX

/**
 * Called if InstanceID token is updated. This may occur if the security of
 * the previous token had been compromised. Note that this is called when the InstanceID 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
    // Instance ID token to your app server.
    sendRegistrationToServer(token)
}

获取该令牌后,您可以将其发送到应用服务器,并使用您偏好的方法进行存储。请参阅 实例 ID API 参考,了解关于此 API 的完整详情。

检查 Google Play 服务

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

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

防止自动初始化

Firebase 会生成一个实例 ID。FCM 将使用该实例 ID 生成注册令牌,而 Analytics 将使用该实例 ID 收集数据。 在生成实例 ID 后,库会将标识符和配置数据上传到 Firebase。如果您希望阻止自动生成实例 ID,请向您的 AndroidManifest.xml 添加以下元数据值,停用 FCM 和 Analytics 的自动初始化功能(您必须同时为这两者停用此功能):

<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

FirebaseMessaging.getInstance().isAutoInitEnabled = true

此值一经设置便会持久保存,不受应用重启的影响。

后续步骤

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

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

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