Capacitor-Ionic安卓前台推送：pushNotificationActionPerformed未触发

问题描述 #

我是Capacitor和Ionic框架新手，正在实现FCM推送及应用深度链接，遇到平台差异问题：

• iOS：应用在后台、前台及杀死状态下，点击推送均能正常调用pushNotificationActionPerformed监听器。
• Android：后台及杀死状态下点击推送可正常触发pushNotificationActionPerformed；但前台时点击推送无任何反应，仅能触发pushNotificationReceived监听器，无法捕获用户点击事件实现深度链接跳转。

已配置内容如下：

capacitor.config.json #

"PushNotifications": {
    "presentationOptions": [
        "badge",
        "sound",
        "alert"
    ]
}

AndroidManifest.xml #

<intent-filter>
    <action android:name="MOBILE-PUSH-DEEP-LINK" />
    <category android:name="android.intent.category.DEFAULT" />
</intent-filter>

推送Payload #

{
    "to": "FCM token",
    "notification": {
        "body": "test",
        "title": "Dummy",
        "click_action": "MOBILE-PUSH-DEEP-LINK"
    },
    "data": {
        "data1": "test",
        "data2": "12345"
    }
}

解决方法 #

1. 手动构建前台可交互通知 #

Android前台收到FCM通知时，默认可能仅触发pushNotificationReceived而不弹出可点击的通知栏。可在该监听器中手动创建通知，确保用户能点击触发动作：

import { PushNotifications, PushNotificationSchema } from '@capacitor/push-notifications';
import { Capacitor } from '@capacitor/core';

PushNotifications.addListener('pushNotificationReceived', async (notification: PushNotificationSchema) => {
  if (Capacitor.getPlatform() === 'android' && notification.foreground) {
    // 手动创建带点击动作的通知
    await PushNotifications.createNotification({
      title: notification.title,
      body: notification.body,
      data: notification.data,
      actionTypeId: 'MOBILE-PUSH-DEEP-LINK'
    });
  }
});

2. 修正AndroidManifest配置位置 #

确保intent-filter添加在主Activity标签内部，同时设置正确的启动模式：

<activity
    android:name=".MainActivity"
    android:launchMode="singleTask"
    android:configChanges="orientation|keyboardHidden|keyboard|screenSize|locale|smallestScreenSize|screenLayout|uiMode"
    android:hardwareAccelerated="true"
    android:windowSoftInputMode="adjustResize">
    <!-- 其他默认intent-filter -->
    <intent-filter>
        <action android:name="MOBILE-PUSH-DEEP-LINK" />
        <category android:name="android.intent.category.DEFAULT" />
    </intent-filter>
</activity>

singleTask模式可避免重复启动Activity，确保点击通知能正确唤起现有前台实例。

3. 调整推送Payload结构 #

Android前台场景下，FCM的notification字段可能无法触发点击动作，建议将跳转核心数据放入data字段，同时保留notification兼容后台场景：

{
    "to": "FCM token",
    "data": {
        "title": "Dummy",
        "body": "test",
        "click_action": "MOBILE-PUSH-DEEP-LINK",
        "data1": "test",
        "data2": "12345"
    },
    "notification": {
        "body": "test",
        "title": "Dummy",
        "click_action": "MOBILE-PUSH-DEEP-LINK"
    }
}

也可直接发送纯data消息，这样无论前后台都会触发pushNotificationReceived，再统一处理点击逻辑。

4. 提前注册监听器 #

确保pushNotificationActionPerformed监听器在App初始化阶段尽早注册，比如在app.component.ts的初始化方法中：

import { Router } from '@angular/router';
import { PushNotifications } from '@capacitor/push-notifications';

constructor(private router: Router) {}

async initializeApp() {
    // 请求推送权限并注册
    await PushNotifications.requestPermissions();
    await PushNotifications.register();

    // 优先注册点击动作监听器
    PushNotifications.addListener('pushNotificationActionPerformed', (action) => {
        // 处理深度链接跳转
        const data = action.notification.data;
        if (data.data1 === 'test') {
            this.router.navigate(['/target-page']);
        }
    });

    // 前台通知接收处理
    PushNotifications.addListener('pushNotificationReceived', (notification) => {
        // 逻辑同方法1
    });
}

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