ไปที่คอนโซล

在 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 应用。

设置 Firebase 和 FCM SDK

  1. 将 Firebase 添加到您的 Android 项目(如果尚未添加)。
  2. 在项目级 build.gradle 文件中,请务必在您的 buildscriptallprojects 部分添加 Google 的 Maven 代码库。
  3. 将 Firebase 云消息传递 Android 版库的依赖项添加到您的模块(应用级)Gradle 文件(通常为 app/build.gradle):
    implementation 'com.google.firebase:firebase-messaging:19.0.1'

修改您的应用清单

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

  • 一项继承 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

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

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

获取该令牌后,您可以将其发送到应用服务器,并使用您偏好的方法进行存储。请参阅 Instance 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

FirebaseMessaging.getInstance().isAutoInitEnabled = true
此值一经设置,即使应用重启也会继续生效。

后续步骤

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

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

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