Firebase Cloud Messaging (FCM) 是 Google 提供的跨平臺消息推送解決方案。以下是在 Android Kotlin 項目中集成 FCM 的詳細步驟。

一、前期準備

1. 創建 Firebase 項目

1. 訪問 Firebase 控制臺
2. 點擊"添加項目"，按照向導創建新項目
3. 項目創建完成后，點擊"添加應用"選擇 Android 應用

2. 獲取配置文件

1. 輸入應用的包名（必須與 build.gradle 中的 applicationId 一致）
2. 下載 google-services.json 文件
3. 將該文件放到項目的 app 模塊根目錄下

二、項目配置

1. 項目級 build.gradle

// 在項目級的 build.gradle 文件中添加：
buildscript {dependencies {// 添加 Google Services 插件classpath 'com.google.gms:google-services:4.3.15'}
}

2. 應用級 build.gradle

// 在應用級的 build.gradle 文件頂部添加：
plugins {id 'com.android.application'id 'kotlin-android'id 'com.google.gms.google-services' // 添加這行
}dependencies {// FCM 核心庫implementation 'com.google.firebase:firebase-messaging:23.2.1'// 可選 - Kotlin 協程支持implementation 'org.jetbrains.kotlinx:kotlinx-coroutines-android:1.6.4'implementation 'org.jetbrains.kotlinx:kotlinx-coroutines-play-services:1.6.4'// 可選 - 用于處理后臺消息implementation 'androidx.work:work-runtime-ktx:2.8.1'
}

三、實現 FCM 服務

1. 創建自定義 FirebaseMessagingService

import android.util.Log
import com.google.firebase.messaging.FirebaseMessagingService
import com.google.firebase.messaging.RemoteMessageclass MyFirebaseMessagingService : FirebaseMessagingService() {private val TAG = "FCM_Service"/*** 當收到新消息時調用*/override fun onMessageReceived(remoteMessage: RemoteMessage) {Log.d(TAG, "From: ${remoteMessage.from}")// 檢查消息是否包含數據負載if (remoteMessage.data.isNotEmpty()) {Log.d(TAG, "Message data payload: ${remoteMessage.data}")// 在這里處理數據消息handleDataMessage(remoteMessage.data)}// 檢查消息是否包含通知負載remoteMessage.notification?.let {Log.d(TAG, "Message Notification Body: ${it.body}")// 在這里處理通知消息handleNotification(it)}}/*** 當新令牌生成時調用*/override fun onNewToken(token: String) {Log.d(TAG, "Refreshed token: $token")// 將新令牌發送到你的應用服務器sendRegistrationToServer(token)}private fun handleDataMessage(data: Map<String, String>) {// 實現你的數據消息處理邏輯// 例如：更新UI、顯示通知等}private fun handleNotification(notification: RemoteMessage.Notification) {// 實現你的通知處理邏輯// 例如：顯示系統通知}private fun sendRegistrationToServer(token: String) {// 實現將令牌發送到你的應用服務器的邏輯}
}

2. 在 AndroidManifest.xml 中注冊服務

<serviceandroid:name=".MyFirebaseMessagingService"android:exported="false"><intent-filter><action android:name="com.google.firebase.MESSAGING_EVENT" /></intent-filter>
</service>

四、獲取設備令牌

1. 創建 FCM 管理器類

import android.util.Log
import com.google.firebase.messaging.FirebaseMessaging
import kotlinx.coroutines.tasks.awaitobject FCMManager {private const val TAG = "FCM_Manager"/*** 獲取當前 FCM 令牌*/suspend fun getToken(): String? {return try {FirebaseMessaging.getInstance().token.await().also { token ->Log.d(TAG, "FCM Token: $token")}} catch (e: Exception) {Log.e(TAG, "Failed to get FCM token", e)null}}/*** 訂閱主題*/fun subscribeToTopic(topic: String) {FirebaseMessaging.getInstance().subscribeToTopic(topic).addOnCompleteListener { task ->if (task.isSuccessful) {Log.d(TAG, "Subscribed to $topic")} else {Log.e(TAG, "Subscribe to $topic failed", task.exception)}}}/*** 取消訂閱主題*/fun unsubscribeFromTopic(topic: String) {FirebaseMessaging.getInstance().unsubscribeFromTopic(topic).addOnCompleteListener { task ->if (task.isSuccessful) {Log.d(TAG, "Unsubscribed from $topic")} else {Log.e(TAG, "Unsubscribe from $topic failed", task.exception)}}}
}

2. 在應用啟動時獲取令牌

class MainActivity : AppCompatActivity() {override fun onCreate(savedInstanceState: Bundle?) {super.onCreate(savedInstanceState)setContentView(R.layout.activity_main)// 獲取 FCM 令牌lifecycleScope.launch {val token = FCMManager.getToken()// 可以將 token 發送到你的服務器}// 訂閱主題示例FCMManager.subscribeToTopic("news")}
}

五、處理通知點擊

1. 創建通知點擊處理 Activity

class NotificationHandlerActivity : AppCompatActivity() {override fun onCreate(savedInstanceState: Bundle?) {super.onCreate(savedInstanceState)setContentView(R.layout.activity_notification_handler)// 處理從通知傳遞過來的數據intent.extras?.let { extras ->// 解析 extras 中的數據并處理val message = extras.getString("key")// 根據消息內容跳轉到相應頁面}// 關閉 Activity（如果是僅用于處理點擊）finish()}
}

2. 在 AndroidManifest.xml 中配置

<activityandroid:name=".NotificationHandlerActivity"android:exported="true"android:theme="@style/Theme.AppCompat.Translucent"><intent-filter><action android:name="android.intent.action.VIEW" /><category android:name="android.intent.category.DEFAULT" /></intent-filter>
</activity>

六、測試 FCM 功能

1. 使用 Firebase 控制臺測試

1. 在 Firebase 控制臺中選擇你的項目
2. 進入 Cloud Messaging 部分
3. 點擊"發送第一條消息"
4. 填寫通知標題、內容等
5. 選擇目標設備或主題
6. 發送測試消息

2. 使用 cURL 命令測試

curl -X POST \'https://fcm.googleapis.com/fcm/send' \-H 'Authorization: key=YOUR_SERVER_KEY' \-H 'Content-Type: application/json' \-d '{"to": "DEVICE_TOKEN","notification": {"title": "測試通知","body": "這是一條測試消息","click_action": ".NotificationHandlerActivity"},"data": {"key1": "value1","key2": "value2"}}'

七、常見問題解決

1. 收不到通知：

   • 檢查設備是否聯網
   • 確認 google-services.json 配置正確
   • 檢查應用是否被強制停止

2. 令牌獲取失敗：

   • 確保 Google Play 服務可用
   • 檢查設備是否支持 GMS

3. 后臺消息不觸發：

   • 確認服務已在 Manifest 中正確聲明
   • 檢查 Android 版本是否限制了后臺服務

4. 通知圖標不顯示：

   • 確保有默認通知圖標
   • 在 Manifest 中添加元數據：

     <meta-dataandroid:name="com.google.firebase.messaging.default_notification_icon"android:resource="@drawable/ic_notification" />
     

八、最佳實踐

1. 令牌管理：

   • 每次應用啟動時檢查令牌
   • 在 onNewToken 中及時更新服務器上的令牌

2. 消息處理：

   • 區分數據消息和通知消息
   • 對于重要消息，考慮添加 WorkManager 任務確保處理

3. 用戶體驗：

   • 為通知設置合適的渠道
   • 提供清晰的點擊行為

4. 安全性：

   • 使用 HTTPS 傳輸令牌
   • 在服務器端驗證消息來源

通過以上步驟，你的 Android Kotlin 應用已經成功集成了 FCM 推送通知功能。你可以根據需要進一步擴展功能，如實現富媒體通知、分組通知等高級特性。