📚 课程目录第2章 SDK接入基础

SDK 接入基础：集成流程、环境准备、依赖管理

说实话，SDK 接入这件事，看着挺简单的。不就是把几个文件拖进去，改几行配置吗？但我在项目里见过太多接入到一半卡住，或者编译报错一脸懵的情况。其实，痛点往往就出在最基础的环节。这一章，我就带你系统捋一遍，把地基打扎实。

一、SDK 集成流程——三步走

不管你接的是广告 SDK、支付 SDK 还是推送 SDK，核心流程就三步。我习惯把它叫做「拉、配、验」。

1. 拉——获取 SDK 资源

先从官方渠道拿东西。一般就两种形式：

下载压缩包：里面是 .aar、.framework、.jar、.bundle 等。
托管仓库地址：maven、CocoaPods、npm 等。

我的习惯：优先用仓库形式。手动拖 aar 经常丢文件，版本也不好追溯。

2. 配——集成到项目

把 SDK 文件放到项目里，然后告诉构建工具：嘿，老子要用它。这部分有手动和自动两种，后面详细说。

3. 验——验证接入成果

跑一下编译，然后看日志。SDK 正常初始化后，一般会在 logcat 或者 Xcode console 里打印「SDK init success」之类的标志。没有？那一定哪里断了。

二、环境准备——这部分偷懒，后面全是坑

环境问题，是新手遇到最多的坑。环境不对，后面所有操作都是瞎忙活。我曾经帮一个团队排查问题，折腾了两天，最后发现是 JDK 版本不兼容。

2.1 你需要检查的清单

维度	Android	iOS
IDE	Android Studio 4.0+	Xcode 12.0+
构建工具	Gradle 6.5+	CocoaPods 1.10+
SDK 最低版本	minSdkVersion 19+	iOS 10.0+
语言	Java 8 / Kotlin 1.5	Swift 5.0 / Objective-C
网络环境	可访问 jcenter / mavenCentral	可访问 CocoaPods Trunk

注意：很多 SDK 的下层依赖会用 Java 8 的 API。如果你的项目还卡在 Java 7，那肯定编译失败。升级 compileOptions 到 Java 8 是基本功。

2.2 网络代理的问题

在公司内网，经常要配代理才能拉依赖。我在项目里见过有人配错了代理地址，结果 gradle 一直卡在 downloading 状态。正确的做法是：

// gradle.properties
systemProp.http.proxyHost=your-proxy
systemProp.http.proxyPort=8080
systemProp.https.proxyHost=your-proxy
systemProp.https.proxyPort=8080

如果是 iOS，CocoaPods 走 http 代理可能需要设置环境变量 export http_proxy=...。嗯，这里要注意，代理配不好，pod install 就永远转圈。

三、依赖管理——两种方式，各有千秋

说白了，就是把 SDK 加入项目依赖。通常有两种方式：手动导入和自动化依赖管理器。

3.1 手动导入

把 .aar 或 .framework 直接丢进项目。Android 放在 app/libs 目录，iOS 拖进 Embedded Binaries。

优点：直观，不依赖第三方工具。缺点：升级痛苦，每次都要手动替换文件；而且传递依赖需要你自己去找。

举个例子，你要接一个推送 SDK，它内部引用了 okhttp。手动导入时，你必须也把 okhttp 的 jar 放到 libs 里。如果版本没对齐，那就等着运行时 crash 吧。

3.2 自动化依赖管理器

通过 Gradle / CocoaPods / SPM 来声明。我强烈推荐这种方式。

Android (Gradle)

// app/build.gradle
dependencies {
    // 从 jcenter / mavenCentral 拉
    implementation 'com.example:sdk-core:2.1.0'
    // 也可以指定本地 aar
    implementation files('libs/sdk-local.aar')
}

这里有一个关键点：implementation 和 api 的区别。我曾经被这个坑过。用 implementation 的话，SDK 内部的依赖不会泄漏给外部调用者，编译能快一点。但如果 SDK 的接口参数类型暴露了依赖，那就要用 api。

iOS (CocoaPods)

# Podfile
source 'https://cdn.cocoapods.org/'
platform :ios, '11.0'

target 'YourAppTarget' do
    use_frameworks!
    pod 'SDKName', '~> 2.1.0'
end

执行 pod install 后，会自动生成 .xcworkspace。以后记得用这个文件打开项目，而不是 .xcodeproj。你想想看，是不是很多时候 crash 就是因为打开错了文件？

3.3 版本冲突怎么办

这是个大话题，我碰到过多次。简单说，冲突类型就两种：

冲突类型	现象	解决
SDK A 和 SDK B 依赖了不同版本的 support 库	编译报错：Duplicate class	统一版本：使用 `force` 或 `exclude`
同一个 SDK 被引用了多次	Gradle 警告：module was resolved to different versions	在 `configurations.all` 里用 `resolutionStrategy` 强制指定

实战代码：Gradle 中强制统一版本

configurations.all {
    resolutionStrategy {
        // 强制指定 support 库版本
        force 'com.android.support:appcompat-v7:28.0.0'
    }
}

四、避坑指南——我踩过的那些坑

漏加权限：Android 的 AndroidManifest.xml 或者 iOS 的 Info.plist 里，如果 SDK 需要相机、网络权限，忘了加就直接调用会闪退。
混淆规则：Release 包如果开了混淆，SDK 的类被混淆了，运行时就找不到方法了。我曾经有次排查了一下午，发现就是忘了加 -keep 规则。
64 位架构：现在 Google Play 要求 64 位包。如果你的 SDK 只提供了 32 位的 so 库，那上传商店会报错。记得检查 arm64-v8a 和 x86_64 的 so 文件。

五、小结一下

环境准备看起来琐碎，但它是整个 SDK 接入的根基。依赖管理，能走自动就走自动，别省那点事。记着，编译通过只是第一步，跑起来、功能正常才是我们的目标。