一、簡介
目標
在此 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 控制台中,單擊Add project ,將 Firebase 項目命名為StockNews並單擊 continue。注意:記住您的 Firebase 項目的項目 ID(或點擊編輯圖標來設置您的首選項目 ID)。
- 您可以跳過啟用 Google Analytics。出於本 Codelab 的目的,您不需要它。單擊繼續。
- 單擊創建項目。
恭喜!您剛剛創建了 Firebase 項目。現在,您可以點擊項目名稱進入控制台。
3. 平台特定的 Firebase 應用配置
啟用 Firebase 支持所需的大部分代碼更改已簽入您正在處理的項目中。但是,為了添加對移動平台的支持,您需要:
- 在 Firebase 項目上註冊所需的平台
- 下載特定於平台的配置文件,並將其添加到代碼中。
出於本 Codelab 的目的,我們將添加一個 Android Firebase 應用。
配置安卓
- 在Firebase Console中,選擇 Settings cog 左側導航欄頂部的Project Settings ,然後單擊General頁面中Your apps下的Android圖標。
您應該看到以下對話框:
- 提供的重要值是Android 包名稱。將其設置為
com.ticker.stocknews
。- 此處提供的包名稱必須與您的 Starter StockNewsApp代碼的
AndroidManifest.xml
中提供的包名稱相同。如果您想找到或更改它,請按照下列步驟操作:- 在StockNewsApp目錄中,打開文件
app/src/main/AndroidManifest.xml
。 - 在
manifest
元素中,找到package
屬性的字符串值。此值是 Android 包名稱。
- 在StockNewsApp目錄中,打開文件
- 此處提供的包名稱必須與您的 Starter StockNewsApp代碼的
- 在 Firebase 對話框中,將復制的包名稱粘貼到Android 包名稱字段中。
- 您不需要此 Codelab 的調試簽名證書 SHA-1 ,因為此應用不會發布。將此留空。
- 單擊註冊應用程序。
- 繼續在 Firebase 控制台中,按照說明下載配置文件
google-services.json
。 - 您可以跳過其餘的設置步驟,因為其他所有內容都已在入門應用程序代碼中配置。您會在 Firebase 控制台的主頁上找到您的應用。
- 將
google-services.json
文件(您剛剛下載的)複製到messaging/fcm-topics-codelab/starter/StockNewsApp/app
目錄。
4. 構建並運行您的應用程序
您已經準備好開始實際使用您的應用程序了!首先,構建並運行應用程序。
導入入門應用
啟動 Android Studio,並從 starter 代碼目錄中導入messaging/fcm-topics-codelab/starter/StockNewsApp
。
項目加載後,您可能還會看到 Git 沒有跟踪您所有本地更改的警報,您可以單擊“忽略”或右上角的“ X ”。 (您不會將任何更改推送回 Git 存儲庫。)
在項目窗口的左上角,如果您在Android視圖中,您應該會看到類似下圖的內容。 (如果您在項目視圖中,則需要展開項目才能看到相同的內容)
請注意,Android Studio 第一次在後台編譯項目可能需要幾秒鐘的時間。在此期間,您將在 Android Studio 底部的狀態欄中看到一個微調器:
我們建議您等到完成後再進行代碼更改。這將允許 Android Studio 引入所有必要的組件。
此外,如果您收到提示“重新加載以使語言更改生效?”或類似的東西,選擇“是”。
模擬器設置
如果您在設置 Android 模擬器時需要幫助,請參閱運行您的應用一文。
了解 Android 應用啟動代碼
- 入門代碼是一個輕量級的 Android 應用程序,具有最少的功能和 UI。
- 對firebase-messaging SDK的依賴已添加到
app/build.gradle
文件中。
- 在
AndroidManifest.xml
中,已經添加了MESSAGING_EVENT
回調處理程序。- 此處理程序
StockNewsMessagingService.java
擴展了FirebaseMessagingService
類,該類提供各種與 Firebase 雲消息傳遞相關的功能。請參閱FirebaseMessagingService 文檔以了解更多信息。
- 創建或刷新 FCM 註冊令牌時調用
onNewToken
函數。有關詳細信息,請參閱監控令牌生成。 - 當收到消息並且應用程序處於前台時,將調用
onMessageReceived
函數。目前,它只是記錄收到的消息。- 請參閱在 Android 應用程序中接收消息,以了解有關後台和前台消息傳遞和處理之間差異的更多信息。
- 此處理程序
- 此外,在
AndroidManifest.xml
中,還提供了一個名為StockNewsApplication
的AndroidApplication
類。- 此類將是 App 啟動時第一個被實例化的類。
- 在
StockNewsApplication
類的onCreate
函數中,添加了 FCM 註冊令牌創建調用。它將生成一個有效的 FCM 註冊令牌並記錄它。
-
MainActivity.java
添加了顯示 Stock Category 選項的RecyclerView
。 -
SubscriptionAdapter.java
實現了繪製 Stock Category 選擇屏幕的RecyclerView.Adapter
。- 每個股票類別旁邊都有一個名稱和一個訂閱切換。
- 更改切換應進行 FCM 主題訂閱/取消訂閱調用。
- 您將在接下來的部分中實現這些調用。
-
model/StockCategories.java
類包含所有股票類別及其相關主題名稱的列表。
運行入門應用
- 將您的 Android 設備連接到計算機或啟動模擬器。
- 在頂部工具欄中,選擇您的目標 Android 設備或模擬器,然後按運行按鈕。
- 應用程序 UI 如下所示:
- 該應用程序將創建一個 FCM 註冊令牌並記錄它。但是,App 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 控制台,單擊左側導航欄中Project Overview旁邊的齒輪圖標,然後選擇Project settings 。
- 在設置頁面中,選擇服務帳戶,然後單擊創建服務帳戶。
- 現在單擊Generate new private key按鈕,將開始自動下載您的密鑰文件。
- 將密鑰文件重命名為
service-account.json
並將其複製到messaging/fcm-topics-codelab/starter/StockNewsServer/src/main/resources
文件夾中。 -
FcmSender.java
和FcmSubscriptionManager.java
都使用以下代碼從類路徑加載service-account.json
文件。
- 轉到 Firebase 控制台,單擊左側導航欄中Project Overview旁邊的齒輪圖標,然後選擇Project settings 。
- 至此,服務器代碼已準備就緒。從頂部菜單欄中運行 Build -> Build Project。
發送測試消息
- 在
FcmSender.java
找到sendMessageToFcmRegistrationToken
函數,並將您從Run the starter app部分複制的 FCM 註冊令牌插入到registrationToken
字段中。 - 在
main
函數中,只取消註釋sendMessageToFcmRegistrationToken
函數並單擊運行以執行代碼。- 觀察 FCM 註冊令牌是如何設置到
message
對象的Token
字段中的。 - 此外,請注意我們如何使用
FirebaseMessaging
接口的send
API。
- 觀察 FCM 註冊令牌是如何設置到
- 這應該會向您在上一步中設置的應用程序實例發送一條消息。
- 當應用程序實例處於前台時,您應該會看到記錄的消息內容。
- 當 App 實例在後台時,您會觀察到消息出現在通知托盤中。
太棒了,您使用 Firebase Admin SDK 向應用實例發送消息。閱讀有關在您的服務器中使用 Firebase Admin SDK 的更多信息。
6.實現主題訂閱/退訂
在此步驟中,您將在 Android 應用程序的 Stock Category 開關上實現主題訂閱和取消訂閱操作。
當 App 用戶切換特定股票類別的開關時,將進行主題訂閱或取消訂閱調用。
審核代碼
- 導航到 Android App 代碼中的
SubscriptionAdapter.java
類並找到RecyclerViewViewHolder
類。
- 類構造函數使用
setOnCheckedChangeListener
為訂閱切換設置監聽器。 - 根據切換開關,訂閱和取消訂閱操作分別通過調用
subscribeToStockCategory
和unsubscribeFromStockCategory
方法來執行。 -
setData
方法由 RecyclerView 適配器的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
函數中定義的對象)。- 不同之處在於您將設置
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();
- 現在添加對
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 的調用。
- 讓我們為應用實例訂閱能源主題。為此,首先為以下兩個字段提供數據:
-
registrationTokens
:一個逗號分隔的字符串列表,表示您要為其創建主題訂閱的 FCM 註冊令牌。 -
topicName
:能源主題的主題名稱,即/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 主題向應用實例的子組發送多播消息。這將有助於簡化您及時向用戶提供相關內容的能力。
下一步是什麼?
現在您已經完成了代碼實驗室,請考慮使用以下指南嘗試其他平台的主題: