接入前调研：SDK 文档解读、API 接口梳理、平台兼容性要求
做 SDK 接入改造，第一步不是写代码，而是把文档吃透。我见过不少团队上来就照着 Demo 抄，结果遇到平台兼容性问题返工重来。这一节，我讲讲自己总结的调研流程，帮你少走弯路。
SDK 文档解读：别只扫一眼目录
拿到 SDK 文档，很多人的习惯是直接翻接入指南。我个人建议先读这四块：
- 架构总览：搞清楚 SDK 的模块依赖、生命周期、线程模型。有的 SDK 要求主线程初始化，有的必须异步，弄反了会崩溃。
- 版本变更日志：重点关注 break change 和废弃 API。我记得有一次升级 IM SDK，它的登录接口从同步改成了回调，我没留意日志，上线后用户登录失败。
- 权限 & 隐私声明：iOS 的 App Tracking Transparency、Android 的 Activity Recognition 权限，没提前申请会导致功能不可用。
- 混淆 & 瘦身规则：ProGuard、R8、iOS 的 bitcode，漏掉一条编译都过不去。
小技巧：把文档的重点用思维导图整理，便于后续团队同步。我习惯用 Markdown 写调研笔记，每个 API 备注常见坑。
API 接口梳理：分类 + 映射
API 文档一般几十个接口，不能逐个看。我按功能域分成几类：
- 生命周期接口：init、login、logout、destroy。关注同步/异步、重入安全性。
- 核心业务接口：比如支付 SDK 的支付下单、查询订单。注意参数类型、回调线程。
- 回调 & 通知：监听网络变化、推送事件。检查回调是否在主线程，是否需要保留引用。
- 配置接口：环境切换、日志开关、超时设置。这些容易被忽略，线上问题常常靠日志定位。
接着要映射到你们工程里现有的接口。可以画个对照表：
| SDK 接口 | 现有接口 | 差异点 | 工作量评估 |
|---|---|---|---|
| PayManager.createOrder() | PaymentService.pay() | 参数顺序不同，需要适配层 | 中 |
| PayManager.onPayResult | PayResultReceiver | 回调线程不一致，需切换 | 小 |
| PayManager.init(context, appId) | —（无对应） | 需新增初始化时机 | 大 |
关键原则：不要改造 SDK 源码。如果发现接口无法满足需求，优先通过封装层适配，而不是修改第三方库。
平台兼容性要求：一张表搞定
现在 SDK 基本都支持 iOS、Android、Web、小程序。但每个平台的限制天差地别。我做过一个多平台项目，踩的坑可以写一本书。
iOS
- 最低部署版本：SDK 要求的 iOS 版本是否高于你们的？比如 SDK 最低 iOS 13，你们项目还支持 iOS 12，那就得找旧版本或自制兼容层。
- 架构：arm64、x86_64 模拟器支持。真机跑不通模拟器能跑，大概率是缺少 x86 切片。
- App Store 合规：是否有使用私有 API？是否需要提供隐私清单？
Android
- API 级别：同样检查 minSdk、targetSdk。注意 SDK 可能要求 Android 8.0 以上，而你们项目还要支持 6.0。
- ABI 分裂：armeabi-v7a、arm64-v8a、x86。每个架构都要有对应的 so 文件，不然某些机型直接闪退。
- 厂商兼容：华为、小米、OPPO 等对某些权限有特殊限制。我在华为手机上遇到过后台定位权限被系统默认拒绝。
Web
- 浏览器兼容：Chrome、Safari、Edge 以及微信内置浏览器。ES6+ 语法需要转译。
- 跨域 & HTTPS：SDK 是否要求 https，是否支持 CORS。有的老机器上地址通信用 http 会报混合内容错误。
- 无痕模式：localStorage、indexedDB 在无痕模式下可能不可写。我曾遇到 SDK 往 localStorage 写缓存，用户开无痕就挂了。
小程序
- 平台限制：微信、支付宝、字节小程序 API 完全不同。SDK 是否提供了对应的小程序版本？通常需要单独适配。
- 包体积：小程序有 2MB 限制（后来扩到 8MB 但仍有阈值）。SDK 如果很胖，得做分包或按需加载。
- 用户授权：小程序登录、支付都需要用户主动触发。SDK 内部如果悄悄调用 wx.login 会被拒绝。
我曾经犯过的错：一个支付 SDK 在 iOS 16 上用了
UIScreen.main.bounds 获取安全区域，结果 iPhone 14 Pro 的 Dynamic Island 导致布局错乱。后来我们设立了“最新系统 + 刘海屏 + 新尺寸”的必测矩阵。
综合评估：走到这步，该出调研报告了
把所有信息汇总成文档，至少包含：
- SDK 核心依赖清单（framework、aar、npm 包）
- 所有需要改动的代码位置（初始化、接口调用、回调处理）
- 平台兼容性矩阵（iOS 版本、Android 版本、浏览器版本、小程序基础库）
- 风险项列表 & 应对方案（比如旧系统不支持用什么 polyfill）
拿这个报告去和产品、测试对齐，比直接写代码高效得多。我每次启动新 SDK 接入都会用相同的模板，团队沟通成本降低了一大截。
接入前调研核心知识体系
这张图是思路主干。实际做的时候，每读一个接口都要在文档里标注「是否异步」「是否主线程」「能否重入」——这些细节恰恰是后期排查问题的关键。你想想看，如果初始化线程不对，用户会直接闪退，连日志都来不及看。所以，调研阶段多花一天，测试阶段少加一周班。