根據 FCM 主題顯示的第一則多點傳播推送訊息

1. 簡介

目標

在本程式碼研究室中，您將瞭解如何檢測多平台應用程式，以便使用 FCM 主題將推送訊息多播至應用程式執行個體的各種子群組。

完成後，您就能運用 FCM 基礎架構管理這些子群組，以及透過子群組傳送多播推播訊息。

主題總覽

主題是 FCM 基礎架構支援的方式，可透過訊息觸及應用程式例項的子群組。

FCM 提供 API，可傳送訊息及維護這些主題的訂閱項目。將應用程式執行個體與主題建立關聯或取消關聯的行為，分別稱為「訂閱」和「取消訂閱」

主題應適用於公開內容。例如天氣更新訊息。如要傳送使用者私密訊息，請使用 Firebase Admin SDK 透過多部裝置傳送多播訊息。

主題式多播是針對總處理量進行最佳化調整。

課程內容

• 如何透過行動應用程式訂閱 (和取消訂閱) 主題。
• 如何使用主題傳送多播推送通知。
• 如何使用主題條件，將訊息傳送至多個主題。
• 如何從伺服器端管理主題訂閱，以及大量訂閱和取消訂閱。

建構項目

• Android 應用程式，可訂閱/取消訂閱主題，並在訊息傳送至主題時接收訊息。
• 使用 Firebase Admin SDK 進行伺服器端整合，透過 FCM API 傳送主題訊息。

軟硬體需求

• 你選擇的瀏覽器，例如 Chrome。
• IntelliJ IDEA IDE，用於開發 Java 應用程式。
  • 請務必在安裝時選擇支援 Gradle。
• Android Studio IDE，用於開發 Android 應用程式。
• 用來執行 Android 應用程式的裝置。下列任一項：
  • Android 模擬器。(需要在 Android Studio 中設定)。
  • 已連上電腦並設為開發人員模式的實體 Android 裝置。
• 用於建立及管理 Firebase 專案的 Google 帳戶。

2. 開始設定

取得程式碼

從指令列複製 GitHub 存放區：

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

程式碼範例會複製到 fcm-codelab 目錄。

cd fcm-codelab

本程式碼研究室的範例應用程式位於 fcm-topics-codelab 分支版本的 messaging 目錄中。請按照下列步驟存取範例程式碼。其中包含 StockNewsApp 和 StockNewsServer 兩個目錄。前者包含範例 Android 應用程式，後者則包含範例伺服器端程式碼。

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

本程式碼研究室的完成版位於 messaging/fcm-topics-codelab/completed 目錄中。

建立 Firebase 專案

1. 使用 Google 帳戶登入 Firebase 控制台。
2. 按一下按鈕建立新專案，然後輸入專案名稱 (例如 StockNews)。
   
3. 按一下「繼續」。
4. 如果系統提示，請詳閱並接受 Firebase 條款，然後按一下「繼續」。
5. (選用) 在 Firebase 控制台中啟用 AI 輔助功能 (稱為「Gemini in Firebase」)。
6. 本程式碼研究室不需要 Google Analytics，因此請關閉 Google Analytics 選項。
7. 按一下「建立專案」，等待專案佈建完成，然後按一下「繼續」。

恭喜！您已建立 Firebase 專案。

3. 平台專屬的 Firebase 應用程式設定

啟用 Firebase 支援功能所需的大部分程式碼變更，都已簽入您正在處理的專案。不過，如要新增行動平台支援功能，請按照下列步驟操作：

• 在 Firebase 專案中註冊所需平台
• 下載平台專屬的設定檔，並將其新增至程式碼。

在本程式碼研究室中，我們將新增 Android Firebase 應用程式。

設定 Android

1. 在 Firebase 控制台中，選取「設定」齒輪左側導覽列頂端的「專案設定」，然後點選「一般」頁面「您的應用程式」下方的「Android」圖示。

您應該會看到下列對話方塊：

2. 請務必提供Android 套件名稱。將其設定為 com.ticker.stocknews。
   1. 這裡提供的套件名稱必須與啟動器 AndroidManifest.xml 中 StockNewsApp 程式碼提供的名稱相同。如要尋找或變更這項設定，請按照下列步驟操作：
      1. 在 StockNewsApp 目錄中，開啟 app/src/main/AndroidManifest.xml 檔案。
      2. 在 manifest 元素中，找出 package 屬性的字串值。這個值是 Android 套件名稱。

3. 在 Firebase 對話方塊中，將複製的套件名稱貼到「Android 套件名稱」欄位。
4. 由於這個應用程式不會發布，因此您不需要本程式碼研究室的「偵錯簽署憑證 SHA-1」。請將此處留空。
5. 按一下「註冊應用程式」。
6. 繼續在 Firebase 控制台中操作，按照指示下載設定檔 google-services.json。
7. 其餘設定步驟可以略過，因為所有其他設定都已在入門應用程式程式碼中設定。Firebase 主控台的主頁面會列出您的應用程式。
8. 將剛才下載的 google-services.json 檔案複製到 messaging/fcm-topics-codelab/starter/StockNewsApp/app 目錄。

4. 建構並執行應用程式

您已準備好實際開始開發應用程式！首先，請建構並執行應用程式。

匯入範例應用程式

啟動 Android Studio，然後從範例程式碼目錄匯入 messaging/fcm-topics-codelab/starter/StockNewsApp。

專案載入後，系統也可能會顯示快訊，通知您 Git 不會追蹤所有本機變更。您可以按一下「Ignore」或右上方的「X」圖示 (系統不會將任何變更推送回 Git 存放區。)

如果您在「Android」檢視畫面中，專案視窗的左上角會顯示如下圖所示的項目 (在「Project」檢視畫面中，您必須展開專案才能看到這些項目)

請注意，由於 Android Studio 首次會在背景編譯專案，因此可能需要幾秒鐘的處理時間。在此期間，Android Studio 底部的狀態列會顯示旋轉圖示：

建議您等到此動作完成後再變更程式碼。這使 Android Studio 提取所有必要的元件。

此外，如果畫面顯示「Reload for language changes to take effect?」的提示或類似內容，請選取「Yes」。

模擬器設定

如需設定 Android 模擬器的相關說明，請參閱「執行應用程式」一文。

瞭解 Android 應用程式範例程式碼

• 範例程式碼是輕量型 Android 應用程式，功能和 UI 很少。
• app/build.gradle 檔案中已新增 firebase-messaging SDK 的依附元件。

• AndroidManifest.xml 中已新增 MESSAGING_EVENT 回呼處理常式。
  • 這個處理常式 StockNewsMessagingService.java 會擴充 FirebaseMessagingService 類別，提供各種 Firebase 雲端通訊相關功能。詳情請參閱 FirebaseMessagingService 說明文件。
  
  • 建立或重新整理 FCM 註冊權杖時，系統會呼叫 onNewToken 函式。詳情請參閱「監控權杖產生作業」。
  • 應用程式在前景運作時收到訊息，就會呼叫 onMessageReceived 函式。目前只會記錄收到的訊息。
    • 如要進一步瞭解背景和前景訊息傳送及處理方式的差異，請參閱「在 Android 應用程式中接收訊息」。
• 此外，在 AndroidManifest.xml 中，也提供名為 StockNewsApplication 的 Android Application 類別。
  • 應用程式啟動時，系統會先例項化這個類別。
  • 在 StockNewsApplication 類別的 onCreate 函式中，新增 FCM 註冊權杖建立呼叫。這會產生有效的 FCM 註冊權杖並記錄。
• MainActivity.java 會新增 RecyclerView，顯示股票類別選項。
• SubscriptionAdapter.java 實作 RecyclerView.Adapter，用於繪製「股票類別」選取畫面。
  • 每個股票類別都有名稱，旁邊會顯示訂閱切換按鈕。
  • 切換切換鈕時，系統應會發出 FCM 主題訂閱 / 取消訂閱呼叫。
  • 您將在後續章節中實作這些呼叫。
• model/StockCategories.java 類別包含所有股票類別及其相關主題名稱的清單。

執行範例應用程式

1. 將 Android 裝置連接到電腦，或啟動模擬器。
2. 在頂端工具列中，選取目標 Android 裝置或模擬器，然後按下執行按鈕。

3. 應用程式 UI 如下所示：

4. 應用程式會建立 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 註冊權杖。

設定伺服器程式碼

1. 首先，我們需要設定 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 檔案。
2. 此時，伺服器程式碼已準備就緒。從頂端選單列執行「Build」->「Build Project」。

傳送測試訊息

1. 在 FcmSender.java 中找到 sendMessageToFcmRegistrationToken 函式，然後將從「執行範例應用程式」一節複製的 FCM 註冊權杖插入 registrationToken 欄位。
2. 在 main 函式中，取消註解 sendMessageToFcmRegistrationToken 函式，然後按一下「執行」執行程式碼。
   1. 請注意 FCM 註冊權杖是如何設定到 message 物件的 Token 欄位中。
   2. 此外，請注意我們如何使用 FirebaseMessaging 介面的 send API。

3. 這時，您在上一個步驟中設定的應用程式執行個體應該會收到訊息。
4. 應用程式執行個體位於前景時，您應該會看到記錄的訊息內容。

5. 如果應用程式執行個體處於背景，您會在通知匣中看到這則訊息。

太棒了！您已使用 Firebase Admin SDK 將訊息傳送至應用程式例項。進一步瞭解如何在伺服器中使用 Firebase Admin SDK。

6. 實作主題訂閱 / 取消訂閱功能

在這個步驟中，您將在 Android 應用程式的「股票類別」切換按鈕上，實作主題訂閱和取消訂閱動作。

當應用程式使用者切換特定股票類別的開關時，系統會發出主題訂閱或取消訂閱呼叫。

審查代碼

• 前往 Android 應用程式程式碼中的 SubscriptionAdapter.java 類別，找出 RecyclerViewViewHolder 類別。

• 類別建構函式會使用 setOnCheckedChangeListener 設定訂閱切換的監聽器。
• 視切換鈕的狀態而定，系統會分別呼叫 subscribeToStockCategory 和 unsubscribeFromStockCategory 方法，執行訂閱和取消訂閱動作。
• RecyclerView 轉接器的 onBindViewHolder 會呼叫 setData 方法，將 ViewHolder 繫結至適當的股票類別。

導入主題訂閱功能

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 的方法。

2. 在第一行中，提供要傳送訊息的 FCM 主題。
   • 這是 /topics/<Topic Name> 形式的字串。例如：/topics/Technology。
3. 在接下來的幾行中，建立新的 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();

4. 現在，請新增對 FirebaseMessaging 例項的呼叫，傳送訊息 (與 sendMessageToFcmRegistrationToken 函式中進行的傳送呼叫相同)。

FirebaseMessaging.getInstance().send(message);

5. 最後，更新 main 函式，並只啟用對 sendMessageToFcmTopic 函式的呼叫。

傳送訊息並驗證回條

1. 傳送主題訊息前，請先確認應用程式例項已訂閱要傳送訊息的主題。
   1. 只要切換對應的切換鈕即可。例如：
   
2. 您現在可以執行 FcmSender.java 的 main 函式，傳送主題訊息。
3. 與先前一樣，您應該可以在應用程式例項中觀察到訊息接收情形。
   1. 應用程式執行個體在前景中
   
   2. 在背景執行的應用程式執行個體
   
4. 額外提示：取消訂閱你傳送訊息的主題，然後重新傳送訊息。您會發現訊息未傳送至應用程式例項。

8. 傳送第一則主題條件訊息

主題條件功能可讓您將訊息傳送至多個主題，以便更清楚地定義目標對象。

舉例來說，在 StockNews 應用程式中，您可以考慮向訂閱「科技」或「汽車」主題的應用程式執行個體群組傳送訊息。舉例來說，如果發生與 Waymo 相關的重大事件，就可能出現這種情況。

主題可讓您使用下列運算子，以布林運算式的形式表示組合

• &&：邏輯 AND。舉例來說，'Technology' in topics && 'Automotive' in topics - 只會將目標設為同時訂閱「科技」和「汽車」主題的應用程式例項。
• ||：邏輯 OR。舉例來說，'Technology' in topics || 'Automotive' in topics - 指定訂閱「技術」或「汽車」主題的應用程式例項。
• ()：用於分組的半形括號。舉例來說，'Technology' in topics && ('Automotive' in topics || 'Energy' in topics) - 只會將目標設為訂閱「技術」和「汽車」或「能源」主題的應用程式例項。

進一步瞭解如何建立傳送要求，以使用這項功能。

導入伺服器端整合，傳送主題條件訊息

1. 回到伺服器程式碼，跳至 FcmSender.java 並找出名為 sendMessageToFcmTopicCondition 的方法。

2. 在第一行中，針對 topicCondition 變數，提供要傳送訊息的主題條件。你可以將其設為：'Technology' in topics && 'Automotive' in topics。
3. 在接下來的幾行中，建立新的 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();

4. 現在，請新增對 FirebaseMessaging 例項的呼叫，傳送訊息 (與 sendMessageToFcmTopic 函式中進行的傳送呼叫相同)。

FirebaseMessaging.getInstance().send(message);

5. 最後，更新 main 函式，並只啟用對 sendMessageToFcmTopicCondition 函式的呼叫。

傳送訊息並驗證收據

1. 傳送主題訊息前，請先將應用程式例項訂閱「Technology」和「Automotive」主題，確保應用程式例項符合指定主題條件。
2. 您現在可以執行 FcmSender.java 的 main 函式，傳送主題訊息。
3. 與先前一樣，您應該可以在應用程式例項中觀察到訊息收據。
   1. 應用程式執行個體在前景中
   
   2. 在背景執行的應用程式執行個體
   
4. 額外步驟：現在你可以取消訂閱「技術」主題，然後重新傳送主題條件訊息。您應該會發現應用程式執行個體未收到訊息。

9. 重點回顧

現在快速回顧一下您目前學到的內容。

• 如何從應用程式例項啟動 / 取消主題訂閱。
• 將訊息傳送至主題，並在已訂閱的應用程式執行個體上驗證訊息是否已送達。
• 將訊息傳送至主題條件，並在符合條件的應用程式執行個體上驗證接收情形。

在下一節中，您將瞭解如何訂閱 / 取消訂閱主題的應用程式例項，而不必從用戶端例項化呼叫。

10. 從伺服器端管理主題訂閱項目

到目前為止，在本程式碼研究室中，所有主題訂閱和取消訂閱呼叫都是從應用程式例項啟動。

不過，在某些情況下，您可能想從伺服器端管理主題訂閱項目。舉例來說，您可能想讓現有使用者群組的子群組訂閱新主題，不必等到應用程式推出。

在本節中，您將瞭解如何使用 Firebase Admin SDK，從伺服器端發出呼叫，將一批 FCM 註冊權杖訂閱及取消訂閱主題。

實作 FCM 註冊權杖的伺服器端訂閱作業，訂閱 FCM 主題

1. 在伺服器程式碼中，跳到 FcmSubscriptionManager.java 類別。找出名為 subscribeFcmRegistrationTokensToTopic 的方法。您將在這裡實作對 subscribeToTopic API 的呼叫。

2. 現在，我們將應用程式執行個體訂閱至「Energy」主題。如要這麼做，請先提供下列兩個欄位的資料：
   1. registrationTokens：以逗號分隔的字串清單，代表您要建立主題訂閱項目的 FCM 註冊權杖。
   2. topicName：能源主題的主題名稱，即 /topics/Energy。
3. 在接下來的幾行中，實作呼叫，如下所示：

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

4. 您可以檢查 TopicManagementResponse，查看一些高階結果統計資料。例如使用 getSuccessCount 列印成功建立的主題訂閱項目數量。

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

5. 最後，在 main 函式中，只允許呼叫 subscribeFcmRegistrationTokensToTopic 函式。

建立訂閱項目並傳送主題訊息

1. 此時，您已準備好建立主題訂閱項目，並傳送訊息至該項目。
2. 執行 FcmSubscriptionManager.java 類別的 main 函式。系統會建立主題訂閱項目。
3. 現在請設定程式碼來傳送訊息。與先前類似，
   1. 在 FcmSender.java 中找出 sendMessageToFcmTopic 函式。
   2. 將 topicName 設為「能源」主題，也就是 /topics/Energy。
   3. 建立 Message 物件，並使用 setTopic 將其設為主題目標。
   4. 最後，更新 main 方法，只啟用 sendMessageToFcmTopic 函式。
4. 執行 FcmSender.java 的 main 函式。這會將訊息傳送至應用程式例項，您可以在應用程式中觀察訊息，如下所示。
   1. 應用程式執行個體在前景中
   
   2. 在背景執行的應用程式執行個體
   

導入 FCM 註冊權杖的伺服器端取消訂閱功能，以便取消訂閱 FCM 主題

1. 如要從伺服器端取消訂閱主題，請使用 unsubscribeFromTopic API。您會在 FcmSubscriptionManager.java 類別的 unsubscribeFcmRegistrationTokensFromTopic 函式中加入相關程式碼。

2. 請自行實作伺服器端取消訂閱程式碼，並傳送主題訊息來驗證其效果。

11. 恭喜

恭喜！您已成功使用 FCM 主題，將多播訊息傳送至應用程式執行個體的子群組。這有助於您及時向使用者提供相關內容。

後續步驟

您已完成本程式碼研究室，現在不妨參考下列指南，試試其他平台的相關主題：

• iOS 適用的 FCM 主題
• 網頁版 FCM 主題

參考文件

• Android API 參考資料 ( Java / Kotlin)
• iOS API 參考資料 ( ObjectiveC / Swift)
• JavaScript API 參考資料 ( 第 9 版 / 第 8 版)
• Admin SDK 參考資料 ( Node.js / Java / Python / .NET)