一、簡介
目標
在此 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
文件。
- 轉到 Firebase 控制台,單擊左側導航欄中“項目概述”旁邊的齒輪圖標,然後選擇“項目設置” 。
- 至此,服務端代碼就準備好了。從頂部菜單欄運行“構建”->“構建項目”。
發送測試消息
- 在
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
函數中定義的對象)。- 不同之處在於,您
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
函數。
發送消息並驗證接收
- 在發送主題消息之前,首先確保您的應用實例已訂閱您要發送到的主題。
- 這可以通過翻轉相應的開關來完成。例如:
- 您現在可以通過執行
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,請考慮使用以下指南嘗試其他平台的主題: