您的第一個使用 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 控制台中,按一下新增項目,將 Firebase 項目命名為StockNews ,然後按一下繼續。注意:記住您的 Firebase 項目的項目 ID(或點擊編輯圖示以設定您的首選項目 ID)。

fc08f9a7808e4553.png

  1. 您可以跳過啟用 Google Analytics。就本 Codelab 而言,您不需要它。單擊繼續。
  2. 點選建立項目

恭喜!您剛剛建立了 Firebase 專案。現在,您可以點擊項目名稱進入控制台。

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

啟用 Firebase 支援所需的大部分程式碼變更已簽入您正在處理的專案中。但是,為了添加對行動平台的支持,您需要:

  • 在 Firebase 專案上註冊所需的平台
  • 下載特定於平台的配置文件,並將其添加到程式碼中。

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

84e0b3199bef6d8a.png設定安卓

  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 套件名稱欄位中。
  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,並從起始代碼目錄匯入messaging/fcm-topics-codelab/starter/StockNewsApp

項目載入後,您可能還會看到一條警告,指出 Git 未追蹤所有本機更改,您可以按一下「忽略」或右上角的「 X 」。 (您不會將任何變更推送回 Git 儲存庫。)

如果您位於Android視圖中,則在專案視窗的左上角,您應該會看到如下圖所示的內容。 (如果您在專案視圖中,則需要展開專案才能看到相同的內容)

b574ea0089ee87c6.png

請注意,Android Studio 首次在背景編譯專案可能需要幾秒鐘的時間。在此期間,您將在 Android Studio 底部的狀態列中看到一個微調器:

4bc64eb3b99eb0ae.png

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

此外,如果您收到「重新載入以使語言變更生效?」的提示。或類似的內容,選擇「是」。

模擬器設定

如果您需要設定 Android 模擬器的協助,請參閱執行您的應用程式一文。

了解Android App啟動程式碼

  • 起始程式碼是一個輕量級 Android 應用程序,具有最少的功能和 UI。
  • firebase-messaging SDK 的依賴項已新增至app/build.gradle檔案。

f04ff8f48d186dff.png

  • AndroidManifest.xml中,已新增MESSAGING_EVENT回呼處理程序。
    • 此處理程序StockNewsMessagingService.java擴充了FirebaseMessagingService類,提供各種 Firebase Cloud Messaging 相關功能。請參閱FirebaseMessagingService 文件以了解更多資訊。 b843c4d33ee53166.png
    88fad1960f4a6ff5.png
    • 建立或重新整理 FCM 註冊令牌時將呼叫onNewToken函數。有關詳細信息,請參閱監視令牌生成
    • 當收到訊息並且應用程式位於前台時,將呼叫onMessageReceived函數。目前,它只是記錄收到的訊息。
  • 此外,在AndroidManifest.xml中,也提供了一個名為StockNewsApplicationAndroid Application類別a4982a8731492dfc.pngccde692f7f68dc5a.png
    • 該類別將是應用程式啟動時第一個被實例化的類別。
    • StockNewsApplication類別的onCreate函數中,新增了 FCM 註冊令牌建立呼叫。它將產生有效的 FCM 註冊令牌並記錄它。
  • MainActivity.java新增了顯示 Stock Category 選擇的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

  • 最後,有兩個類,分別是:
    • 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.javaFcmSubscriptionManager.java使用以下程式碼從類別路徑載入service-account.json檔案。 8dffbee658e0bdd.png
  2. 至此,服務端程式碼就準備好了。從頂部功能表列運行“構建”->“構建項目”。

發送測試訊息

  1. FcmSender.java中,找到sendMessageToFcmRegistrationToken函數,並將您從執行入門應用程式部分複製的 FCM 註冊令牌插入到registrationToken欄位中。
  2. main函數中,僅取消註解sendMessageToFcmRegistrationToken函數,然後按一下執行來執行程式碼。
    1. 觀察如何將 FCM 註冊令牌設定到message物件的Token欄位中。
    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為訂閱切換設定偵聽器。
  • 根據開關切換,訂閱和取消訂閱操作分別透過呼叫subscribeToStockCategoryunsubscribeFromStockCategory方法來執行。
  • setData方法由 RecyclerView Adapter 的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函數中定義的物件)。
    • 不同之處在於,您將設定Token字段,而不是設定message物件的Topic字段。
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. 區別在於您將設定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();
  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. 讓我們將應用程式實例訂閱 Energy 主題。為此,首先為以下兩個欄位提供資料:
    1. registrationTokens :以逗號分隔的字串列表,表示您要為其建立主題訂閱的 FCM 註冊令牌。
    2. topicName :Energy 主題的主題名稱,即/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

下一步是什麼?

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

參考文檔