FCM应用未运行时onMessageReceived未触发，求助解决方案

问题描述 #

使用FCM为Android应用推送通知，自定义了继承FirebaseMessagingService的PushService类并重写onMessageReceived方法，代码如下：

class PushService : FirebaseMessagingService() {
    override fun onMessageReceived(message: RemoteMessage) {
        var intent = Intent(applicationContext, MainActivity::class.java)
        intent.putExtra("KeyI", "It is") //Just a debug pair
        var pendingIntent = TaskStackBuilder.create(this)
            .run {
                addNextIntentWithParentStack(intent)
                getPendingIntent(
                    0, PendingIntent.FLAG_UPDATE_CURRENT or PendingIntent.FLAG_IMMUTABLE
                )
            }
        Log.d("Myy", Gson().toJson(message.notification))
        var notif = NotificationCompat.Builder(this, getString(R.string.notification_channel_id))
            .setContentText(message.notification?.body)
            .setSmallIcon(R.drawable.push_icon)
            .setAutoCancel(true)
            .setContentIntent(pendingIntent)
        if (Build.VERSION.SDK_INT < Build.VERSION_CODES.TIRAMISU) {
            NotificationManagerCompat.from(this)
                .notify(ServiceConstants.NOTIFICATION_ID, notif.build())
        } else {
            startForeground(ServiceConstants.NOTIFICATION_ID, notif.build())
        }
    }
}

应用运行时消息接收正常，MainActivity可获取Intent数据；但应用未运行时，点击通知启动应用，既无法获取Intent数据，也看不到onMessageReceived的日志输出。

解决思路 #

1. 区分FCM消息类型 #

FCM消息分为通知消息和数据消息：

• 应用后台/未运行时，纯通知消息会由系统直接展示，不会触发onMessageReceived；只有数据消息，或通知+数据混合消息，才会让onMessageReceived在后台状态下被调用。
• 检查推送payload：如果只包含notification字段，后台时系统接管推送流程，不会走自定义Service；需要添加data字段，或者改用纯数据消息自行构建通知。

2. 调整PendingIntent与Activity数据获取逻辑 #

• 应用未运行时，点击通知启动的MainActivity是新任务栈的根Activity，此时通过getIntent()获取原始Intent可能存在系统处理偏差，建议：
  • 给MainActivity设置启动模式为singleTop，在AndroidManifest.xml中配置：

    <activity
        android:name=".MainActivity"
        android:launchMode="singleTop">
    </activity>
    

  • 在MainActivity中重写onNewIntent()方法接收数据：

    override fun onNewIntent(intent: Intent?) {
        super.onNewIntent(intent)
        setIntent(intent) // 更新当前Intent为最新的通知跳转Intent
        val debugData = intent?.getStringExtra("KeyI")
        // 处理获取到的数据
    }
    

  • 保持PendingIntent的FLAG_UPDATE_CURRENT flag，确保更新已存在PendingIntent的Extra数据，避免旧数据残留。

3. 检查Service注册与配置 #

• 确认AndroidManifest.xml中正确注册PushService：

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

• 验证google-services.json文件配置正确，包名与项目完全匹配。

4. 适配Android 13+权限要求 #

Android 13（TIRAMISU）及以上版本，前台服务需要申请POST_NOTIFICATIONS权限：

• 在Manifest中添加权限声明：

  <uses-permission android:name="android.permission.POST_NOTIFICATIONS" />
  

• 启动前台服务前，确保已动态申请该权限，否则通知可能无法正常展示，导致点击行为异常。

内容的提问来源于stack exchange，提问作者SmirnovDV