在原生 iOS/Android 应用中集成 Sumsub…

当需要把 Sumsub KYC 验证嵌入现有原生 iOS（Swift）或 Android（Kotlin）应用时，从安装依赖到拉起验证流程的完整做法。

适用场景

解决思路

1. 先一次性问清三个问题：1）从哪个界面启动 Sumsub 流程（iOS 的 ViewController/SwiftUI 视图，Android 的 Activity/Fragment/Composable）；2）应用是否已有从后端获取 Sumsub access token 的方式（有则给出函数名/端点/服务类，没有则先加占位符）；3）是否需要可选模块（NFC、VideoIdent、EID、Fisherman/Device Intelligence），基础 SDK 始终安装，模块纯增量，不确定可跳过。不要询问 App Token 或 secret key（属于服务端）。
2. 只读操作（扫描/grep/读取 Info.plist、AndroidManifest.xml、构建文件）无需请求批准；把多处修改合并成一次审批；仅在编辑现有应用代码、执行改动项目的命令（pod install、Gradle sync）、不可逆操作或 intake 未决事项时才显式询问。
3. 先检测平台：用 find 查找 iOS 标记（*.xcodeproj、*.xcworkspace、Podfile、Package.swift）和 Android 标记（build.gradle、build.gradle.kts、settings.gradle*、AndroidManifest.xml）。仅 iOS → 走 iOS 轨道；仅 Android → 走 Android 轨道；两者都有（monorepo 或 RN/Flutter 原生壳）→ 报告两者并询问集成哪个平台，一次只做一个平台；都没有 → 让用户指出应用源码根目录。
4. iOS 轨道按顺序执行：1）扫描；2A）用 CocoaPods 安装（若选 CocoaPods）或 2B）用 SPM 安装（默认）；3）配置权限与 capabilities；4）创建集成文件；5）接入 target；6A）若宿主是 UIKit ViewController 则按 UIKit 方式启动，或 6B）若宿主是 SwiftUI 视图则按 SwiftUI 方式启动。
5. Android 轨道按顺序执行：1）扫描；2）安装依赖；3）创建集成文件（Gradle 自动编译，无需接入 target 步骤）；4）启动。
6. iOS 上始终通过 SumsubVerification.start()（sdk.present() / sdk.present(from:)）让 SDK 自行展示与关闭；绝不在整个流程中强持有 SDK 或其 mainVC，也绝不把 sdk.mainVC 桥接进 SwiftUI 的 .fullScreenCover / .sheet（mainVC 会强持有 SDK，且 SDK 从该控制器的 dealloc 触发 onDidDismiss，自行持有会延迟销毁，导致“隔次打开”并在重开时崩溃）。
7. Android 上不要自行添加相机/麦克风权限或运行时请求（SDK 自己声明并请求，自行添加会重复弹窗或冲突）；token 刷新处理器是同步的，onTokenExpired() 必须在后台线程返回 token，用 runBlocking 桥接 suspend 的 token 调用，而不是 iOS 的 async/回调模式。
8. 绝不把 Swift 写进 Android 项目或把 Kotlin 写进 iOS 项目；绝不编辑 intake 中用户批准的目标调用点之外的现有应用代码；绝不在未获当前消息中明确许可时执行改动项目的命令（pod install、Gradle sync/build）；绝不询问、引用或存储 App Token 或 secret key；绝不静默覆盖已有的 Info.plist / AndroidManifest 值（先展示当前值再询问）；绝不在此技能中应用主题改动（样式属于 sumsub-theme-msdk）；绝不用应用内回调作为访问判定依据（权威结论来自后端 webhook + applicant GET）。
9. 仅在遇到分支文件无法解决的真实阻塞时，才查阅 Sumsub 官方文档（iOS: https://docs.sumsub.com/docs/get-started-ios，Android: https://docs.sumsub.com/docs/get-started-android）。
10. 完成后交接总结：1）列出创建/修改的文件及一句话说明；2）若 token 获取是占位符，明确说明并描述用户需实现的内容（Android 上是单个 SumsubTokenProvider.fetchAccessToken suspend 函数，launcher 会复用它做会话中刷新）；3）构建步骤（iOS：运行 pod install 后打开 .xcworkspace 构建，或 SPM 自动解析直接构建运行；Android：Sync Gradle 后构建运行）；4）如何测试：从后端获取 sandbox access token（或临时硬编码），从启动点触发验证（iOS: SumsubVerification.start(…)，Android: ViewModel 动作使界面调用 SumsubLauncher.present(…)），确认 Sumsub 流程出现（NFC 模块需真机，不能用 iOS 模拟器/Android 模拟器）；5）提醒最终验证结果来自后端 webhook + applicant 读取，而非 SDK 回调；6）下一步指向 sumsub-theme-msdk 做样式。

适用边界 · 注意事项

• Web 端集成（用 sumsub-integrate-websdk）
• 仅后端/API 的 token 签名（用 sumsub-api-generic）
• 主题定制（用 sumsub-theme-msdk）以及 React Native / Flutter（不支持，仅原生 iOS 与 Android）