您使用 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目錄中。執行以下步驟以獲取入門代碼。它包含兩個目錄StockNewsApp和StockNewsServer 。前者包含啟動 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中，還提供了一個名為StockNewsApplication的Android Application類。 a4982a8731492dfc.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 settings 。 8c2108d4d7c915e9.png
    2. 在設置頁面中，選擇服務帳戶，然後單擊創建服務帳戶。 84b128cc5dac0a85.png
    3. 現在單擊Generate new private key按鈕，將開始自動下載您的密鑰文件。
    4. 將密鑰文件重命名為service-account.json並將其複製到messaging/fcm-topics-codelab/starter/StockNewsServer/src/main/resources文件夾中。
    5. FcmSender.java和FcmSubscriptionManager.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為訂閱切換設置監聽器。
  • 根據切換開關，訂閱和取消訂閱操作分別通過調用subscribeToStockCategory和unsubscribeFromStockCategory方法來執行。
  • 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.java的main功能來發送您的主題消息。
  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.java的main功能來發送您的主題消息。
  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.java的main功能。這會將消息發送到您的應用程序實例，您可以在您的應用程序中觀察它，如下所示。
    1. 前台應用實例
    40ab6cf71e0e4116.png
    1. 後台應用實例
    8fba81037198209e.png

實現服務器端取消訂閱 FCM 註冊令牌到 FCM 主題

  1. 對於服務器端主題取消訂閱，請使用此unsubscribeFromTopic API。您將相關代碼添加到FcmSubscriptionManager.java類的unsubscribeFcmRegistrationTokensFromTopic函數中。

8d9e8ea9d34016bd.png

  1. 實現服務器端取消訂閱代碼並通過發送主題消息驗證其效果，留給您作為練習。

11. 恭喜

恭喜您已成功使用 FCM 主題向應用實例的子組發送多播消息。這將有助於簡化您及時向用戶提供相關內容的能力。

947def3eb33b1e4a.gif

下一步是什麼？

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

參考文檔