Flutter OneSignal后台通知处理及remoteNotificationReceivedHandler问题

问题根因 #

出现remoteNotificationReceivedHandler not setup, displaying normal OneSignal notification提示，是因为仅完成了前台通知回调setNotificationWillShowInForegroundHandler的配置，没有注册后台状态下的通知接收回调，OneSignal无法识别自定义后台处理逻辑，会直接走默认通知展示流程，不会执行自定义的后台打印逻辑。

具体实现方案 #

1. Flutter端补全回调注册 #

在原有OneSignal初始化逻辑中，补全后台通知接收回调，不要只保留前台处理方法，参考代码如下：

import 'package:onesignal_flutter/onesignal_flutter.dart';

Future<void> initOneSignal() async {
  // 替换为你自己的OneSignal App ID
  OneSignal.shared.setAppId("YOUR_ONESIGNAL_APP_ID");

  // 原有前台通知处理逻辑，保持不变
  OneSignal.shared.setNotificationWillShowInForegroundHandler((OSNotificationReceivedEvent event) {
    final notification = event.notification;
    print("前台接收通知: ${notification.jsonRepresentation()}");
    event.complete(notification);
  });

  // 新增：后台/应用未在前台时的通知接收回调，解决handler未设置的报错
  // 应用处于后台、未被用户主动杀死的状态下，收到通知会立即触发该回调
  OneSignal.shared.setNotificationReceivedHandler((OSNotification notification) {
    // 这里实现后台通知内容打印到控制台的需求
    print("后台接收通知: ${notification.jsonRepresentation()}");
    // 其他自定义后台逻辑（如本地存储、更新本地状态等）可直接写在此处
  });

  // 可选：注册通知点击回调，用户点击通知拉起应用时触发
  OneSignal.shared.setNotificationOpenedHandler((OSNotificationOpenedResult result) {
    print("用户点击通知: ${result.notification.jsonRepresentation()}");
  });

  // 申请通知权限，确保后台通知接收权限正常
  await OneSignal.shared.promptUserForPushNotificationPermission(
    fallbackToSettings: true,
  );
}

2. iOS端必要配置 #

iOS系统对后台通知有严格权限限制，需要额外配置才能触发后台回调：

• 打开ios/Runner/Info.plist文件，添加远程通知后台模式权限：

<key>UIBackgroundModes</key>
<array>
  <string>remote-notification</string>
</array>

• 从OneSignal后台发送通知时，必须在高级选项中勾选Content Available（对应通知payload字段content-available: 1），该字段会唤醒后台运行的应用，触发接收回调。

3. Android端注意事项 #

• Android 13及以上版本需要确保已授予应用通知权限，无需额外配置后台模式即可正常触发回调。
• 回调内不要执行耗时超过10秒的逻辑，否则会被系统判定为异常，直接杀死应用后台进程。

验证规则 #

• 首次测试时将应用切到后台，不要手动上滑杀死进程
• 发送带Content Available标记的测试通知
• 控制台可看到后台通知的打印内容，原有的handler未设置提示会完全消失

注意：如果应用被用户手动上滑强制停止，iOS和Android系统都会默认禁止应用后台唤醒，此场景下无法触发回调属于系统级限制，不是代码配置问题。

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