本頁面由 Cloud Translation API 翻譯而成。

Switch to English

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

在Firebase 控制台中，單擊添加項目，將 Firebase 項目命名為StockNews ，然後單擊繼續。注意：記住您的 Firebase 項目的項目 ID（或單擊編輯圖標設置您的首選項目 ID）。

您可以跳過啟用 Google Analytics。就本 Codelab 而言，您不需要它。單擊繼續。
單擊創建項目。

恭喜！您剛剛創建了 Firebase 項目。現在，您可以點擊項目名稱進入控制台。

3. 特定於平台的 Firebase 應用配置

啟用 Firebase 支持所需的大部分代碼更改已簽入您正在處理的項目中。但是，為了添加對移動平台的支持，您需要：

在 Firebase 項目上註冊所需的平台
下載特定於平台的配置文件，並將其添加到代碼中。

出於本 Codelab 的目的，我們將添加一個 Android Firebase 應用。

配置安卓

在Firebase 控制台中，選擇左側導航欄頂部的“設置”齒輪中的“項目設置” ，然後單擊“常規”頁面中“您的應用”下的Android圖標。

您應該看到以下對話框：

要提供的重要值是Android 包名稱。將其設置為com.ticker.stocknews 。
1. 此處提供的包名稱必須與入門StockNewsApp代碼的AndroidManifest.xml中提供的包名稱相同。如果您想找到或更改它，請按照下列步驟操作：
  1. 在StockNewsApp目錄中，打開文件app/src/main/AndroidManifest.xml 。
  2. 在manifest元素中，查找package屬性的字符串值。該值是 Android 包名稱。

在 Firebase 對話框中，將復制的包名稱粘貼到Android 包名稱字段中。
您不需要此 Codelab 的調試簽名證書 SHA-1 ，因為此應用不會發布。將此留空。
單擊註冊應用程序。
繼續在 Firebase 控制台中，按照說明下載配置文件google-services.json 。
您可以跳過剩餘的設置步驟，因為其他所有內容都已在入門應用程序代碼中配置。您會發現您的應用程序列在 Firebase 控制台的主頁上。
將google-services.json文件（您剛剛下載的）複製到messaging/fcm-topics-codelab/starter/StockNewsApp/app目錄。

4. 構建並運行您的應用程序

您已準備好真正開始開發您的應用程序了！首先，構建並運行應用程序。

導入入門應用程序

啟動Android Studio，並從起始代碼目錄導入messaging/fcm-topics-codelab/starter/StockNewsApp 。

項目加載後，您可能還會看到一條警告，指出 Git 未跟踪所有本地更改，您可以單擊“忽略”或右上角的“ X ”。（您不會將任何更改推送回 Git 存儲庫。）

如果您位於Android視圖中，則在項目窗口的左上角，您應該會看到如下圖所示的內容。（如果您在項目視圖中，則需要展開項目才能看到相同的內容）

請注意，Android Studio 首次在後台編譯項目可能需要幾秒鐘的時間。在此期間，您將在 Android Studio 底部的狀態欄中看到一個微調器：

我們建議您等到此操作完成後再進行代碼更改。這將允許 Android Studio 引入所有必要的組件。

此外，如果您收到“重新加載以使語言更改生效？”的提示。或類似的內容，選擇“是”。

模擬器設置

如果您需要設置 Android 模擬器的幫助，請參閱運行您的應用程序一文。

了解Android App啟動代碼

起始代碼是一個輕量級 Android 應用程序，具有最少的功能和 UI。
對firebase-messaging SDK 的依賴項已添加到app/build.gradle文件中。

在AndroidManifest.xml中，已添加MESSAGING_EVENT回調處理程序。
- 此處理程序StockNewsMessagingService.java擴展了FirebaseMessagingService類，該類提供各種 Firebase Cloud Messaging 相關功能。請參閱FirebaseMessagingService 文檔以了解更多信息。
- 創建或刷新 FCM 註冊令牌時將調用onNewToken函數。有關詳細信息，請參閱監視令牌生成。
- 當收到消息並且應用程序位於前台時，將調用onMessageReceived函數。目前，它只是記錄收到的消息。
  - 請參閱在 Android 應用程序中接收消息，詳細了解後台和前台消息傳遞和處理之間的差異。
此外，在AndroidManifest.xml中，還提供了一個名為StockNewsApplication的Android Application類。
- 該類將是應用程序啟動時第一個被實例化的類。
- 在StockNewsApplication類的onCreate函數中，添加了 FCM 註冊令牌創建調用。它將生成有效的 FCM 註冊令牌並記錄它。
MainActivity.java添加了顯示 Stock Category 選擇的RecyclerView 。
SubscriptionAdapter.java實現RecyclerView.Adapter ，它繪製股票類別選擇屏幕。
- 每個股票類別都有一個名稱和旁邊的訂閱切換開關。
- 更改切換應該會發出 FCM 主題訂閱/取消訂閱調用。
- 您將在接下來的部分中實現這些調用。
model/StockCategories.java類包含所有股票類別及其關聯主題名稱的列表。

運行啟動應用程序

將 Android 設備連接到計算機或啟動模擬器。
在頂部工具欄中，選擇您的目標 Android 設備或模擬器，然後按運行按鈕。

應用程序 UI 將如下所示：

該應用程序將創建 FCM 註冊令牌並記錄它。但是應用程序 UI 不會發生任何變化。
1. 複製並保存 FCM 註冊令牌，因為它將在後續步驟中使用。

5. 發送測試消息

現在您已準備好向您在上一步中設置的應用程序實例發送測試消息。

導入啟動服務器代碼

啟動 IntelliJ IDEA 並打開messaging/fcm-topics-codelab/starter/StockNewsServer項目。

左側導航欄中的項目視圖應如下所示：

請注意，Intellij IDEA 可能需要幾分鐘時間來構建您的項目，包括提取所需的依賴項。

了解服務器啟動代碼

服務器起始代碼是一個基於 Gradle 的 Java 項目。
build.gradle文件已添加對firebase-admin SDK 的依賴項。該 SDK 提供對各種 FCM 消息發送功能的訪問。

最後，有兩個類，即：
- FcmSender.java ：該類包含以下值得注意的方法：
  - initFirebaseSDK ：初始化 firebase-admin SDK。
  - sendMessageToFcmRegistrationToken ：向 FCM 註冊令牌發送消息。
  - sendMessageToFcmTopic ：向 FCM 主題發送消息。
  - sendMessageToFcmTopicCondition ：向 FCM 主題條件發送消息。
- FcmSubscriptionManager.java ：此類包含允許從服務器端管理主題訂閱的方法。
  - initFirebaseSDK ：初始化 firebase-admin SDK。
  - subscribeFcmRegistrationTokensToTopic ：將 FCM 註冊令牌訂閱到 FCM 主題。
  - unsubscribeFcmRegistrationTokensFromTopic ：從 FCM 主題取消訂閱 FCM 註冊令牌。

設置服務器代碼

首先，我們需要設置一個 Firebase 服務帳戶，允許 firebase-admin SDK 授權調用 FCM API。
1. 轉到 Firebase 控制台，單擊左側導航欄中“項目概述”旁邊的齒輪圖標，然後選擇“項目設置” 。
2. 在設置頁面中，選擇服務帳戶並單擊創建服務帳戶。
3. 現在單擊“生成新的私鑰”按鈕，將開始自動下載密鑰文件。
4. 將密鑰文件重命名為service-account.json並將其複製到messaging/fcm-topics-codelab/starter/StockNewsServer/src/main/resources文件夾中。
5. FcmSender.java和FcmSubscriptionManager.java使用以下代碼從類路徑加載service-account.json文件。
至此，服務端代碼就準備好了。從頂部菜單欄運行“構建”->“構建項目”。

發送測試消息

在FcmSender.java中，找到sendMessageToFcmRegistrationToken函數，並將您從運行入門應用程序部分複制的 FCM 註冊令牌插入到registrationToken字段中。
在main函數中，僅取消註釋sendMessageToFcmRegistrationToken函數，然後單擊運行來執行代碼。
1. 觀察如何將 FCM 註冊令牌設置到message對象的Token字段中。
2. 此外，請注意我們如何使用FirebaseMessaging接口的send API。

這應該向您在上一步中設置的應用程序實例發送一條消息。
當應用程序實例位於前台時，您應該會看到記錄的消息內容。

當應用程序實例處於後台時，您會看到通知托盤中出現該消息。

太棒了，您使用 Firebase Admin SDK 將消息發送到應用實例。詳細了解如何在服務器中使用 Firebase Admin SDK 。

6.實現主題訂閱/退訂

在此步驟中，您將在 Android 應用程序的股票類別切換上實現主題訂閱和取消訂閱操作。

當應用程序用戶切換特定股票類別的開關時，將進行主題訂閱或取消訂閱調用。

審查代碼

導航到 Android 應用程序代碼中的SubscriptionAdapter.java類並找到RecyclerViewViewHolder類。

類構造函數使用setOnCheckedChangeListener為訂閱切換設置偵聽器。
根據開關切換，訂閱和取消訂閱操作分別通過調用subscribeToStockCategory和unsubscribeFromStockCategory方法來執行。
setData方法由 RecyclerView Adapter 的onBindViewHolder調用，以將 ViewHolder 與適當的 Stock Category 綁定。

實現主題訂閱

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

實現主題取消訂閱

同樣，在 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();
          });
    }

我們來嘗試一下

運行應用程序並切換股票類別選項以執行訂閱和取消訂閱操作。它看起來像這樣：

訂閱	退訂

7. 發送您的第一條主題消息

在此步驟中，您將實現服務器端代碼來發送 FCM 主題消息。

實現服務器端集成以發送主題消息

在服務器代碼中，跳轉到FcmSender.java並找到名為sendMessageToFcmTopic的方法。

在第一行中，提供您要將消息發送到的 FCM 主題。
- 它是一個以下形式的字符串： /topics/<Topic Name> 。例如， /topics/Technology 。
在下一行中創建一個新的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();

現在添加對FirebaseMessaging實例的調用以發送消息（與sendMessageToFcmRegistrationToken函數中進行的發送調用相同）。

FirebaseMessaging.getInstance().send(message);

最後，更新main函數並啟用僅調用sendMessageToFcmTopic函數。

發送消息並驗證接收

在發送主題消息之前，首先確保您的應用實例已訂閱您要發送到的主題。
1. 這可以通過翻轉相應的開關來完成。例如：
您現在可以通過執行FcmSender.java的main函數來發送主題消息。
像以前一樣，您應該能夠觀察應用程序實例上的消息接收。
1. 前台應用程序實例
1. 後台應用程序實例
獎勵：嘗試取消訂閱您發送到的主題並重新發送消息。您會發現消息沒有傳遞到應用程序實例。

8. 發送您的第一條主題條件消息

主題條件功能允許您將消息發送到主題組合，從而使您能夠提供更具表現力的受眾定義。

例如，在我們的 StockNews 應用程序中，考慮向訂閱技術或汽車主題的一組應用程序實例發送消息的可能性。例如，如果發生涉及 Waymo 的值得注意事件，則可能會發生這種情況。

主題允許您使用以下運算符以布爾表達式的形式表達您的組合

&& ：邏輯與。例如， 'Technology' in topics && 'Automotive' in topics - 僅定位訂閱技術和汽車主題的應用程序實例。
|| ：邏輯或。例如， 'Technology' in topics || 'Automotive' in topics - 定位訂閱技術或汽車主題的應用程序實例。
() ：用於分組的括號。例如， 'Technology' in topics && ('Automotive' in topics || 'Energy' in topics) - 僅定位訂閱技術以及汽車或能源主題的應用程序實例。

詳細了解如何構建使用此功能的發送請求。

實現服務器端集成以發送主題條件消息

返回服務器代碼，跳轉到FcmSender.java並找到名為sendMessageToFcmTopicCondition的方法。

在第一行中，對於topicCondition變量，提供要將消息發送到的主題條件。您可以將其設置為： 'Technology' in topics && 'Automotive' in topics 。
在接下來的行中，創建一個新的message對象（類似於sendMessageToFcmTopic函數中定義的對象）。
1. 區別在於您將設置Topic字段，而不是設置對象的Condition字段。

    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();

現在添加對FirebaseMessaging實例的調用以發送消息（與sendMessageToFcmTopic函數中進行的發送調用相同）。

FirebaseMessaging.getInstance().send(message);

最後，更新main函數並啟用僅調用sendMessageToFcmTopicCondition函數。

發送消息並驗證接收

在發送主題消息之前，首先通過訂閱技術和汽車主題來確保您的應用實例滿足指定的主題條件。
您現在可以通過執行FcmSender.java的main函數來發送主題消息。
像以前一樣，您應該能夠觀察應用程序實例上的消息接收。
1. 前台應用程序實例
1. 後台應用程序實例
獎勵：您現在可以取消訂閱技術主題並重新發送主題條件消息。您應該觀察到應用程序實例沒有收到該消息。

9. 回顧

讓我們快速回顧一下到目前為止您所學到的內容。

如何從應用實例發起主題訂閱/取消訂閱。
向主題發送消息並驗證訂閱的應用程序實例的接收。
向主題條件發送消息並驗證滿足條件的應用程序實例上的接收。

在下一節中，您將了解如何訂閱/取消訂閱應用程序實例的主題，而無需從客戶端實例化調用。

10.從服務器端管理主題訂閱

到目前為止，在此 Codelab 中，所有主題訂閱和取消訂閱調用都是從應用實例發起的。

但是，在某些用例中，您可能希望從服務器端管理主題訂閱。例如，您可能希望為現有用戶群的一部分訂閱新主題，而無需等待應用程序推出。

在本部分中，您將了解如何使用 Firebase Admin SDK通過從服務器端進行調用來訂閱和取消訂閱主題的一批 FCM 註冊令牌。

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

在服務器代碼中，跳轉到FcmSubscriptionManager.java類。找到名為subscribeFcmRegistrationTokensToTopic的方法。您將在此處實現對subscribeToTopic API 的調用。

讓我們將應用程序實例訂閱 Energy 主題。為此，首先為以下兩個字段提供數據：
1. registrationTokens ：以逗號分隔的字符串列表，表示您要為其創建主題訂閱的 FCM 註冊令牌。
2. topicName ：Energy 主題的主題名稱，即/topics/Energy 。
在接下來的幾行中，按照以下方式實現調用：

TopicManagementResponse response = FirebaseMessaging.getInstance().subscribeToTopic(
        registrationTokens, topicName);

您可以檢查TopicManagementResponse以獲得一些高級結果統計信息。例如使用getSuccessCount打印成功創建的主題訂閱的數量。

System.out.printf("Num tokens successfully subscribed %d", response.getSuccessCount());

最後，在main函數中僅啟用對subscribeFcmRegistrationTokensToTopic函數的調用。

創建訂閱並發送主題消息

此時，您已準備好創建主題訂閱並向其發送消息。
執行FcmSubscriptionManager.java類的main函數。這將創建一個主題訂閱。
現在，設置發送消息的代碼。與之前類似，
1. 在FcmSender.java中，找到sendMessageToFcmTopic函數。
2. 將topicName設置為 Energy 主題，即/topics/Energy 。
3. 創建一個Message對象並使用setTopic將其定位到主題。
4. 最後，更新main方法以僅啟用sendMessageToFcmTopic功能。
執行FcmSender.java的main函數。這會將消息發送到您的應用程序實例，您可以在應用程序中觀察它，如下所示。
1. 前台應用程序實例
1. 後台應用程序實例

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

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

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

11.恭喜你

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

下一步是什麼？

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

參考文檔

Android API 參考（ Java / Kotlin ）
iOS API 參考（ ObjectiveC / Swift ）
Javascript API 參考（版本 9 /版本 8 ）
管理 SDK 參考（ Node.js / Java / Python / .NET ）