sumsub-integrate-msdk

Sumsub — 移动 SDK 集成（iOS 和 Android）

通过 IdensicMobileSDK 框架（主类 SNSMobileSDK），将 Sumsub KYC 嵌入现有原生应用，涵盖从安装依赖到展示／启动验证流程的所有步骤，适用于 iOS（Swift）或 Android（Kotlin）。

这是 主干：阅读下方始终适用的部分（信息收集、询问与执行），检测平台，然后使用决策表，仅打开与平台、项目和用户回答相匹配的分支文件。

信息收集 — 先在一条消息中询问以下三个问题

在查看任何项目文件之前，一次性询问以下全部问题：

1. 启动位置。“您希望从哪个屏幕打开 Sumsub 流程？请提供类名或描述该屏幕。”—— iOS： ViewController 或 SwiftUI 视图；Android： Activity、Fragment 或 Composable。

2. 访问令牌来源。“您的应用是否已有从后端获取 Sumsub 访问令牌的方式？（如果有，请提供函数名、端点 URL 或服务类。如果没有，我会添加一个占位内容，等您的后端准备就绪后再填写。）”

3. 可选模块。“基础 SDK 支持标准验证流程，始终会安装。除此之外，您还需要以下哪些附加组件？

   • NFC（护照／eMRTD 芯片读取）—— iOS： MRTDReader；Android： nfc 模块——读取生物识别护照中的芯片
   • VideoIdent——与审核员进行实时视频通话
   • EID——读取德国电子身份证
   • Fisherman / Device Intelligence——欺诈信号 (iOS：可选模块；Android：自 1.43.0 起已捆绑在基础 SDK 中——无需额外添加) 如果不确定，可以先跳过——之后仍可添加。”

   模块仅用于扩展功能。进行多选时，只列出所需模块——不选择任何模块就表示“仅使用基础 SDK”；不要将“仅使用基础 SDK”作为可与其他模块并列选择的选项。

不要询问 App Token 或密钥——这些属于服务器端事务，不会涉及应用。

询问与执行 — 让审批有意义

• 只读操作无需审批——扫描／grep／读取 Info.plist、AndroidManifest.xml 和构建文件，无需询问。
• 将修改合并到一次审批中，不要每行都单独询问（“我会添加以下 3 个 Info.plist 键 [列表]，以及此调用位置 [差异]——是否应用？”）。
• **仅在以下情况明确询问：**编辑现有应用代码、会修改项目的命令（pod install、Gradle 同步）、不可逆操作，以及无法在信息收集阶段确定的事项。

检测平台（在打开任何分支文件之前执行）

判断这是 iOS 还是 Android 项目——安装步骤、权限模型和生成的语言各不相同。此操作为只读。

# iOS markers
find . -maxdepth 3 \( -name '*.xcodeproj' -o -name '*.xcworkspace' -o -name 'Podfile' -o -name 'Package.swift' \) 2>/dev/null
# Android markers
find . -maxdepth 3 \( -name 'build.gradle' -o -name 'build.gradle.kts' -o -name 'settings.gradle*' -o -name 'AndroidManifest.xml' \) 2>/dev/null

• 仅有 iOS（有 .xcodeproj／Package.swift／Podfile，没有 Gradle）→ iOS 路线。
• 仅有 Android（有 build.gradle[.kts]／AndroidManifest.xml，没有 Xcode）→ Android 路线。
• 两者都有（单体仓库，或带有原生目录的 React-Native / Flutter 外壳）→ 报告两个平台，并**询问要集成哪个平台。**每次只处理一个平台。（React Native / Flutter 封装本身不在范围内——此技能针对原生 SDK；检测到封装后，步骤 1 的扫描会停止。）
• 两者都没有 → 请用户指出应用源码根目录。

如果平台判断存在任何歧义，请确认检测到的平台，然后遵循对应路线。

如何使用此技能

信息收集完成后，仅打开与检测到的平台、项目（来自步骤 1）和用户回答相匹配的行。每个分支文件均独立完整，并以 Next 指引结束。字母（2A/2B、6A/6B）表示分支——选择其中一个；纯数字步骤按顺序执行。

iOS 流程

步骤	条件	阅读
1. 扫描	始终（首先，在接收信息后）	ios/stages/1-scan.md
2A. 安装 — CocoaPods	选择了 CocoaPods（根据步骤 1）	ios/stages/2a-install-cocoapods.md
2B. 安装 — SPM	选择了 SPM（根据步骤 1；默认选项）	ios/stages/2b-install-spm.md
3. 权限与功能	始终	ios/stages/3-permissions.md
4. 集成文件	始终	ios/stages/4-integration-code.md
5. 接入目标	始终（创建文件后立即执行）	ios/stages/5-wire-target.md
6A. 启动 — UIKit	宿主是 UIKit ViewController	ios/stages/6a-launch-uikit.md
6B. 启动 — SwiftUI	宿主是 SwiftUI 视图	ios/stages/6b-launch-swiftui.md

Android 流程

步骤	条件	阅读
1. 扫描	始终（首先，在接收信息后）	android/stages/1-scan.md
2. 安装 — 依赖项	始终	android/stages/2-install-dependencies.md
3. 集成文件	始终（Gradle 会自动编译 — 无需执行接入目标步骤）	android/stages/3-integration-code.md
4. 启动	始终	android/stages/4-launch.md

备用方案（仅限最后手段）。 此技能及其分支文件是主要信息来源 — 默认不要查阅外部文档。只有遇到这些文件无法解决的真正阻碍时，才查阅 Sumsub 文档： iOS · Android。

遍历完目录树后，返回此处查看 防护措施 和 交接。

防护规则 — 此技能绝不能做的事

• 先检测平台 — 绝不能将 Swift 写入 Android 项目，也不能将 Kotlin 写入 iOS 项目；如果两者都存在，请询问要集成到哪个平台。
• 绝不编辑现有应用代码，用户在信息收集阶段批准的单个目标调用点除外。
• （iOS）让 SDK 自行呈现，包括在 SwiftUI 中。 始终通过 SumsubVerification.start() 启动（sdk.present() / sdk.present(from:)）。绝不能在整个流程中强持有 SDK 或其 mainVC，也绝不能将 sdk.mainVC 嵌入 SwiftUI 的 .fullScreenCover / .sheet。mainVC 会强持有 SDK，而 SDK 会在该控制器的 dealloc 时触发 onDidDismiss；自行持有它会延迟清理，并导致“隔次才能打开”以及重新打开时崩溃。SDK 负责呈现和关闭 — 由一个所有者负责，确保可以正常重新打开。
• （Android）绝不添加相机/麦克风权限或运行时权限请求 — SDK 会自行声明并请求这些权限；自行添加可能会导致重复请求或冲突。
• （Android）令牌刷新处理程序是同步的 — onTokenExpired() 必须在后台线程返回令牌；使用 runBlocking 桥接挂起式令牌调用，不要使用 iOS 的 async/callback 模式。
• 未经用户在当前消息中明确许可，绝不运行会修改项目的命令（pod install、Gradle 同步/构建）。
• 绝不询问或提及 App Token 或密钥 — 令牌由服务器端生成。
• 绝不在任何应用文件中存储或提及 App Token 或密钥。
• 绝不静默覆盖现有的 Info.plist / AndroidManifest 值 — 始终先展示当前值并征求同意。
• 绝不在此技能中应用主题更改 — 样式调整应在 sumsub-theme-msdk 中进行。
• 绝不根据应用内回调决定是否允许访问 — 权威判定来自后端（webhook + applicant GET），而不是 SDK 回调。

交接

所有更改完成后，清晰地总结：

1. 创建/修改的文件 — 列出每个文件，并用一句话说明。
2. 需要补充实现的存根 — 如果令牌获取逻辑是占位内容，请明确说明，并描述用户需要实现什么。（Android 上是单个 SumsubTokenProvider.fetchAccessToken 挂起函数 — 启动器会在会话中途刷新时复用它。）
3. 构建步骤 — iOS：“运行 pod install，然后打开 .xcworkspace 并构建”，或“构建并运行 — SPM 包会自动解析”；Android：“同步 Gradle，然后构建并运行”。
4. 测试方法 — 说明：从后端获取沙盒访问令牌（或暂时硬编码一个），从启动点触发验证（iOS：SumsubVerification.start(…)；Android：由副作用使屏幕调用 SumsubLauncher.present(…) 的 ViewModel 操作），并确认 Sumsub 流程出现。（NFC 模块需要使用实体设备 — 不能使用 iOS 模拟器 / Android 模拟器。）
5. 权威来源 — 提醒用户：最终验证结果来自后端 webhook + applicant read，而不是 SDK 回调。
6. 后续步骤 — 指引用户前往 sumsub-theme-msdk 进行样式调整（iOS 和 Android）。