摘要本文系统梳理 iOS 推送通知的完整实现链路涵盖整体架构、初始化流程、到达与点击处理、埋点上报、App Groups 共享配置、数据模型、通知权限缓存及调试方法。文章以 FCM 中转 APNs 的投递链路为主线重点说明前台、后台、被杀三种状态下的回调差异以及 NSE 扩展在后台/被杀场景下的到达埋点上报与去重机制并给出核心代码示例与调试建议。一、整体架构1.1 推送投递链路后端服务器 │ 使用 FCM Token 调用 Firebase API ▼ Firebase Cloud Messaging (FCM) │ 转发给 APNs ▼ Apple Push Notification service (APNs) │ 投递到设备 ▼ iOS 设备 → 系统展示通知横幅后端不直接调用 APNs而是通过 Firebase Cloud Messaging 中转Firebase 负责与 APNs 对接投递到 iOS 设备前提后端 APNs payload 中需包含mutable-content: 1以触发 Notification Service Extension1.2 核心文件清单文件职责AppDelegate.swift推送初始化、FCM Token 监听、通知到达/点击回调SceneDelegate.swift前台/后台状态标记通知权限缓存刷新PushNotificationManager.swift通知点击后的页面跳转逻辑PushNotificationModel.swift推送数据模型解析 userInfoDeviceTokenUploadService.swiftFCM Token 上报给后端DeviceInfoProvider.swift设备信息收集FCM Token、通知权限等SharedConfigStore.swiftApp Groups 共享配置API 地址、前台状态等NotificationService/NotificationService.swiftNSE 扩展后台/被杀时的到达埋点上报TrackEventService.swift埋点上报服务二、推送初始化流程2.1 App 启动时在AppDelegate.didFinishLaunchingWithOptions中完成// 1. 初始化 Firebase FirebaseApp.configure() // 2. 设置 FCM 代理 Messaging.messaging().delegate self // 3. 设置通知中心代理 UNUserNotificationCenter.current().delegate self // 4. 请求通知权限 UNUserNotificationCenter.current().requestAuthorization(options: [.alert, .badge, .sound]) // 5. 注册远程通知 application.registerForRemoteNotifications() // 6. 预加载通知权限状态 DeviceInfoProvider.refreshNotificationEnabled() // 7. 同步共享配置到 App Groups SharedConfigStore.shared.sync()2.2 FCM Token 获取与上报FCM Token 是后端发送推送的凭证获取和上报流程Firebase SDK 自动生成 FCM Token │ ▼ messaging(_:didReceiveRegistrationToken:) 回调 │ ├─ DeviceInfoProvider.updateMessagingToken() ← 缓存 Token │ └─ DeviceTokenUploadService.uploadDeviceTokenAndLanguage() ← 上报后端 │ ├─ 已登录 → POST /setting/set-languagebody: { deviceToken } └─ 未登录 → POST /setting/upload-device-tokenbody: { deviceToken, isActivated }Pending 机制冷启动时 session 登录未完成标记mPendingUpload true等.sessionLoginCompleted通知后补发。三、推送到达处理3.1 三种 App 状态下的回调App 状态系统回调是否触发前台(active)willPresent✅ 触发后台(background)willPresent❌ 不触发被杀(terminated)willPresent❌ 不触发3.2 前台到达willPresent文件AppDelegate.swiftfunc userNotificationCenter(_ center:, willPresent notification:) async - UNNotificationPresentationOptions { let userInfo notification.request.content.userInfo // 1. 刷新未读消息角标 NoticeBadgeManager.shared.refresh() // 2. 上报推送到达埋点 let pushModel PushNotificationModel(userInfo: userInfo) TrackEventService.shared.requestPushArrivalTrack(title: pushModel.displayTitle) // 3. 在前台展示通知横幅 return [[.alert, .sound]] }3.3 后台/被杀到达Notification Service Extension文件NotificationService/NotificationService.swiftNSE 是独立进程在推送到达时被系统调用无论 App 处于什么状态。override func didReceive(_ request:, contentHandler:) { let appIsActive sharedDefaults?.bool(forKey: shared_app_is_active) ?? false // 1. 立即放行通知不阻塞展示 contentHandler(request.content) // 2. 后台上报埋点fire-and-forget // App 在前台时由 willPresent 上报Extension 跳过避免重复 if !appIsActive { trackPushArrival(userInfo: request.content.userInfo) } }关键设计contentHandler在第一行就调用通知立即展示零延迟埋点请求 fire-and-forget不等待完成通过shared_app_is_active标记避免与willPresent重复上报四、推送点击处理4.1 点击回调文件AppDelegate.swift用户点击通知横幅时系统调用didReceive无论 App 什么状态func userNotificationCenter(_ center:, didReceive response:) async { let userInfo response.notification.request.content.userInfo // 1. 上报推送点击埋点 let pushModel PushNotificationModel(userInfo: userInfo) TrackEventService.shared.requestPushClickTrack(title: pushModel.displayTitle) // 2. 处理页面跳转 PushNotificationManager.shared.handleNotificationTap(userInfo: userInfo) }4.2 页面跳转逻辑文件PushNotificationManager.swifthandleNotificationTap(userInfo:) │ ├─ 解析 userInfo → PushNotificationModel │ ├─ 检查是否横屏 → 是则先切回竖屏 │ └─ nextNavigation(for:) │ ├─ App 在前台 → handleNavigation() → 直接跳转 │ └─ App 在后台/被杀 → handleDelayedNavigation() │ └─ 保存 URL等 App 完全启动后 handlePendingNotification() 执行跳转跳转规则已登录通过navigateToURL(path:)跳转到目标页面或 present WebViewController未登录先跳转登录页登录后再处理待跳转 URL有模态控制器在最顶层 present WebViewController不打断用户操作五、推送埋点上报5.1 埋点字段定义场景pageIdcategoryactionlabel推送到达pushpush_arrivalviewpush_{消息标题}推送点击pushpush_clickclickpush_{消息标题}5.2 上报代码位置上报位置触发条件代码文件willPresentApp 在前台收到推送AppDelegate.swiftNSEdidReceiveApp 在后台/被杀推送到达NotificationService.swiftdidReceive(response)用户点击通知AppDelegate.swift5.3 去重机制NSE 通过 App Groups 中的shared_app_is_active标记判断推送到达 │ ▼ NSE 启动读取 shared_app_is_active │ ├─ trueApp 在前台→ 跳过上报willPresent 已处理 │ └─ falseApp 在后台/被杀→ 上报 push_arrivalshared_app_is_active的写入时机sceneDidBecomeActive→ 写truesceneDidEnterBackground→ 写falseApp 被杀时最后写入的值是false杀之前一定先进入后台所以 NSE 会正确执行上报。5.4 NSE 埋点的可靠性优点通知立即展示零延迟缺点fire-and-forget 请求可能在完成前被系统杀掉极端情况下部分埋点丢失实际表现大部分情况下能完成上报NSE 进程不会立即被杀仅在网络极慢时可能丢失六、App Groups 共享配置6.1 为什么需要NSE 是独立进程无法访问主 App 的单例和内存状态。通过 App Groups UserDefaults 共享运行时配置。6.2 共享的数据Key写入方读取方用途shared_api_base_url主 App 启动时NSE埋点请求的 API 地址shared_app_version主 App 启动时NSE请求头 Versionshared_build_number主 App 启动时NSE请求头 Buildshared_accept_language主 App 启动时NSE请求头 Accept-Languageshared_app_is_activeScene 生命周期NSE前台状态标记去重用6.3 写入时机// AppDelegate.didFinishLaunchingWithOptions SharedConfigStore.shared.sync() // 写入 API 地址、版本等 // SceneDelegate.sceneDidBecomeActive SharedConfigStore.shared.updateAppIsActive(true) // SceneDelegate.sceneDidEnterBackground SharedConfigStore.shared.updateAppIsActive(false)6.4 Xcode 配置要求主 App 所有 target 和 NSE target 都需开启App Groupscapability使用相同的 Group 标识符group.com.vgmarkets.shared七、推送数据模型7.1 PushNotificationModel文件Common/Models/PushNotificationModel.swift从推送userInfo中解析的字段字段类型来源messageIdInt64?noticeIdcategoryString?categorynoticeTypeInt?noticeTypeurlString?urltitleString?titlebodyString?bodybriefString?briefnumberString?number或从 URL 提取7.2 消息类型分类类型noticeType说明activity10活动通知news20新闻通知system30系统通知other40其他通知account50账户通知announcementcategoryannounce公告通知7.3 标题提取优先级var displayTitle: String { return aps?.alert?.title ?? title ?? messageType.displayName }aps.alert.titleAPNs 标准字段title自定义字段消息类型显示名如活动通知八、通知权限状态缓存8.1 缓存机制文件DeviceInfoProvider.swift// 异步获取并缓存 class func refreshNotificationEnabled() { UNUserNotificationCenter.current().getNotificationSettings { settings in cachedNotificationEnabled (settings.authorizationStatus .authorized ...) } } // 同步读取缓存 private class func getNotificationEnabledSync() - Bool { return cachedNotificationEnabled ?? false }8.2 刷新时机App 启动AppDelegate.didFinishLaunchingWithOptions回前台SceneDelegate.sceneDidBecomeActive用户可能在系统设置中改变了权限8.3 用途缓存值写入Device-InfoHTTP 头部的is_notification_enabled字段供后端判断用户是否开启了通知。九、调试方法9.1 控制台日志推送到达/点击搜索Message ID:和userInfo埋点上报搜索[Track]FCM Token搜索Firebase registration tokenToken 上报搜索[DeviceTokenUpload]9.2 抓包验证埋点请求Hostapi-web-beta.vgmarkets.comPath/customer-track/upload-eventToken 上报Path/setting/set-language或/setting/upload-device-token9.3 NSE 调试NSE 是独立进程主 App 的 Console 看不到其日志。使用Console.app选择设备搜索com.vgmarkets.NotificationService杀死 App发送推送观察 Extension 执行日志 iOS 推送通知机制知识文档
摘要本文系统梳理 iOS 推送通知的完整实现链路涵盖整体架构、初始化流程、到达与点击处理、埋点上报、App Groups 共享配置、数据模型、通知权限缓存及调试方法。文章以 FCM 中转 APNs 的投递链路为主线重点说明前台、后台、被杀三种状态下的回调差异以及 NSE 扩展在后台/被杀场景下的到达埋点上报与去重机制并给出核心代码示例与调试建议。一、整体架构1.1 推送投递链路后端服务器 │ 使用 FCM Token 调用 Firebase API ▼ Firebase Cloud Messaging (FCM) │ 转发给 APNs ▼ Apple Push Notification service (APNs) │ 投递到设备 ▼ iOS 设备 → 系统展示通知横幅后端不直接调用 APNs而是通过 Firebase Cloud Messaging 中转Firebase 负责与 APNs 对接投递到 iOS 设备前提后端 APNs payload 中需包含mutable-content: 1以触发 Notification Service Extension1.2 核心文件清单文件职责AppDelegate.swift推送初始化、FCM Token 监听、通知到达/点击回调SceneDelegate.swift前台/后台状态标记通知权限缓存刷新PushNotificationManager.swift通知点击后的页面跳转逻辑PushNotificationModel.swift推送数据模型解析 userInfoDeviceTokenUploadService.swiftFCM Token 上报给后端DeviceInfoProvider.swift设备信息收集FCM Token、通知权限等SharedConfigStore.swiftApp Groups 共享配置API 地址、前台状态等NotificationService/NotificationService.swiftNSE 扩展后台/被杀时的到达埋点上报TrackEventService.swift埋点上报服务二、推送初始化流程2.1 App 启动时在AppDelegate.didFinishLaunchingWithOptions中完成// 1. 初始化 Firebase FirebaseApp.configure() // 2. 设置 FCM 代理 Messaging.messaging().delegate self // 3. 设置通知中心代理 UNUserNotificationCenter.current().delegate self // 4. 请求通知权限 UNUserNotificationCenter.current().requestAuthorization(options: [.alert, .badge, .sound]) // 5. 注册远程通知 application.registerForRemoteNotifications() // 6. 预加载通知权限状态 DeviceInfoProvider.refreshNotificationEnabled() // 7. 同步共享配置到 App Groups SharedConfigStore.shared.sync()2.2 FCM Token 获取与上报FCM Token 是后端发送推送的凭证获取和上报流程Firebase SDK 自动生成 FCM Token │ ▼ messaging(_:didReceiveRegistrationToken:) 回调 │ ├─ DeviceInfoProvider.updateMessagingToken() ← 缓存 Token │ └─ DeviceTokenUploadService.uploadDeviceTokenAndLanguage() ← 上报后端 │ ├─ 已登录 → POST /setting/set-languagebody: { deviceToken } └─ 未登录 → POST /setting/upload-device-tokenbody: { deviceToken, isActivated }Pending 机制冷启动时 session 登录未完成标记mPendingUpload true等.sessionLoginCompleted通知后补发。三、推送到达处理3.1 三种 App 状态下的回调App 状态系统回调是否触发前台(active)willPresent✅ 触发后台(background)willPresent❌ 不触发被杀(terminated)willPresent❌ 不触发3.2 前台到达willPresent文件AppDelegate.swiftfunc userNotificationCenter(_ center:, willPresent notification:) async - UNNotificationPresentationOptions { let userInfo notification.request.content.userInfo // 1. 刷新未读消息角标 NoticeBadgeManager.shared.refresh() // 2. 上报推送到达埋点 let pushModel PushNotificationModel(userInfo: userInfo) TrackEventService.shared.requestPushArrivalTrack(title: pushModel.displayTitle) // 3. 在前台展示通知横幅 return [[.alert, .sound]] }3.3 后台/被杀到达Notification Service Extension文件NotificationService/NotificationService.swiftNSE 是独立进程在推送到达时被系统调用无论 App 处于什么状态。override func didReceive(_ request:, contentHandler:) { let appIsActive sharedDefaults?.bool(forKey: shared_app_is_active) ?? false // 1. 立即放行通知不阻塞展示 contentHandler(request.content) // 2. 后台上报埋点fire-and-forget // App 在前台时由 willPresent 上报Extension 跳过避免重复 if !appIsActive { trackPushArrival(userInfo: request.content.userInfo) } }关键设计contentHandler在第一行就调用通知立即展示零延迟埋点请求 fire-and-forget不等待完成通过shared_app_is_active标记避免与willPresent重复上报四、推送点击处理4.1 点击回调文件AppDelegate.swift用户点击通知横幅时系统调用didReceive无论 App 什么状态func userNotificationCenter(_ center:, didReceive response:) async { let userInfo response.notification.request.content.userInfo // 1. 上报推送点击埋点 let pushModel PushNotificationModel(userInfo: userInfo) TrackEventService.shared.requestPushClickTrack(title: pushModel.displayTitle) // 2. 处理页面跳转 PushNotificationManager.shared.handleNotificationTap(userInfo: userInfo) }4.2 页面跳转逻辑文件PushNotificationManager.swifthandleNotificationTap(userInfo:) │ ├─ 解析 userInfo → PushNotificationModel │ ├─ 检查是否横屏 → 是则先切回竖屏 │ └─ nextNavigation(for:) │ ├─ App 在前台 → handleNavigation() → 直接跳转 │ └─ App 在后台/被杀 → handleDelayedNavigation() │ └─ 保存 URL等 App 完全启动后 handlePendingNotification() 执行跳转跳转规则已登录通过navigateToURL(path:)跳转到目标页面或 present WebViewController未登录先跳转登录页登录后再处理待跳转 URL有模态控制器在最顶层 present WebViewController不打断用户操作五、推送埋点上报5.1 埋点字段定义场景pageIdcategoryactionlabel推送到达pushpush_arrivalviewpush_{消息标题}推送点击pushpush_clickclickpush_{消息标题}5.2 上报代码位置上报位置触发条件代码文件willPresentApp 在前台收到推送AppDelegate.swiftNSEdidReceiveApp 在后台/被杀推送到达NotificationService.swiftdidReceive(response)用户点击通知AppDelegate.swift5.3 去重机制NSE 通过 App Groups 中的shared_app_is_active标记判断推送到达 │ ▼ NSE 启动读取 shared_app_is_active │ ├─ trueApp 在前台→ 跳过上报willPresent 已处理 │ └─ falseApp 在后台/被杀→ 上报 push_arrivalshared_app_is_active的写入时机sceneDidBecomeActive→ 写truesceneDidEnterBackground→ 写falseApp 被杀时最后写入的值是false杀之前一定先进入后台所以 NSE 会正确执行上报。5.4 NSE 埋点的可靠性优点通知立即展示零延迟缺点fire-and-forget 请求可能在完成前被系统杀掉极端情况下部分埋点丢失实际表现大部分情况下能完成上报NSE 进程不会立即被杀仅在网络极慢时可能丢失六、App Groups 共享配置6.1 为什么需要NSE 是独立进程无法访问主 App 的单例和内存状态。通过 App Groups UserDefaults 共享运行时配置。6.2 共享的数据Key写入方读取方用途shared_api_base_url主 App 启动时NSE埋点请求的 API 地址shared_app_version主 App 启动时NSE请求头 Versionshared_build_number主 App 启动时NSE请求头 Buildshared_accept_language主 App 启动时NSE请求头 Accept-Languageshared_app_is_activeScene 生命周期NSE前台状态标记去重用6.3 写入时机// AppDelegate.didFinishLaunchingWithOptions SharedConfigStore.shared.sync() // 写入 API 地址、版本等 // SceneDelegate.sceneDidBecomeActive SharedConfigStore.shared.updateAppIsActive(true) // SceneDelegate.sceneDidEnterBackground SharedConfigStore.shared.updateAppIsActive(false)6.4 Xcode 配置要求主 App 所有 target 和 NSE target 都需开启App Groupscapability使用相同的 Group 标识符group.com.vgmarkets.shared七、推送数据模型7.1 PushNotificationModel文件Common/Models/PushNotificationModel.swift从推送userInfo中解析的字段字段类型来源messageIdInt64?noticeIdcategoryString?categorynoticeTypeInt?noticeTypeurlString?urltitleString?titlebodyString?bodybriefString?briefnumberString?number或从 URL 提取7.2 消息类型分类类型noticeType说明activity10活动通知news20新闻通知system30系统通知other40其他通知account50账户通知announcementcategoryannounce公告通知7.3 标题提取优先级var displayTitle: String { return aps?.alert?.title ?? title ?? messageType.displayName }aps.alert.titleAPNs 标准字段title自定义字段消息类型显示名如活动通知八、通知权限状态缓存8.1 缓存机制文件DeviceInfoProvider.swift// 异步获取并缓存 class func refreshNotificationEnabled() { UNUserNotificationCenter.current().getNotificationSettings { settings in cachedNotificationEnabled (settings.authorizationStatus .authorized ...) } } // 同步读取缓存 private class func getNotificationEnabledSync() - Bool { return cachedNotificationEnabled ?? false }8.2 刷新时机App 启动AppDelegate.didFinishLaunchingWithOptions回前台SceneDelegate.sceneDidBecomeActive用户可能在系统设置中改变了权限8.3 用途缓存值写入Device-InfoHTTP 头部的is_notification_enabled字段供后端判断用户是否开启了通知。九、调试方法9.1 控制台日志推送到达/点击搜索Message ID:和userInfo埋点上报搜索[Track]FCM Token搜索Firebase registration tokenToken 上报搜索[DeviceTokenUpload]9.2 抓包验证埋点请求Hostapi-web-beta.vgmarkets.comPath/customer-track/upload-eventToken 上报Path/setting/set-language或/setting/upload-device-token9.3 NSE 调试NSE 是独立进程主 App 的 Console 看不到其日志。使用Console.app选择设备搜索com.vgmarkets.NotificationService杀死 App发送推送观察 Extension 执行日志