您使用 FCM 主题的第一条多播推送消息

一、简介

目标

在此 Codelab 中,您将学习如何检测您的多平台应用程序,以便您可以使用 FCM 主题将推送消息多播到应用程序实例的各个子组。

完成后,您将能够利用 FCM 基础架构来管理这些子组以及通过子组的多播推送消息。

主题概述

主题是一种 FCM 基础架构支持的方式,可以通过消息到达应用实例的子组。

FCM 提供 API 来发送消息以及维护对这些主题的订阅。将应用实例与主题关联和分离的行为分别称为订阅和取消订阅

主题应用于公开可用的内容。例如,有关天气更新的消息。如果您想发送用户敏感消息,请使用 Firebase Admin SDK在多个设备上多播消息

基于主题的多播针对吞吐量进行了优化。

你会学到什么

  • 如何为用户订阅(和取消订阅)移动应用程序中的主题。
  • 如何使用主题发送多播推送消息。
  • 如何使用主题条件向主题组合发送消息。
  • 如何在服务器端管理主题订阅并进行批量订阅和取消订阅。

您将构建什么

  • 订阅/取消订阅主题并在发送到主题时接收消息的 Android 应用程序。
  • 使用 Firebase Admin SDK 的服务器端集成,将用于通过 FCM API 发送主题消息。

你需要什么

  • 您选择的浏览器,例如 Chrome。
  • 用于开发 Java 应用程序的IntelliJ IDEA IDE。
    • 确保在安装时选择加入对 Gradle 的支持。
  • 用于开发 Android 应用程序的Android Studio IDE。
  • 运行 Android 应用程序的设备。任一个:
    • 安卓模拟器。 (需要在Android Studio中设置)。
    • 连接到您的计算机并设置为开发人员模式的物理 Android 设备。
  • 用于创建和管理 Firebase 项目的 Google 帐户。

2. 设置

获取代码

从命令行克隆 GitHub 存储库:

git clone https://github.com/firebase/quickstart-android.git fcm-codelab

示例代码将被克隆到fcm-codelab目录中。

cd fcm-codelab

此 codelab 的入门应用程序位于fcm-topics-codelab分支的messaging目录中。执行以下步骤以获取入门代码。它包含两个目录StockNewsAppStockNewsServer 。前者包含启动 Android 应用程序,后者包含启动服务器端代码。

git checkout fcm-topics-codelab
cd messaging/fcm-topics-codelab/starter

本 codelab 的完整版本放在messaging/fcm-topics-codelab/completed目录下。

创建一个 Firebase 项目

  1. Firebase 控制台中,单击Add project ,将 Firebase 项目命名为StockNews并单击 continue。注意:记住您的 Firebase 项目的项目 ID(或点击编辑图标来设置您的首选项目 ID)。

fc08f9a7808e4553.png

  1. 您可以跳过启用 Google Analytics。出于本 Codelab 的目的,您不需要它。单击继续。
  2. 单击创建项目

恭喜!您刚刚创建了 Firebase 项目。现在,您可以点击项目名称进入控制台。

3. 平台特定的 Firebase 应用配置

启用 Firebase 支持所需的大部分代码更改已签入您正在处理的项目中。但是,为了添加对移动平台的支持,您需要:

  • 在 Firebase 项目上注册所需的平台
  • 下载特定于平台的配置文件,并将其添加到代码中。

出于本 Codelab 的目的,我们将添加一个 Android Firebase 应用。

84e0b3199bef6d8a.png配置安卓

  1. Firebase Console中,选择 Settings cog 左侧导航栏顶部的Project Settings ,然后单击General页面中Your apps下的Android图标。

您应该看到以下对话框: 8254fc299e82f528.png

  1. 提供的重要值是Android 包名称。将其设置为com.ticker.stocknews
    1. 此处提供的包名称必须与您的 Starter StockNewsApp代码的AndroidManifest.xml中提供的包名称相同。如果您想找到或更改它,请按照下列步骤操作:
      1. StockNewsApp目录中,打开文件app/src/main/AndroidManifest.xml
      2. manifest元素中,找到package属性的字符串值。此值是 Android 包名称。
  1. 在 Firebase 对话框中,将复制的包名称粘贴到Android 包名称字段中。
  2. 您不需要此 Codelab 的调试签名证书 SHA-1 ,因为此应用不会发布。将此留空。
  3. 单击注册应用程序
  4. 继续在 Firebase 控制台中,按照说明下载配置文件google-services.json
  5. 您可以跳过其余的设置步骤,因为其他所有内容都已在入门应用程序代码中配置。您会在 Firebase 控制台的主页上找到您的应用。
  6. google-services.json文件(您刚刚下载的)复制到messaging/fcm-topics-codelab/starter/StockNewsApp/app目录。

4. 构建并运行您的应用程序

您已经准备好开始实际使用您的应用程序了!首先,构建并运行应用程序。

导入入门应用

启动 Android Studio,并从 starter 代码目录中导入messaging/fcm-topics-codelab/starter/StockNewsApp

项目加载后,您可能还会看到 Git 没有跟踪您所有本地更改的警报,您可以单击“忽略”或右上角的“ X ”。 (您不会将任何更改推送回 Git 存储库。)

在项目窗口的左上角,如果您在Android视图中,您应该会看到类似下图的内容。 (如果您在项目视图中,则需要展开项目才能看到相同的内容)

b574ea0089ee87c6.png

请注意,Android Studio 第一次在后台编译项目可能需要几秒钟的时间。在此期间,您将在 Android Studio 底部的状态栏中看到一个微调器:

4bc64eb3b99eb0ae.png

我们建议您等到完成后再进行代码更改。这将允许 Android Studio 引入所有必要的组件。

此外,如果您收到提示“重新加载以使语言更改生效?”或类似的东西,选择“是”。

模拟器设置

如果您在设置 Android 模拟器时需要帮助,请参阅运行您的应用一文。

了解 Android 应用启动代码

  • 入门代码是一个轻量级的 Android 应用程序,具有最少的功能和 UI。
  • firebase-messaging SDK的依赖已添加到app/build.gradle文件中。

f04ff8f48d186dff.png

  • AndroidManifest.xml中,已经添加了MESSAGING_EVENT回调处理程序。
    • 此处理程序StockNewsMessagingService.java扩展了FirebaseMessagingService类,该类提供各种与 Firebase 云消息传递相关的功能。请参阅FirebaseMessagingService 文档以了解更多信息。 b843c4d33ee53166.png
    88fad1960f4a6ff5.png
    • 创建或刷新 FCM 注册令牌时调用onNewToken函数。有关详细信息,请参阅监控令牌生成
    • 当收到消息并且应用程序处于前台时,将调用onMessageReceived函数。目前,它只是记录收到的消息。
  • 此外,在AndroidManifest.xml中,还提供了一个名为StockNewsApplicationAndroid Applicationa4982a8731492dfc.pngccde692f7f68dc5a.png
    • 此类将是 App 启动时第一个被实例化的类。
    • StockNewsApplication类的onCreate函数中,添加了 FCM 注册令牌创建调用。它将生成一个有效的 FCM 注册令牌并记录它。
  • MainActivity.java添加了显示 Stock Category 选项的RecyclerView
  • SubscriptionAdapter.java实现了绘制 Stock Category 选择屏幕的RecyclerView.Adapter
    • 每个股票类别旁边都有一个名称和一个订阅切换。
    • 更改切换应进行 FCM 主题订阅/取消订阅调用。
    • 您将在接下来的部分中实现这些调用。
  • model/StockCategories.java类包含所有股票类别及其相关主题名称的列表。

b32663ec4e865a18.png

运行入门应用

  1. 将您的 Android 设备连接到计算机或启动模拟器。
  2. 在顶部工具栏中,选择您的目标 Android 设备或模拟器,然后按运行按钮。

5b27fc5b237e06b9.png

  1. 应用程序 UI 如下所示:

ff5b1a1c53231c54.png

  1. 该应用程序将创建一个 FCM 注册令牌并记录它。但是,App UI 中的任何内容都不会改变。
    1. 复制并保存 FCM 注册令牌,因为它将在后续步骤中使用。

927eb66bc909f36b.png

5.发送测试消息

现在您已准备好向您在上一步中设置的应用程序实例发送测试消息。

导入启动服务器代码

启动 IntelliJ IDEA 并打开messaging/fcm-topics-codelab/starter/StockNewsServer项目。

左侧导航栏中的项目视图应如下所示:

da20711f6527dff6.png

请注意,IntellIj IDEA 可能需要几分钟来构建您的项目,包括提取所需的依赖项。

了解服务器启动代码

  • 服务器启动代码是一个基于 Gradle 的 Java 项目。
  • build.gradle文件已经添加了对 firebase -admin SDK的依赖。此 SDK 提供对各种 FCM 消息发送功能的访问。

650fc733298588f8.png

  • 最后,有两个类,即:
    • FcmSender.java :该类包含以下注意方法:
      • initFirebaseSDK :初始化 firebase-admin SDK。
      • sendMessageToFcmRegistrationToken :向 FCM 注册令牌发送消息。
      • sendMessageToFcmTopic :向 FCM 主题发送消息。
      • sendMessageToFcmTopicCondition :向 FCM 主题条件发送消息。
    • FcmSubscriptionManager.java :此类包含允许从服务器端管理主题订阅的方法。
      • initFirebaseSDK :初始化 firebase-admin SDK。
      • subscribeFcmRegistrationTokensToTopic :将 FCM 注册令牌订阅到 FCM 主题。
      • unsubscribeFcmRegistrationTokensFromTopic :取消订阅 FCM 主题的 FCM 注册令牌。

设置服务器代码

  1. 首先,我们需要设置一个 Firebase 服务帐户,允许 firebase-admin SDK 授权对 FCM API 的调用。
    1. 转到 Firebase 控制台,单击左侧导航栏中Project Overview旁边的齿轮图标,然后选择Project settings8c2108d4d7c915e9.png
    2. 在设置页面中,选择服务帐户,然后单击创建服务帐户84b128cc5dac0a85.png
    3. 现在单击Generate new private key按钮,将开始自动下载您的密钥文件。
    4. 将密钥文件重命名为service-account.json并将其复制到messaging/fcm-topics-codelab/starter/StockNewsServer/src/main/resources文件夹中。
    5. FcmSender.javaFcmSubscriptionManager.java都使用以下代码从类路径加载service-account.json文件。 8dffbee658e0bdd.png
  2. 至此,服务器代码已准备就绪。从顶部菜单栏中运行 Build -> Build Project。

发送测试消息

  1. FcmSender.java找到sendMessageToFcmRegistrationToken函数,并将您从Run the starter app部分复制的 FCM 注册令牌插入到registrationToken字段中。
  2. main函数中,只取消注释sendMessageToFcmRegistrationToken函数并单击运行以执行代码。
    1. 观察 FCM 注册令牌是如何设置到message对象的Token字段中的。
    2. 此外,请注意我们如何使用FirebaseMessaging接口的send API。

52e4a3ec3f816473.png

  1. 这应该会向您在上一步中设置的应用程序实例发送一条消息。
  2. 当应用程序实例处于前台时,您应该会看到记录的消息内容。

d3540ec1089f97dd.png

  1. 当 App 实例在后台时,您会观察到消息出现在通知托盘中。

31203deca59c03fe.png

太棒了,您使用 Firebase Admin SDK 向应用实例发送消息。阅读有关在您的服务器中使用 Firebase Admin SDK 的更多信息。

6.实现主题订阅/退订

在此步骤中,您将在 Android 应用程序的 Stock Category 开关上实现主题订阅和取消订阅操作。

当 App 用户切换特定股票类别的开关时,将进行主题订阅或取消订阅调用。

审核代码

  • 导航到 Android App 代码中的SubscriptionAdapter.java类并找到RecyclerViewViewHolder类。

6c0614199e684f6.png

  • 类构造函数使用setOnCheckedChangeListener为订阅切换设置监听器。
  • 根据切换开关,订阅和取消订阅操作分别通过调用subscribeToStockCategoryunsubscribeFromStockCategory方法来执行。
  • setData方法由 RecyclerView 适配器的onBindViewHolder ,以将 ViewHolder 与适当的 Stock Category 绑定。

实施主题订阅

  1. subscribeToStockCategory方法中,您将实现对FirebaseMessaging对象的subscribeToTopic API 的调用。代码可能如下所示:
   void subscribeToStockCategory() {
      // Making call to FCM for subscribing to the topic for stockCategory
     FirebaseMessaging.getInstance().subscribeToTopic(stockCategory.getTopicName()).addOnSuccessListener(
          unused -> {
            // Subscribing action successful
            Log.i(TAG, "Subscribed to topic: " + stockCategory.getTopicName());
            Toast.makeText(itemView.getContext(), "Subscribed to " + stockCategory.getCategoryName(),
                Toast.LENGTH_SHORT).show();
          });
    }

实施主题退订

  1. 同样,在 else 条件下,您将实现对unsubscribeFromTopic API 的调用。大致如下:
void unsubscribeFromStockCategory() {
      // Making call to FCM for unsubscribing from the topic for stockCategory
      FirebaseMessaging.getInstance().unsubscribeFromTopic(stockCategory.getTopicName())
          .addOnSuccessListener(unused -> {
            // Unsubscribing action successful
            Log.i(TAG, "Unsubscribed from topic: " + stockCategory.getTopicName());
            Toast.makeText(itemView.getContext(), "Unsubscribed from " + stockCategory.getCategoryName(),
                Toast.LENGTH_SHORT).show();
          });
    }

让我们试试看

  1. 运行应用程序并切换股票类别选项以执行订阅和取消订阅操作。它看起来像这样:

订阅

退订

7. 发送您的第一个主题消息

在此步骤中,您将实现服务器端代码以发送 FCM 主题消息。

实现服务器端集成以发送主题消息

  1. 在服务器代码中,跳转到FcmSender.java并找到名为sendMessageToFcmTopic的方法。

56381dd1b40cde9c.png

  1. 在第一行中,提供您要将消息发送到的 FCM 主题。
    • 它是以下形式的字符串: /topics/<Topic Name> 。例如, /topics/Technology
  2. 在接下来的几行中,创建一个新的message对象(类似于在sendMessageToFcmRegistrationToken函数中定义的那个)。
    • 不同之处在于您将设置Topic字段,而不是设置message对象的Token字段。
Message message = Message.builder()
        .putData("FOOTECH", "$1000")
        .setNotification(
            Notification.builder()
                .setTitle("Investor confidence in Tech Stocks growing")
                .setBody("Foo Tech leading the way in stock growth for Tech sector.")
                .build())
        .setTopic(topicName)
        .build();
  1. 现在添加对FirebaseMessaging实例的调用以发送消息(与在sendMessageToFcmRegistrationToken函数中进行的发送调用相同)。
FirebaseMessaging.getInstance().send(message);
  1. 最后,更新main函数并启用仅调用sendMessageToFcmTopic函数。

9a6aa08dd7c28898.png

发送消息并验证收据

  1. 在发送主题消息之前,首先确保您的应用实例订阅了您要发送到的主题。
    1. 这可以通过翻转相应的切换来完成。例如:
    4668247408377712.png
  2. 您现在可以通过执行FcmSender.javamain功能来发送您的主题消息。
  3. 像以前一样,您应该能够观察应用实例上的消息接收。
    1. 前台应用实例
    c144721399f610fe.png
    1. 后台应用实例
    44efc7dfd57e8e9a.png
  4. 奖励:尝试取消订阅您发送到的主题并重新发送消息。您会观察到消息未传递到应用程序实例。

8. 发送您的第一个主题条件消息

主题条件功能允许您将消息发送到主题组合,使您能够提供更具表现力的受众定义。

例如,在我们的 StockNews 应用程序中,考虑向订阅技术或汽车主题的一组应用程序实例发送消息的可能性。例如,如果有涉及 Waymo 的值得注意的事件,则可能会发生这种情况。

主题允许您使用以下运算符以布尔表达式的形式表达您的组合

  • && :逻辑与。例如, 'Technology' in topics && 'Automotive' in topics - 仅针对订阅了技术和汽车主题的应用程序实例。
  • || : 逻辑或。例如, 'Technology' in topics || 'Automotive' in topics - 以订阅技术或汽车主题的应用程序实例为目标。
  • () :用于分组的括号。例如, 'Technology' in topics && ('Automotive' in topics || 'Energy' in topics) - 仅针对订阅了技术以及汽车或能源主题的应用实例。

阅读有关如何构建发送请求以使用此功能的更多信息。

实现服务器端集成以发送主题条件消息

  1. 返回服务器代码,跳转到FcmSender.java并找到名为sendMessageToFcmTopicCondition的方法。

3719a86c274522cf.png

  1. 在第一行中,对于topicCondition变量,提供您要将消息发送到的主题条件。您可以将其设置为: 'Technology' in topics && 'Automotive' in topics
  2. 在接下来的几行中,创建一个新的message对象(类似于在sendMessageToFcmTopic函数中定义的对象)。
    1. 不同之处在于您将设置Condition字段,而不是设置对象的Topic字段。
    Message message = Message.builder()
        .putData("FOOCAR", "$500")
        .setNotification(
            Notification.builder()
                .setTitle("Foo Car shows strong Q2 results")
                .setBody("Foo Car crosses 1B miles. Stocks rally.")
                .build())
        .setCondition(topicCondition)
        .build();
  1. 现在添加对FirebaseMessaging实例的调用以发送消息(与在sendMessageToFcmTopic函数中进行的发送调用相同)。
FirebaseMessaging.getInstance().send(message);
  1. 最后,更新main函数并启用仅调用sendMessageToFcmTopicCondition函数。

db9588d40d2a0da6.png

发送消息并验证收据

  1. 在发送主题消息之前,首先确保您的应用实例满足指定的主题条件,方法是为应用实例订阅技术和汽车主题。
  2. 您现在可以通过执行FcmSender.javamain功能来发送您的主题消息。
  3. 和以前一样,您应该能够在应用实例上观察消息接收。
    1. 前台应用实例
    6f612ace15aa6515.png
    1. 后台应用实例
    78044a56ac2359cb.png
  4. 奖励:您现在可以取消订阅技术主题并重新发送主题条件消息。您应该观察到应用实例没有收到该消息。

9. 回顾

让我们快速回顾一下到目前为止您所学到的知识。

  • 如何从应用实例启动主题订阅/取消订阅。
  • 向主题发送消息并验证订阅的应用程序实例的收据。
  • 向主题条件发送消息并在满足条件的应用实例上验证接收。

在下一节中,您将了解如何订阅/取消订阅主题的应用程序实例,而无需实例化来自客户端的调用。

c0dc20655d392690.gif

10.从服务器端管理主题订阅

到目前为止,在此 Codelab 中,所有主题订阅和取消订阅调用都是从应用实例发起的。

但是,在某些用例中,您可能希望从服务器端管理主题订阅。例如,您可能希望为现有用户群的一个子组订阅一个新主题,而无需等待应用推出。

在本节中,您将学习如何使用 Firebase Admin SDK通过从服务器端进行调用来订阅和取消订阅一批 FCM 注册令牌到某个主题。

实现 FCM 注册令牌的服务器端订阅到 FCM 主题

  1. 在服务器代码中,跳转到FcmSubscriptionManager.java类。找到名为subscribeFcmRegistrationTokensToTopic的方法。您将在此处实现对subscribeToTopic API 的调用。

5d5709e7b3cbcb04.png

  1. 让我们为应用实例订阅能源主题。为此,首先为以下两个字段提供数据:
    1. registrationTokens :一个逗号分隔的字符串列表,表示您要为其创建主题订阅的 FCM 注册令牌。
    2. topicName :能源主题的主题名称,即/topics/Energy
  2. 在接下来的几行中,按照以下几行实现调用:
TopicManagementResponse response = FirebaseMessaging.getInstance().subscribeToTopic(
        registrationTokens, topicName);
  1. 您可以检查TopicManagementResponse以获取一些高级结果统计信息。例如使用getSuccessCount打印成功创建主题订阅的数量。
System.out.printf("Num tokens successfully subscribed %d", response.getSuccessCount());
  1. 最后,在main函数中启用仅调用subscribeFcmRegistrationTokensToTopic函数。

创建订阅并发送主题消息

  1. 此时您已准备好创建主题订阅并向其发送消息。
  2. 执行FcmSubscriptionManager.java类的main功能。这将创建一个主题订阅。
  3. 现在,设置代码以发送消息。和之前一样,
    1. FcmSender.java中,找到sendMessageToFcmTopic函数。
    2. topicName设置为 Energy 主题,即/topics/Energy
    3. 创建一个Message对象并使用setTopic将其定位到主题。
    4. 最后,将main方法更新为仅启用sendMessageToFcmTopic功能。
  4. 执行FcmSender.javamain功能。这会将消息发送到您的应用程序实例,您可以在您的应用程序中观察它,如下所示。
    1. 前台应用实例
    40ab6cf71e0e4116.png
    1. 后台应用实例
    8fba81037198209e.png

实现服务器端取消订阅 FCM 注册令牌到 FCM 主题

  1. 对于服务器端主题取消订阅,请使用此unsubscribeFromTopic API。您将相关代码添加到FcmSubscriptionManager.java类的unsubscribeFcmRegistrationTokensFromTopic函数中。

8d9e8ea9d34016bd.png

  1. 实现服务器端取消订阅代码并通过发送主题消息验证其效果,留给您作为练习。

11. 恭喜

恭喜您已成功使用 FCM 主题向应用实例的子组发送多播消息。这将有助于简化您及时向用户提供相关内容的能力。

947def3eb33b1e4a.gif

下一步是什么?

现在您已经完成了代码实验室,请考虑使用以下指南尝试其他平台的主题:

参考文档