iOS MobPush 集成 Skill

当用户希望把 MobTech MobPush 集成到 iOS 工程，或者排查已有 MobPush 接入问题时，使用本 skill。

适用场景

当用户提到以下任一主题时，使用本 skill：

• iOS MobPush 集成
• iOS 推送接入
• iOS MobTech 推送
• MobPush CocoaPods 配置
• MobPush Info.plist 配置
• MobPush APNs 配置
• MobPush 隐私合规
• uploadPrivacyPermissionStatus 调用时机
• setupNotification / setAPNsForProduction 用法
• MobPush tag / alias 设置
• MobPush Live Activity 接入
• 帮我在 iOS 项目里增加推送
• 帮我把 MobPush 接进现有 iOS 工程

如果用户问题明确与 iOS MobPush 接入、工程配置、证书鉴权、隐私合规、通知接收、Tag/Alias 或 Live Activity 扩展能力有关，应优先使用本 skill。

输出语言

• 默认使用中文与用户沟通
• 代码、配置键名、类名、命令名保持原文
• 回答尽量短，先给结论，再给动作

官方资料

优先使用以下线上资料，不依赖本机资料路径：

主文档：

• MobTech 文档中心
• MobPush 产品页
• SDK 下载中心
• 创建应用流程
• 合规指南
• 集成指南
• SDK API 文档
• 证书配置
• App Store Connect 后台隐私数据项配置
• MobPush 扩展业务功能设置
• 其它 App 数据采集主动控制器配置
• MobPush 隐私政策

扩展资料：

• iOS 实时活动说明

如果某个深链失效，先从 MobTech 文档中心 搜索对应标题，不要回退到本机绝对路径。

已确认的官方事实

以下信息已经可作为执行依据，不需要再猜测：

• 默认开发环境要求为 Xcode 9.1.0+、iOS 8.0+
• 官方支持 CocoaPods 和手动导入两种集成方式
• 默认 Pod 为 pod 'mob_pushsdk'
• 工程需要链接 libc++.tbd、libz.1.2.5.tbd
• Info.plist 需要配置 MOBAppKey 与 MOBAppSecret
• 需要开启 Push Notifications
• 需要开启 Background Modes 并勾选 Remote notifications
• uploadPrivacyPermissionStatus 是 MobSDK 业务起点，必须在用户同意隐私政策后、使用 SDK 能力前调用
• 严格合规方案要求默认 plist 中增加 MOBNetLater = 2
• 推送环境应通过 setAPNsForProduction: 在开发与生产间切换
• 通知权限申请与推送注册通过 setupNotification: 配置
• 收到推送或自定义消息后，应监听 MobPushDidReceiveMessageNotification
• Swift API 注意：MobPushDidReceiveMessageNotification 在 Swift 中被重命名为 NSNotification.Name.MobPushDidReceiveMessage
• MPushMessage 的 msg 和 isCustomMessage 属性在 4.x 中已移除，改用 messageType（MPushMessageType.custom）和 message.notification.body
• 自定义消息内容存于 message.notification.userInfo["mobpushCustomTitle"] / ["mobpushCustomType"]
• MPushAuthorizationOptions 在 Swift 中以 OptionSet 形式可用：MPushAuthorizationOptions.badge.union(.sound).union(.alert)
• 纯 Swift 工程必须创建 Bridging Header 并添加 #import \x3CMobPush/MobPush.h> 和 #import \x3CMOBFoundation/MOBFoundation.h>
• Bridging Header 路径需在 .xcodeproj 的 Debug 和 Release 构建配置中设置 SWIFT_OBJC_BRIDGING_HEADER
• getRegistrationID 必须在推送设置接口之后调用
• SDK 支持 tag、alias、本地通知、badge 同步等能力
• iOS 端扩展业务能力仅支持“基于地域更精准推送”和“网络链路优化/特定区域服务”两类
• 扩展业务主动控制器应通过 MOBFoundationPrivacyDelegate 自定义类接入
• 证书鉴权支持 .p12 与 APNs Auth Key(.p8) 两种方式
• .p8 鉴权需要 Key ID、Team ID、Bundle ID
• Live Activity 功能需 iOS 16.1+、SwiftUI、ActivityKit，且需要 App 运行态配合

文档未明确，需向用户确认

以下内容在当前资料里没有被稳定、明确地定义，禁止猜：

• 是否支持 Swift Package Manager
• 是否需要 Bitcode、Privacy Manifest 或额外苹果隐私文件
• 用户项目应该使用 CocoaPods 还是已存在的手动导入体系
• 用户是否本次就要接入 Notification Service Extension
• Live Activity 官方独立文档深链地址在当前资料中未提供，若用户要正式启用该能力，需先确认要以当前资料版本为准还是由用户补充最新官方页面

如果缺这些信息且会阻塞安全修改，必须明确写：

文档未明确，需向用户确认

默认执行策略

• 默认集成方式：CocoaPods
• 默认先扫描工程，再给改动方案
• 默认优先复用工程已有推送能力、隐私弹窗和 App 启动入口
• 默认先生成最小 Excel 模板，再等用户填写
• 默认不在 Excel 中收集 Bundle ID、Target 名称、Info.plist 路径、入口类名，因为这些应由扫描工程自动推断
• 默认不主动询问是否启用扩展业务主动控制器；仅在最终项目文档中说明这项可选能力
• 默认不主动启用 Live Activity；仅当用户明确需要时才进入该分支
• 默认不运行 pod install、xcodebuild 或其他会改动依赖状态的命令，先展示计划，再执行
• 默认不把 Pods/ 提交进项目；如项目未忽略 Pods/，补充 .gitignore，保留 Podfile 与 Podfile.lock
• 一次只问用户一个阻塞问题

执行流程

严格按以下顺序推进：

1. 先扫描工程，再判断接入方式。
2. 先生成或读取配置模板，再确定静态配置。
3. 先展示最小改动计划，再修改文件。
4. 依赖安装前先征求确认。
5. 完成后补项目内说明文档。

第一步：扫描工程

优先扫描以下内容：

• .xcodeproj / .xcworkspace
• Podfile
• Podfile.lock
• Package.swift
• AppDelegate / SceneDelegate / SwiftUI @main
• Info.plist
• 现有通知权限申请、APNs 注册、UNUserNotificationCenter 代理代码
• 隐私政策弹窗或同意回调位置
• Objective-C / Swift / 混编类型，以及是否已有 Bridging Header
• 是否已有 MobPush、MOBAppKey、MOBAppSecret、MOBNetLater、uploadPrivacyPermissionStatus
• .gitignore 是否忽略 Pods/
• .xcworkspace 是否包含 contents.xcworkspacedata

推荐命令：

• rg --files -g '*.xcodeproj' -g '*.xcworkspace' -g 'Podfile' -g 'Podfile.lock' -g 'Package.swift' -g '*Info.plist' -g '.gitignore'
• rg --files -g '*.m' -g '*.h' -g '*.mm' -g '*.swift'
• rg -n 'MobPush|MOBAppKey|MOBAppSecret|MOBNetLater|uploadPrivacyPermissionStatus|setAPNsForProduction|setupNotification|MobPushDidReceiveMessageNotification|UNUserNotificationCenter|didRegisterForRemoteNotificationsWithDeviceToken|SWIFT_OBJC_BRIDGING_HEADER'

扫描后先给一段简短结论，至少包含：

• 当前工程依赖方式
• 当前入口结构
• 当前代码语言形态：Objective-C / Swift / 混编
• Swift 工程是否已有 Bridging Header
• 是否已有 MobPush 残留
• 是否已经有隐私同意链路
• 是否已经有推送能力接线
• CocoaPods 状态：是否有有效 Podfile、Podfile.lock、Pods/、*.xcworkspace/contents.xcworkspacedata
• 下一步是生成模板还是读取已有 MobPush_iOS_Config.xlsx

第二步：生成并读取配置模板

2-1 模板生成

如果 {path} 下还没有 MobPush_iOS_Config.xlsx：

1. 运行本 skill 目录下的 assets/generate_excel_template.py
2. 将生成的 assets/MobPush_iOS_Config_Template.xlsx 复制到 {path} 下
3. 在 {path} 下命名为 MobPush_iOS_Config.xlsx

2-2 向用户说明填写项

必须明确告诉用户只需要填写这些最小字段：

• appKey
• appSecret
• apnsAuthMode
• needLiveActivity

同时明确说明以下内容不需要填表：

• Bundle ID
• Target
• Info.plist 路径
• App 启动入口类名
• 隐私弹窗类名
• 推送回调方法名
• Key ID / Team ID / .p12 文件路径

其中工程信息应由 Agent 扫描后推断；鉴权材料属于控制台与苹果后台准备项，不应默认塞进最小模板。

2-3 配置校验

读取 MobPush_iOS_Config.xlsx 后，至少校验：

• appKey：必填，按字符串处理，不做数值推断
• appSecret：必填，按字符串处理，不做数值推断
• apnsAuthMode：必须明确是 p12 / p8 / 已存在
• needLiveActivity：必须明确是 是 / 否

如不合法，列出具体问题并要求用户修正，不要继续改工程。

第三步：扫描后推断工程接入点

读取配置后，再次结合工程做推断：

• 优先识别主要 App Target
• 推断 Objective-C / Swift / 混编
• 记录当前工程要使用 Objective-C 示例、Swift 示例还是两者都需要
• Swift 工程需检查是否已有 {Target}-Bridging-Header.h 与 SWIFT_OBJC_BRIDGING_HEADER
• 定位疑似隐私同意回调位置，后续仍必须向用户确认
• 推断当前是否已有 CocoaPods 体系
• 推断是否已有 Push Notifications / Background Modes 相关工程配置说明或脚本
• 推断是否已有 APNs 注册代码、通知代理、启动回调
• 判断已有 *.xcworkspace 是否有效；只有目录但缺少 contents.xcworkspacedata 时，应运行 pod install 重新生成
• 判断已有 Pods/ 是否完整；如果只有空 framework 目录或缺少 Info.plist、Headers、binary，不要按手动 SDK 接入硬改工程，应优先重新 pod install

以下信息必须分两类处理：

必须在修改前确认的信息

• 多 Target 时应该接入哪个 App Target
• 用户同意隐私政策后的回调位置。即使扫描到疑似隐私弹窗，也要让用户确认 uploadPrivacyPermissionStatus 应插入到哪个“同意”回调
• 用户明确不想用 CocoaPods，必须改走手动导入

可以在扫描后逐步确认的信息

• 是否需要启用 Live Activity
• 是否需要添加 tag / alias 业务接线
• 是否需要接入扩展业务主动控制器

如果必须确认，串行一次只问一个问题。

第四步：展示最小改动计划

修改前必须向用户展示本次最小改动计划，通常包括：

• Podfile：按需加入 pod 'mob_pushsdk'
• .gitignore：按需加入 Pods/
• Info.plist：写入 MOBAppKey、MOBAppSecret、MOBNetLater = 2
• Xcode 工程能力：提醒用户检查或手动开启 Push Notifications 与 Background Modes > Remote notifications
• 系统库：补 libc++.tbd、libz.1.2.5.tbd
• App 启动入口：接入 setAPNsForProduction:、setupNotification:
• 隐私同意后：接入 uploadPrivacyPermissionStatus
• 通知回调：注册 MobPushDidReceiveMessageNotification
• 视情况增加 getRegistrationID 示例或落点
• 如用户明确需要 Live Activity，再进入额外分支
• 生成项目内 MobPush_README.md

没有确认前，不要直接改。

第五步：执行工程修改

5-1 依赖接入

默认优先 CocoaPods：

• Podfile 中加入 pod 'mob_pushsdk'
• 若项目是 Swift 且需桥接 Objective-C API，优先复用已有 Bridging Header
• 若无 Bridging Header，创建 {Target}/mobpush_bridge.h 并写入：

#import \x3CMobPush/MobPush.h>
#import \x3CMOBFoundation/MOBFoundation.h>

• 同时在 .xcodeproj 的 Debug 和 Release 构建配置中设置 SWIFT_OBJC_BRIDGING_HEADER = "{Target}/mobpush_bridge.h"
• 若项目没有 Podfile，先说明将新增，再等待确认

如果用户明确要求手动导入：

• 只给出最小手动导入计划
• 不凭空修改 .xcodeproj 二进制文件
• 需要用户确认 SDK 解压目录和目标 Target

5-2 Info.plist

至少处理以下键：

• MOBAppKey
• MOBAppSecret
• MOBNetLater = 2

如果工程里已有同名键：

• 先展示现值
• 与 Excel 配置冲突时停止并询问用户

5-3 启动入口接线

根据工程入口类型选择落点：

• Objective-C：AppDelegate
• UIKit Swift：AppDelegate / SceneDelegate
• SwiftUI：@main App 对应的 UIApplicationDelegateAdaptor

最小接线包括：

• 按 DEBUG / 非 DEBUG 设置 setAPNsForProduction:
• 构造 MPushNotificationConfiguration
• 调用 setupNotification:
• 注册通知监听

Swift 示例（AppDelegate 核心接线）：

import UIKit
import UserNotifications

func application(_ application: UIApplication, didFinishLaunchingWithOptions: ...) -> Bool {
    #if DEBUG
    MobPush.setAPNsForProduction(false)
    #else
    MobPush.setAPNsForProduction(true)
    #endif

    let config = MPushNotificationConfiguration()
    config.types = MPushAuthorizationOptions.badge.union(.sound).union(.alert)
    MobPush.setupNotification(config)

    // ⚠️ 注意使用 Swift 重命名后的常量名
    NotificationCenter.default.addObserver(
        self,
        selector: #selector(didReceiveMobPushMessage(_:)),
        name: NSNotification.Name.MobPushDidReceiveMessage,
        object: nil
    )
    return true
}

如果工程已有自己的通知权限申请逻辑：

• 优先复用，不重复申请
• 仅补 SDK 必需部分

5-4 隐私合规接线

必须在用户同意隐私政策后插入：

• MobSDK uploadPrivacyPermissionStatus:YES onResult:...

如果用户拒绝隐私政策：

• 不得接入会实际调用 MobPush 能力的初始化流程

如果用户明确需要控制扩展业务数据采集：

• 再增加 MobCustomController 与 MOBFoundationPrivacyDelegate
• 否则不要提前写复杂隐私控制器

5-5 通知与业务回调

最小落地包括：

• 注册 MobPushDidReceiveMessageNotification
• 预留 didReceiveMessage: 或 Swift 等价方法
• 按需输出 MPushMessage 关键字段日志或注释

Swift 回调示例（注意 4.x 属性变化）：

@objc private func didReceiveMobPushMessage(_ notification: Notification) {
    guard let message = notification.object as? MPushMessage else { return }

    switch message.messageType {
    case .custom:
        // 自定义消息：notification.userInfo["mobpushCustomTitle"] / ["mobpushCustomType"]
        let body = message.notification.body ?? "自定义消息"
        // App 内展示
    default:
        // 推送通知 / APNs / 本地通知
        print(message.notification.body ?? "")
    }
}

如果用户明确需要：

• 再接 tag / alias / badge / local notification
• 这些能力默认不作为首轮硬接线项

5-6 Live Activity 可选分支

只有当用户明确要求并且工程满足 iOS 16.1+、SwiftUI、扩展 Target 条件时才执行：

• 提示添加 NSSupportsLiveActivities = YES
• 提示添加 ActivityKit.framework 与 SwiftUI.framework
• 提示新增 Live Activity Extension
• 接入 registerLiveActivityWithID:pushToken:completion:

Live Activity UI 与业务状态模型默认不代写完整业务实现，只保留官方能力落点和最小示例。

第六步：安装依赖与验证

在用户确认后才执行：

• pod install 或 pod update
• 注意：Ruby 4.0+ 环境下 pod install 可能因编码问题失败，需先设置环境变量：

  export LANG=en_US.UTF-8 && export LC_ALL=en_US.UTF-8
  pod install
  

• 必要时打开 *.xcworkspace

验证优先级：

1. Podfile.lock 中确认 mob_pushsdk
2. Info.plist 键值存在
3. 入口代码已接线
4. 代码搜索可命中 uploadPrivacyPermissionStatus、setupNotification
5. 如能编译，再做编译验证

如果不能实际运行真机推送测试，要明确说明：

• APNs 收包、证书有效性、后台推送链路未在当前环境完成验证

第七步：生成项目内说明文档

完成后在 {path} 下生成 MobPush_README.md，至少包含：

• 本次修改了哪些文件
• MOBAppKey / MOBAppSecret 放在哪里
• 隐私同意后调用链路在哪里
• 推送初始化入口在哪里
• APNs 鉴权材料还需用户在哪个平台完成
• 如果启用了 Live Activity，还需哪些额外工程配置
• 官方文档地址清单

优先使用本 skill 内的 templates/MOBPUSH_README.md 作为骨架，再结合实际项目修改点渲染。

交互约束

• 一次只问一个阻塞问题
• 自动可推断项优先从工程读取
• 只有当推断失败、存在多个候选值或发现冲突时才询问开发者
• 依赖安装是否代执行放到最后再问
• 如果某一步无需修改，应直接进入下一步
• 不要一次性抛出长问题清单

常用搜索关键字

• MobPush
• MOBAppKey
• MOBAppSecret
• MOBNetLater
• uploadPrivacyPermissionStatus
• setAPNsForProduction
• setupNotification
• MobPushDidReceiveMessageNotification
• getRegistrationID
• MOBFoundationPrivacyDelegate
• registerLiveActivityWithID