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

1. 簡介

目標

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

完成後，您就能使用 FCM 基礎架構管理這些子群組，以及對子群組進行多點傳播推送訊息。

主題總覽

「主題」是 FCM 基礎架構的支援，可透過訊息觸及應用程式執行個體的子群組。

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

主題應用於公開內容。例如最新天氣資訊的訊息。如要傳送使用者俱敏感性的訊息，請使用 Firebase Admin SDK 在多部裝置上透過多部傳播訊息傳送訊息。

以主題為基礎的多點傳播已最佳化處理量。

課程內容

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

建構項目

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

軟硬體需求

  • 您選擇的瀏覽器，例如 Chrome。
  • 用於開發 Java 應用程式的 IntelliJ IDEA IDE。
    • 請務必在安裝時選擇使用 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. 在 Firebase 控制台，按一下「新增專案」，將 Firebase 專案命名為「StockNews」，然後點選「繼續」。注意：請記下 Firebase 專案的專案 ID (或按一下「編輯」圖示設定您偏好的專案 ID)。

fc08f9a7808e4553.png

  1. 您可以略過啟用 Google Analytics 的步驟。就本程式碼研究室而言，您不需要這麼做。按一下「繼續」。
  2. 按一下 [Create Project]。

恭喜！Firebase 專案已經建立好了，現在只要按一下專案名稱，就能進入控制台。

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

啟用 Firebase 支援功能所需的大部分程式碼變更，都已寫入您正在進行的專案。不過，若要新增行動平台支援，您必須：

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

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

84e0b3199bef6d8a.png設定 Android

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

畫面上應會顯示下列對話方塊：8254fc299e82f528.png

  1. 請務必提供 Android 套件名稱。設為 com.ticker.stocknews。
    1. 在這裡提供的套件名稱必須與啟動條件 StockNewsApp 程式碼啟動條件中的 AndroidManifest.xml 相同。如果您想要找到或變更它，請按照下列步驟進行：
      1. 在 StockNewsApp 目錄中，開啟 app/src/main/AndroidManifest.xml 檔案。
      2. 在 manifest 元素中，找出 package 屬性的字串值。這個值是 Android 套件名稱。
  1. 在 Firebase 對話方塊中，將複製的套件名稱貼到「Android package name」欄位。
  2. 您不需要在本程式碼研究室中發布偵錯簽署憑證 SHA-1，因為這個應用程式不會發布。將此欄位留白。
  3. 按一下「Register App」。
  4. 繼續前往 Firebase 控制台，按照操作說明下載設定檔 google-services.json。
  5. 您可以略過其餘的設定步驟，因為範例應用程式程式碼中已完成其他設定。您可以在 Firebase 控制台主頁面找到您的應用程式。
  6. 將剛才下載的 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」檢視畫面中，您必須展開專案才能看到這些項目)。

b574ea0089ee87c6.png

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

4bc64eb3b99eb0ae.png

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

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

模擬器設定

如需設定 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 中也會提供 Android Application 類別 StockNewsApplication。a4982a8731492dfc.pngccde692f7f68dc5a.png
    • 此類別將是應用程式啟動時要例項化的第一個類別。
    • 在 StockNewsApplication 類別的 onCreate 函式中，系統會新增 FCM 註冊權杖建立呼叫。系統會產生有效的 FCM 註冊權杖並加以記錄。
  • MainActivity.java 會新增顯示「股票類別」選項的 RecyclerView。
  • SubscriptionAdapter.java 會實作 RecyclerView.Adapter 來繪製「股票類別」選取畫面。
    • 每個股票類別旁邊都有名稱和訂閱切換按鈕。
    • 變更切換鈕應會啟動 FCM 主題訂閱 / 取消訂閱呼叫。
    • 您將在接下來的幾節中實作這些呼叫。
  • model/StockCategories.java 類別包含所有股票類別及其相關主題名稱的清單。

b32663ec4e865a18.png

執行範例應用程式

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

5b27fc5b237e06b9.png

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

ff5b1a1c53231c54.png

  1. 應用程式會建立並記錄 FCM 註冊權杖。不過，應用程式 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

  • 最後，總共有兩個類別，viz：
    • 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 控制台，按一下左側導覽列「專案總覽」旁的齒輪圖示，然後選取「專案設定」。8c2108d4d7c915e9.png
    2. 在設定頁面中，選取「服務帳戶」，然後點選「建立服務帳戶」。84b128cc5dac0a85.png
    3. 接著點選「產生新的私密金鑰」按鈕，系統就會開始自動下載金鑰檔案。
    4. 將金鑰檔案重新命名為 service-account.json，並複製到 messaging/fcm-topics-codelab/starter/StockNewsServer/src/main/resources 資料夾中。
    5. FcmSender.java 和 FcmSubscriptionManager.java 都使用下列程式碼，從類別路徑載入 service-account.json 檔案。8dffbee658e0bdd.png
  2. 此時，伺服器程式碼已就緒。執行建構 ->從頂端選單列建構專案。

傳送測試訊息

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

52e4a3ec3f816473.png

  1. 系統應會傳送訊息至您在上一個步驟中設定的應用程式執行個體。
  2. 當應用程式執行個體在前景運作時，系統應會記錄訊息內容。

d3540ec1089f97dd.png

  1. 當應用程式執行個體在背景運作時，您會發現通知匣中會顯示此訊息。

31203deca59c03fe.png

太棒了，您使用了 Firebase Admin SDK 來傳送訊息至應用程式執行個體。進一步瞭解如何在伺服器中使用 Firebase Admin SDK。

6. 導入主題訂閱 / 取消訂閱

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

應用程式使用者將特定「股票類別」的切換鈕撥到切換鈕時，就會觸發主題訂閱或取消訂閱的通話。

查看程式碼

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

6c0614199e684f6.png

  • 類別建構函式使用 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. 同樣地，在其他條件中，您會實作對 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 發生值得關注的事件，就可能屬於這類情況。

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

  • (&&)：邏輯 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 的方法。

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. 回顧

讓我們快速回顧一下目前為止學到的知識。

  • 如何透過應用程式執行個體啟動主題訂閱 / 取消訂閱作業。
  • 傳送訊息給主題，並在訂閱的應用程式執行個體上驗證接收。
  • 傳送訊息至主題 Condition，並在符合條件的應用程式執行個體上驗證接收。

下一節將說明如何訂閱 / 取消訂閱應用程式主題，而不必從用戶端將呼叫例項化。

c0dc20655d392690.gif

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

目前，在本程式碼研究室中，所有主題訂閱和取消訂閱呼叫都是從應用程式執行個體發出。

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

本節將說明如何使用 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 設為「能源」主題，例如/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

後續步驟

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

參考文件