一、簡介
目標
在此 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
。- 此處提供的套件名稱必須與入門StockNewsApp程式碼的
AndroidManifest.xml
中提供的套件名稱相同。如果您想找到或更改它,請按照下列步驟操作:- 在StockNewsApp目錄中,開啟檔案
app/src/main/AndroidManifest.xml
。 - 在
manifest
元素中,尋找package
屬性的字串值。該值是 Android 套件名稱。
- 在StockNewsApp目錄中,開啟檔案
- 此處提供的套件名稱必須與入門StockNewsApp程式碼的
- 在 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
的AndroidApplication
類別。- 該類別將是應用程式啟動時第一個被實例化的類別。
- 在
StockNewsApplication
類別的onCreate
函數中,新增了 FCM 註冊令牌建立呼叫。它將產生有效的 FCM 註冊令牌並記錄它。
-
MainActivity.java
新增了顯示 Stock Category 選擇的RecyclerView
。 -
SubscriptionAdapter.java
實作RecyclerView.Adapter
,它會繪製股票類別選擇畫面。- 每個股票類別都有一個名稱和旁邊的訂閱切換開關。
- 更改切換應該會發出 FCM 主題訂閱/取消訂閱呼叫。
- 您將在接下來的部分中實作這些呼叫。
-
model/StockCategories.java
類別包含所有股票類別及其關聯主題名稱的清單。
運行啟動應用程式
- 將 Android 裝置連接到電腦或啟動模擬器。
- 在頂部工具列中,選擇您的目標 Android 裝置或模擬器,然後按運行按鈕。
- 應用程式 UI 將如下所示:
- 該應用程式將建立 FCM 註冊令牌並記錄它。但是應用程式 UI 不會發生任何變化。
- 複製並保存 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。
- 前往 Firebase 控制台,點擊左側導覽列中「項目概述」旁邊的齒輪圖標,然後選擇「項目設定」 。
- 在設定頁面中,選擇服務帳戶並點選建立服務帳戶。
- 現在點擊「產生新的私鑰」按鈕,將開始自動下載金鑰檔案。
- 將金鑰檔案重新命名為
service-account.json
並將其複製到messaging/fcm-topics-codelab/starter/StockNewsServer/src/main/resources
資料夾中。 -
FcmSender.java
和FcmSubscriptionManager.java
使用以下程式碼從類別路徑載入service-account.json
檔案。
- 至此,服務端程式碼就準備好了。從頂部功能表列運行“構建”->“構建項目”。
發送測試訊息
- 在
FcmSender.java
中,找到sendMessageToFcmRegistrationToken
函數,並將您從執行入門應用程式部分複製的 FCM 註冊令牌插入到registrationToken
欄位中。 - 在
main
函數中,僅取消註解sendMessageToFcmRegistrationToken
函數,然後按一下執行來執行程式碼。- 觀察如何將 FCM 註冊令牌設定到
message
物件的Token
欄位中。 - 此外,請注意我們如何使用
FirebaseMessaging
介面的send
API。
- 觀察如何將 FCM 註冊令牌設定到
- 這應該會向您在上一步中設定的應用程式實例發送一條訊息。
- 當應用程式實例位於前台時,您應該會看到記錄的訊息內容。
- 當應用程式實例處於背景時,您會看到通知托盤中出現該訊息。
太棒了,您使用 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
函數中定義的物件)。- 不同之處在於,您將設定
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();
- 現在新增對
FirebaseMessaging
實例的呼叫以傳送訊息(與sendMessageToFcmRegistrationToken
函數中進行的傳送呼叫相同)。
FirebaseMessaging.getInstance().send(message);
- 最後,更新
main
函數並啟用僅呼叫sendMessageToFcmTopic
函數。
發送訊息並驗證接收
- 在發送主題訊息之前,首先確保您的應用程式實例已訂閱您要傳送到的主題。
- 這可以透過翻轉相應的開關來完成。例如:
- 現在您可以透過執行
FcmSender.java
的main
函數來傳送主題訊息。 - 像以前一樣,您應該能夠觀察應用程式實例上的消息接收。
- 前台應用程式實例
- 後台應用程式實例
- 獎勵:嘗試取消訂閱您發送到的主題並重新發送訊息。您會發現訊息沒有傳遞到應用程式實例。
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
函數中定義的物件)。- 區別在於您將設定
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
函數來傳送主題訊息。 - 像以前一樣,您應該能夠觀察應用程式實例上的消息接收。
- 前台應用程式實例
- 後台應用程式實例
- 獎勵:您現在可以取消訂閱技術主題並重新發送主題條件訊息。您應該觀察到應用程式實例沒有收到該訊息。
9. 回顧
讓我們快速回顧一下到目前為止您所學到的內容。
- 如何從應用程式實例發起主題訂閱/取消訂閱。
- 向主題發送訊息並驗證訂閱的應用程式實例的接收。
- 向主題條件發送訊息並驗證滿足條件的應用程式實例上的接收。
在下一節中,您將了解如何訂閱/取消訂閱應用程式實例的主題,而無需從客戶端實例化呼叫。
10.從伺服器端管理主題訂閱
到目前為止,在此 Codelab 中,所有主題訂閱和取消訂閱呼叫都是從應用程式實例發起的。
但是,在某些用例中,您可能希望從伺服器端管理主題訂閱。例如,您可能希望為現有用戶群的一部分訂閱新主題,而無需等待應用程式推出。
在本部分中,您將了解如何使用 Firebase Admin SDK透過從伺服器端進行呼叫來訂閱和取消訂閱主題的一批 FCM 註冊令牌。
實現 FCM 註冊令牌的伺服器端訂閱到 FCM 主題
- 在伺服器程式碼中,跳到
FcmSubscriptionManager.java
類別。找到名為subscribeFcmRegistrationTokensToTopic
的方法。您將在此處實作對subscribeToTopic
API 的呼叫。
- 讓我們將應用程式實例訂閱 Energy 主題。為此,首先為以下兩個欄位提供資料:
-
registrationTokens
:以逗號分隔的字串列表,表示您要為其建立主題訂閱的 FCM 註冊令牌。 -
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
函數。這將建立一個主題訂閱。 - 現在,設定發送訊息的代碼。與之前類似,
- 在
FcmSender.java
中,找到sendMessageToFcmTopic
函數。 - 將
topicName
設定為 Energy 主題,即/topics/Energy
。 - 建立一個
Message
物件並使用setTopic
將其定位到主題。 - 最後,更新
main
方法以僅啟用sendMessageToFcmTopic
功能。
- 在
- 執行
FcmSender.java
的main
函數。這會將訊息發送到您的應用程式實例,您可以在應用程式中觀察它,如下所示。- 前台應用程式實例
- 後台應用程式實例
實施伺服器端取消訂閱 FCM 註冊令牌到 FCM 主題
- 對於伺服器端主題取消訂閱,請使用此
unsubscribeFromTopic
API。您將相關程式碼加入FcmSubscriptionManager.java
類別的unsubscribeFcmRegistrationTokensFromTopic
函數中。
- 實作伺服器端取消訂閱代碼並透過傳送主題訊息驗證其效果,留給您作為練習。
11.恭喜你
恭喜您已成功使用 FCM 主題將多播訊息傳送到應用程式實例的子群組。這將有助於簡化您向用戶及時提供相關內容的能力。
下一步是什麼?
現在您已經完成了 Codelab,請考慮使用以下指南嘗試其他平台的主題: