--- name: ios-flyverify-integration description: 面向 iOS 工程的 MobTech FlyVerify(秒验) 集成 skill。默认先扫描工程，优先使用 CocoaPods，以最小改动完成依赖接入、隐私合规、一键登录流程接线和项目内说明文档落地。 tags: - ios - flyverify - 秒验 - sdk-integration - mobtech - one-click-login - cocoapods - privacy - objective-c - swift --- # iOS FlyVerify 集成 Skill 当用户希望把 MobTech FlyVerify 集成到 iOS 工程，或者排查已有 FlyVerify 接入问题时，使用本 skill。 ## 适用场景 当用户提到以下任一主题时，使用本 skill： - iOS FlyVerify 集成 - iOS 秒验接入 - iOS 一键登录 - MobTech 秒验一键登录 - FlyVerify CocoaPods 配置 - FlyVerify `Info.plist` 配置 - FlyVerify 隐私合规 - `agreePrivacy` 调用时机 - `preLogin` / `openAuthPageWithModel` 用法 - 秒验授权页自定义 - 秒验 token 置换手机号 - 帮我在 iOS 项目里增加一键登录 - 帮我把 FlyVerify 接进现有 iOS 工程 如果用户问题明确与 iOS 秒验接入、工程配置、隐私合规、一键登录流程或授权页 UI 定制有关，应优先使用本 skill。 ## 输出语言 - 默认使用中文与用户沟通 - 代码、配置键名、类名、命令名保持原文 - 回答尽量短，先给结论，再给动作 ## 官方资料 优先使用以下线上资料，不依赖本机资料路径： 主文档： - [MobTech 文档中心](https://www.mob.com/wiki/list) - [秒验产品页](https://www.mob.com/mobService/secverify) - [SDK 下载中心](https://www.mob.com/download) - [集成指南](https://www.mob.com/wiki/detailed?wiki=531&id=78) - [SDK API 文档](https://www.mob.com/wiki/detailed?wiki=297&id=78) - [合规指南](https://www.mob.com/wiki/detailed?wiki=217&id=78) - [秒验隐私政策](https://policy.zztfly.com/sdk/verify/privacy) - [创建应用流程](https://www.mob.com/wiki/detailed?wiki=538&id=78) - [秒验审核流程](https://www.mob.com/wiki/detailed?wiki=159&id=78) - [服务端接入文档](https://www.mob.com/wiki/detailed?wiki=157&id=78) - [秒验 SDK 扩展业务功能设置](https://www.mob.com/wiki/detailed?wiki=669&id=78) - [其它 App 数据采集主动控制器配置](https://www.mob.com/wiki/detailed?wiki=675&id=714) - [App Store Connect 后台配置参考文档](https://www.mob.com/wiki/detailed?wiki=289&id=172) - [秒验 Demo](https://github.com/MobClub/FlyVerify_For_iOS) 如果某个深链失效，先从 [MobTech 文档中心](https://www.mob.com/wiki/list) 搜索对应标题，不要回退到本机绝对路径。 ## 已确认的官方事实 以下信息已经可作为执行依据，不需要再猜测： - 默认开发环境要求为 `Xcode 9.1.0+`、`iOS 8.0+` - 官方支持 `CocoaPods` 和手动导入两种集成方式 - 默认 Pod 为 `pod 'FlyVerify'` - 工程需要链接 `libsqlite3.tbd`、`libc++.tbd`、`libz.1.2.5.tbd` - `Other Linker Flags` 需要添加 `-ObjC` - `Info.plist` 需要配置 `flyverifykey` 与 `flyverifysecret` - 严格隐私模式需要在默认 `plist` 中添加 `FlyVerifyPLevel = 2` - 如果项目全局禁止 HTTP，需要为以下域名配置 ATS 白名单： - `zzx9.cn` - `cmpassport.com` - `id6.me` - `wostore.cn` - `mdn.open.wo.cn` - `agreePrivacy` 是 FlyVerify 业务起点，必须在用户同意隐私政策后、使用 SDK 能力前调用 - `preLogin` 回调在全局队列，`error == nil` 才视为成功 - `openAuthPageWithModel` 的 `uiConfigure.currentViewController` 为必传 - 授权页关闭可由 SDK 自动处理，也可通过 `manualDismiss = @(YES)` 后手动调用 `finishLoginVcAnimated:Completion:` - 一键登录成功后 SDK 返回 `opToken`、`operator`、`token` - 真实手机号需要开发者服务端调用秒验服务端接口完成置换，客户端不能直接得到手机号 - 一键登录能力依赖运营商网关取号，必须在手机开启移动蜂窝网络时使用 - 文档明确建议授权页 UI 定制参考官方 Demo - 严格隐私模式和隐私 API 支持情况必须结合线上合规文档与当前 `Podfile.lock` 中实际安装版本确认，不要只凭本地缓存判断 - 接入代码必须同时支持 Objective-C 与 Swift 工程；Swift 工程优先通过桥接头调用官方 Objective-C API ## 文档未明确，需向用户确认 以下内容在当前资料里没有被稳定、明确地定义，禁止猜： - 是否支持 Swift Package Manager - 是否需要 Bitcode、Privacy Manifest 或额外苹果隐私文件 - 用户项目应该使用 `Info.plist` 配置读取，还是代码显式 `initKey:secret:privacyLevel:` - 用户具体要不要开启授权页自定义 如果缺这些信息且会阻塞安全修改，必须明确写： `文档未明确，需向用户确认` ## 默认执行策略 - 默认集成方式：`CocoaPods` - 默认先扫描工程，再给改动方案 - 默认优先复用工程已有隐私弹窗和登录入口，不新造页面 - 默认先生成最小 Excel 模板，再等用户填写 - 默认不在 Excel 中收集 `Bundle ID`、Target 名称、入口类名、`Info.plist` 路径，因为这些应由扫描工程自动推断 - 默认把 FlyVerify 能力接入放在用户已同意隐私政策之后 - 默认不主动询问是否启用扩展业务主动控制器；仅在最终项目文档中说明这项可选能力 - 服务端 token 置换接口属于后续业务步骤，本轮客户端集成只保留注释占位，不追问接口域名、鉴权方式或返回结构 - 默认不运行 `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` - 隐私政策弹窗或同意回调位置 - 登录页、手机号登录页、现有一键登录入口 - Objective-C / Swift / 混编类型，以及是否已有 Bridging Header - 是否已有 `FlyVerify`、`FVSDKHyVerify`、`FlyVerifyC`、`flyverifykey`、`flyverifysecret`、`FlyVerifyPLevel` - `.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 'FlyVerify|FVSDKHyVerify|FlyVerifyC|flyverifykey|flyverifysecret|FlyVerifyPLevel|agreePrivacy|preLogin|openAuthPageWithModel|SWIFT_OBJC_BRIDGING_HEADER'` 扫描后先给一段简短结论，至少包含： - 当前工程依赖方式 - 当前入口结构 - 当前代码语言形态：Objective-C / Swift / 混编 - Swift 工程是否已有 Bridging Header - 是否已有 FlyVerify 残留 - 是否已经有隐私同意链路 - CocoaPods 状态：是否有有效 `Podfile`、`Podfile.lock`、`Pods/`、`*.xcworkspace/contents.xcworkspacedata` - 下一步是生成模板还是读取已有 `FlyVerify_iOS_Config.xlsx` ## 第二步：生成并读取配置模板 ### 2-1 模板生成 如果用户项目根目录还没有 `FlyVerify_iOS_Config.xlsx`： 1. 运行本 skill 目录下的 `assets/generate_excel_template.py` 2. 将生成的 `assets/FlyVerify_iOS_Config_Template.xlsx` 复制到用户项目根目录 3. 在用户项目根目录命名为 `FlyVerify_iOS_Config.xlsx` ### 2-2 向用户说明填写项 必须明确告诉用户只需要填写这些最小字段： - `appKey` - `appSecret` - 秒验审核是否已通过 - 是否需要自定义授权页 同时明确说明以下内容不需要填表： - `Bundle ID` - `Target` - `Info.plist` 路径 - 隐私弹窗类名 - 授权页按钮落点 - 是否启用扩展业务主动控制器 其中工程信息应由 Agent 扫描后推断；扩展业务主动控制器不作为前置配置项，只在最终文档中说明。 ### 2-3 配置校验 读取 `FlyVerify_iOS_Config.xlsx` 后，至少校验： - `appKey`：必填，按字符串处理，不做数值推断 - `appSecret`：必填，按字符串处理，不做数值推断 - `秒验审核`：必须明确是 `是` / `否` - `授权页自定义`：必须明确是 `是` / `否` 如不合法，列出具体问题并要求用户修正，不要继续改工程。 ## 第三步：扫描后推断工程接入点 读取配置后，再次结合工程做推断： - 优先识别主要 App Target - 推断 Objective-C / Swift / 混编 - 记录当前工程要使用 Objective-C 示例、Swift 示例还是两者都需要 - Swift 工程需检查是否已有 `{Target}-Bridging-Header.h` 与 `SWIFT_OBJC_BRIDGING_HEADER` - 定位疑似隐私同意回调位置，后续仍必须向用户确认 - 推断一键登录入口页或手机号登录页 - 推断当前是否已有 CocoaPods 体系 - 推断是否已有 ATS 配置、`-ObjC`、系统库链接 - 判断已有 `*.xcworkspace` 是否有效；只有目录但缺少 `contents.xcworkspacedata` 时，应运行 `pod install` 重新生成 - 判断已有 `Pods/` 是否完整；如果只有空 framework 目录或缺少 `Info.plist`、Headers、binary，不要按手动 SDK 接入硬改工程，应优先重新 `pod install` 以下信息必须分两类处理： ### 必须在修改前确认的信息 - 多 Target 时应该接入哪个 App Target - 用户同意隐私政策后的回调位置。即使扫描到疑似隐私弹窗，也要让用户确认 `agreePrivacy` 应插入到哪个“同意”回调 - 用户明确不想用 CocoaPods，必须改走手动导入 ### 可以在扫描后逐步确认的信息 - 是否需要自定义授权页样式 - `preLogin` 放在 `viewDidLoad`、按钮前预热还是其他业务时机 如果必须确认，串行一次只问一个问题。 ## 第四步：展示最小改动计划 修改前必须向用户展示本次最小改动计划，通常包括： - `Podfile`：按需加入 `pod 'FlyVerify'` - `.gitignore`：按需加入 `Pods/` - `Info.plist`：写入 `flyverifykey`、`flyverifysecret`、`FlyVerifyPLevel` - Xcode 构建设置：补 `-ObjC` - Swift 工程：新增或复用 Bridging Header，并配置 `SWIFT_OBJC_BRIDGING_HEADER` - 视情况补 ATS 白名单或提示用户已有配置可复用 - 在隐私同意后插入 `agreePrivacy` - 在登录链路中接入 `preLogin` 与 `openAuthPageWithModel` - 在 token 成功回调后保留服务端置换手机号逻辑注释占位 - 生成项目内 `FlyVerify_README.md` 没有确认前，不要直接改。 ## 第五步：执行工程修改 ### 5-1 依赖接入 默认优先 `CocoaPods`： - 在正确的 target 下加入 `pod 'FlyVerify'` - 如项目没有有效 workspace，运行 `pod install` 后确认 `*.xcworkspace/contents.xcworkspacedata` 已生成 - `pod install` 可能需要写用户级 CocoaPods cache；如遇 `~/Library/Caches/CocoaPods` 权限错误，应按当前执行环境申请授权后重试 - 若 `pod install` 修改 `.xcodeproj`，不要再手写重复的 Pods framework、xcconfig、shell script phase - 只有用户确认后才执行 `pod install` 如果用户明确要求手动导入： - 按官方资料把下载的 SDK 拖入工程 - 检查并补系统库、`-ObjC` 与 `Info.plist` ### 5-2 `Info.plist` 配置 默认写入或校正： - `flyverifykey` - `flyverifysecret` - `FlyVerifyPLevel = 2` ATS 处理规则： - 若工程已全局允许 HTTP，不重复扩大权限 - 若工程禁用 HTTP，则按官方域名白名单最小化添加 - 若工程已有等价白名单，复用现有配置，不重复写 ### 5-3 隐私合规接入 在用户同意隐私政策后、首次使用 FlyVerify 能力前接入： ```objective-c #import [FlyVerifyC agreePrivacy:YES onResult:nil]; ``` Swift 工程必须先确保桥接头可访问 SDK 头文件： ```objc #import #import ``` 然后在用户同意隐私政策后的 Swift 回调中调用： ```swift FlyVerifyC.agreePrivacy(true, onResult: nil) ``` 如果用户明确采用代码初始化方案，才补： ```objective-c [FlyVerifyC initKey:@"" secret:@"" privacyLevel:2]; ``` 否则优先沿用 `Info.plist` 配置，不同时强塞两套初始化方案。 ### 5-4 登录流程接入 建议流程： 1. 用户同意隐私政策后调用 `agreePrivacy` 2. 在即将进入一键登录前调用 `preLogin` 3. 在主线程拉起 `openAuthPageWithModel` 4. 成功返回 `token` / `opToken` 后保留服务端置换手机号注释占位 接入时必须注意： - `preLogin` 成功判断以 `error == nil` 为准 - `preLogin` 回调不是主线程，涉及 UI 必须切回主线程 - `currentViewController` 必须传当前页面或顶层页面 - 如果 `manualDismiss = @(YES)`，成功或失败后按业务自行关闭授权页 - Objective-C 与 Swift 工程都要提供对应语言代码；Swift 工程通过桥接头调用 `FVSDKHyVerify` 与 `FVSDKHyUIConfigure` - Swift 调用 `openAuthPageWithModel:openAuthPageListener:cancelAuthPageListener:oneKeyLoginListener:` 时，首参标签应为 `withModel:`，不是 `with:` - 服务端 token 置换接口的具体域名、鉴权方式、返回结构不在当前客户端集成步骤中追问，只在代码中以 `TODO` 注释标明 ### 5-5 授权页 UI 定制 只有用户明确需要时，才继续改 UI。 优先通过以下方式做最小定制： - `FVSDKHyUIConfigure` 基本属性 - `FVSDKVerifyDelegate` - `fvVerifyAuthPageViewDidLoad:userInfo:` 中设置布局或自定义控件 若用户要复杂弹窗、暗黑模式、横竖屏、自定义 loading、协议页接管，优先提示参考官方 Demo 与线上文档： - [秒验 Demo](https://github.com/MobClub/FlyVerify_For_iOS) - [MobTech 文档中心](https://www.mob.com/wiki/list) ## 第六步：验证与说明文档 完成改动后，按条件执行： - 若用户确认，可运行 `pod install` - 若环境允许，可运行一次构建验证；FlyVerify 依赖运营商库，优先验证 `generic/platform=iOS` 真机目标 - 不要把模拟器构建失败直接等同于集成失败；若错误类似 `building for 'iOS-simulator', but linking in object file ... built for 'iOS'`，说明某运营商 framework 只有真机切片，应改用真机目标验证 - Xcode 15+ 如遇 CocoaPods `[CP] Copy Pods Resources` 被 User Script Sandboxing 拦截，可在目标 Build Settings 中将 `ENABLE_USER_SCRIPT_SANDBOXING = NO`，或用等价命令行参数验证 - 如果普通沙箱下 `xcodebuild` 无法访问 CoreSimulator 或 Xcode 用户目录，应按当前环境申请授权后重试 - 若无法构建，明确说明未验证的原因 然后生成项目内 `FlyVerify_README.md`，至少包含： - 本次改动点 - `appKey` / `appSecret` 的配置位置 - `agreePrivacy` 的调用位置 - `preLogin` 与授权页拉起位置 - Objective-C / Swift 支持情况与桥接头配置情况 - CocoaPods 版本信息：`Podfile`、`Podfile.lock`、实际安装的 FlyVerify / FlyVerifyCSDK 版本 - 构建验证结果：真机目标、模拟器限制、剩余 warning - 服务端 token 置换属于后续业务步骤，当前只保留注释占位 - 扩展业务主动控制器是可选能力；如未来需要控制地理位置、WiFi、IP 等扩展业务数据采集，可参考官方扩展业务文档接入 `FlyVerifyCPrivacyDelegate` - 常见错误码排查入口 - 官方文档链接清单 ## 常见错误排查原则 遇到失败时优先检查： - 秒验审核是否已通过 - 手机是否开启移动蜂窝网络 - `agreePrivacy` 是否在隐私同意后已调用 - `currentViewController` 是否为当前顶层可 `present` 的 VC - `flyverifykey` / `flyverifysecret` 是否和后台一致 - ATS 是否拦截了运营商或 SDK 请求 - Swift 首参标签是否使用了 `withModel:` - 是否用真机目标验证，而不是只看模拟器构建结果 - CocoaPods workspace 是否有效生成 ## 与用户沟通的硬约束 - 一次只问一个阻塞问题 - 没有阻塞就不要追问，直接推进 - 每次修改前先展示计划 - 执行 `pod install` 或构建前先征求确认 - 如果某项无需修改，要明确说“无需修改”