您使用 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

下一步是什麼?

現在您已經完成了代碼實驗室,請考慮使用以下指南嘗試其他平台的主題:

參考文檔