Android Kotlin 项目集成 Firebase Cloud Messaging (FCM) 全攻略

tangweiguo030519872025-05-02 15:18

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

kotlin 复制代码 
// 在项目级的 build.gradle 文件中添加：
buildscript {
    dependencies {
        // 添加 Google Services 插件
        classpath 'com.google.gms:google-services:4.3.15'
    }
}

2. 应用级 build.gradle

kotlin 复制代码 
// 在应用级的 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

kotlin 复制代码 
import android.util.Log
import com.google.firebase.messaging.FirebaseMessagingService
import com.google.firebase.messaging.RemoteMessage

class 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 中注册服务

xml 复制代码 
<service
    android:name=".MyFirebaseMessagingService"
    android:exported="false">
    <intent-filter>
        <action android:name="com.google.firebase.MESSAGING_EVENT" />
    </intent-filter>
</service>

四、获取设备令牌

1. 创建 FCM 管理器类

kotlin 复制代码 
import android.util.Log
import com.google.firebase.messaging.FirebaseMessaging
import kotlinx.coroutines.tasks.await

object 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. 在应用启动时获取令牌

kotlin 复制代码 
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

kotlin 复制代码 
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 中配置

xml 复制代码 
<activity
    android: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 命令测试

bash 复制代码 
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 中添加元数据：

      xml 复制代码 
      <meta-data
    android:name="com.google.firebase.messaging.default_notification_icon"
    android:resource="@drawable/ic_notification" />

八、最佳实践

  1. 令牌管理：

    • 每次应用启动时检查令牌
    • 在 onNewToken 中及时更新服务器上的令牌

  2. 消息处理：

    • 区分数据消息和通知消息
    • 对于重要消息，考虑添加 WorkManager 任务确保处理

  3. 用户体验：

    • 为通知设置合适的渠道
    • 提供清晰的点击行为

  4. 安全性：

    • 使用 HTTPS 传输令牌
    • 在服务器端验证消息来源

通过以上步骤，你的 Android Kotlin 应用已经成功集成了 FCM 推送通知功能。你可以根据需要进一步扩展功能，如实现富媒体通知、分组通知等高级特性。

相关推荐
饭小猿人4 小时前
Android 腾讯X5WebView如何禁止系统自带剪切板和自定义剪切板视图
android·java
_李小白4 小时前
【android opencv学习笔记】Day 8: remap（像素位置重映射）
android·opencv·学习
美狐美颜SDK开放平台5 小时前
多场景美颜SDK解决方案：直播APP（iOS/安卓）开发接入详解
android·人工智能·ios·音视频·美颜sdk·第三方美颜sdk·短视频美颜sdk
嗷o嗷o5 小时前
Android BLE 里，MTU、分包和长数据发送到底该怎么处理
android
胡致和5 小时前
配置变更后，弹窗为什么飞到了最左边？
kotlin
Gary Studio7 小时前
Android AIDL HAL工程结构示例
android
y = xⁿ7 小时前
MySQL八股知识合集
android·mysql·adb
andr_gale8 小时前
04_rc文件语法规则
android·framework·aosp
祖国的好青年9 小时前
VS Code 搭建 React Native 开发环境（Windows 实战指南）
android·windows·react native·react.js
热门推荐
01GitHub 镜像站点02Codex 接入 DeepSeek API 完整配置文档032026年4月AI大事件深度解读：大模型竞争进入“深水区“04近期有什么ai的新消息，新动态？ 2026.4月05【AI】2026 年具身智能模型和世界模型总结062026年AI编程工具终极横评：Cursor vs Claude Code vs Copilot07实测可用｜小米 MiMo 百万亿 Token 免费领，开发者速冲08在Windows 11上安装Docker的踩坑记录09裂开！ChatGPT 居然开始要手机号验证，附详细解决方法10零基础教你claude code 接入 deepseek V4