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

要编写您的 Android 版 Firebase 云消息传递 (FCM) 客户端应用,请将 FirebaseMessaging API 和 Android Studio 1.4 或更高版本与 Gradle 结合使用。本文中的说明假定您已完成将 Firebase 添加至您的 Android 项目的步骤。

FCM 客户端需要在运行 Android 4.0 或更高版本且安装了 Google Play 商店应用的设备上运行,或者在运行 Android 4.0 且支持 Google API 的模拟器中运行。请注意,您并非只能通过 Google Play 商店部署您的 Android 应用。

设置 Firebase 和 FCM SDK

  1. 将 Firebase 添加至您的 Android 项目(如果尚未添加)。

  2. 在 Android Studio 中,将 FCM 依赖项添加至您的应用级 build.gradle 文件:

    dependencies {
         compile 'com.google.firebase:firebase-messaging:12.0.1'
    }

修改您的应用清单

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

  • 一项继承 FirebaseMessagingService 的服务。如果您希望在后台进行除接收应用通知之外的消息处理,则必须添加此服务。要接收前台应用中的通知、接收数据有效负载以及发送上行消息等,您必须继承此服务。
  • <service
        android:name=".MyFirebaseMessagingService">
        <intent-filter>
            <action android:name="com.google.firebase.MESSAGING_EVENT"/>
        </intent-filter>
    </service>
  • 一项继承 FirebaseInstanceIdService 的服务,用于处理注册令牌的创建、轮替和更新。如果要发送至特定设备或者创建设备组,则必须添加此服务。
  • <service
        android:name=".MyFirebaseInstanceIDService">
        <intent-filter>
            <action android:name="com.google.firebase.INSTANCE_ID_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 对于 Android 应用的功能至关重要,请务必在应用的 build.gradle 中设置 minSdkVersion 8 或更高版本。这可确保 Android 应用无法安装在不能让其正常运行的环境中。

获取设备注册令牌

您的应用初次启动时,FCM SDK 会为客户端应用实例生成一个注册令牌。如果您希望定位至单台设备或创建设备组,则需要通过继承 FirebaseInstanceIdService 来访问此令牌。

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

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

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

检索当前注册令牌

如果需要检索当前令牌,请调用 FirebaseInstanceId.getInstance().getToken()。如果令牌尚未生成,此方法将返回 null。

监控令牌的生成

每次生成新的令牌时,都会触发 onTokenRefresh 回调,因此,在上下文中调用 getToken 可以确保您访问的是当前可用的注册令牌。确保已将该服务添加到您的清单文件中,然后在 onTokenRefresh 的上下文中调用 getToken,并记录相应值,如下所示:

@Override
public void onTokenRefresh() {
    // Get updated InstanceID token.
    String refreshedToken = FirebaseInstanceId.getInstance().getToken();
    Log.d(TAG, "Refreshed token: " + refreshedToken);

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

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

防止自动初始化

FCM 会生成一个实例 ID,并将其用作注册令牌。在生成实例 ID 后,库会将标识符和配置数据上传到 Firebase。要防止自动生成实例 ID,请通过向您的 AndroidManifest.xml 添加元数据值来停用 FCM:

<?xml version="1.0" encoding="utf-8"?>
<application>
  <meta-data android:name="firebase_messaging_auto_init_enabled"
             android:value="false" />
</application>

要重新启用 FCM,请执行运行时调用:

FirebaseMessaging.getInstance().setAutoInitEnabled(true);
此值一经设置,即使应用重启也将持续生效。

后续步骤

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

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

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

发送以下问题的反馈:

此网页
需要帮助?请访问我们的支持页面