Aqara SDK 的 Android 与 iOS 集成：选对那一个

简要回答 — Aqara SDK 套件分为设备配网 SDK和设备控制 SDK：前者把设备接入网关并在云端激活，后者绘制 Aqara 风格的界面组件，让你的 App 控制这些设备。通常两者都需要，因为前者是接入，后者才是产品本身。摄像头和门锁是独立的垂直品类 SDK，因为它们确实是不同的工作：摄像头带来 P2P 回放和双向语音，门锁带来自己的配网和控制界面。硬性要求在于构建工具链和手机权限，而不在代码：文档记载的 Android 要求包括 minSdk 26、target 和 compile SDK 36、Java 17、Kotlin 2.1.0、KSP 2.1.0，以及 Gradle 9.3.1+（最低 8.9+），iOS 端则要求 iOS 15.1、iPadOS 15.1 和 Swift 5.0+。

我们的 AqaraLink 开发者平台概览列出了各个 SDK 系列。本文讲的是如何在它们之间做选择，以及人们在开发冲刺进行到第三天才发现的构建和权限工作。

SDK 系列一览

来自英文的 Android 和 iOS 开发指南：

这些体积是文档记载的最大增量数字，前提是你的 App 依赖与 SDK 的依赖没有重叠。实际上通常更小，文档也明确这样说。但仍要按最坏情况预算，因为那才是会影响低端 Android 手机用户的情况。摄像头 SDK 是最重的，约 70MB：回放（约 24MB，P2P）、控制和设置（约 22MB），以及其他第三方组件（约 24MB）。如果你的 App 不做视频流，就不要带上它。

接入和控制是不同的工作

这是人们最常搞错的划分，而且是结构性的，不是表面的。

配网 SDK 用于把硬件接入网络和云端：文档说明它通过 Aqara 风格的界面页面，把 Aqara 设备配置到路由器上并完成云端激活。支持的接入类型有 MagicPair、Wi-Fi AP、Ethernet 有线和 Bluetooth。

不带界面的版本比名字暗示的窄得多：它只添加网关设备，子设备随后通过 write.device.openConnect 接口添加。如果你的产品承诺贴牌（white-label）接入，每一个页面都要自己设计，而且仍然无法通过 SDK 接入子设备。

控制 SDK 才是产品。 它主要提供 Aqara 风格的界面组件，并支持第三方 App 直接调用，这让你的 App 看起来像 Aqara 的 App，而你的团队不必自己设计 Aqara 的控制界面。一般情况下两者都需要：只有配网没有控制，等于交付了一个通向虚无的接入向导；只有控制没有配网，则会迫使用户先去 Aqara Home。

配网 SDK 明确不支持四种接入类型，各自另有途径：Zigbee 子设备（在第三方 App 中通过 API 实现）、Matter 配网（Matter SDK）、摄像头配网（Camera SDK）和门锁配网（Door Lock SDK）。Zigbee 值得单独说明，因为大多数 Aqara 传感器都是这样添加的：接入是由网关驱动的，App 只需调用云端 HTTP API 让网关进入配对模式，由网关发现并绑定周围的设备。你的 App 是触发者，不是实现机制。

摄像头和门锁之所以独立，是因为它们本就不同

摄像头支持配网、实时预览、回放和双向语音，以及控制和设置。回放是 P2P，即点对点，设备到手机，不经云端流媒体中转。这与控制一盏灯的工程形态完全不同：你要保持媒体连接，管理重连，并处理编解码器和渲染器。

门锁支持门锁配网和门锁控制，范围较小，作为独立的 SDK 发布，有自己的配网路径、错误码和常见问题。它的风险性质不同：发布的 App 里的开锁路径是安全面，不是界面上的便利，值得单独审查。摄像头和门锁都不是可以随手加上的模块，两者都是各自独立的集成项目。

OTA 改变了你所交付的东西

固件管理在 App 端的含义很容易被忽略：一旦你集成了 OTA，你交付的就不再是一个 App，而是在运营一支设备队伍。 这意味着要有你自己设备队伍的兼容性视图、分阶段发布策略（在 2,000 个单位的场所里，不应让所有设备在同一个下午更新）、在上线前与 Aqara 讨论回滚方案，以及终端用户的同意体验，因为固件更新是客户看得到的操作。把它当作背后有支持流程的运营工具，而不是一个功能。

构建环境是难点

集成项目往往卡在这里。来自 Android 环境搭建页面：

Matter 垂直品类 SDK 给出了自己的一套要求：minSdk 26、target 36、compile 36，另外必须使用 Gradle 8.9、JDK 17、Kotlin 2.1.0 和 SDK Build Tools 34.0.0，Android Studio 2024.3.1、AGP 8.7 和 NDK 27.0.12077973 为可选。文档说得很直白：如果不满足这些条件，demo 或 SDK 可能无法正常运行。如果你的 App 用的是 AGP 8.5 或 Gradle 8.7，加入 Matter SDK 就是一次构建系统迁移，请按迁移来排期。

iOS 端较轻，但同样有明确要求：iOS 15.1、iPadOS 15.1、Swift 5.0+。iOS 公开 SDK 以静态库形式集成到宿主 App 中；Android 公开 SDK 仅支持远程 Maven 集成。除定制 SDK 外，两者都不提供源代码下载，所以想拥有源代码要与 Aqara 沟通，而不是一个构建开关。一个实用的提醒：如果你还集成了扫码和红外模块，可能出现 zxing 冲突，你可能需要排除 com.google.zxing:core。

权限和同意：另一半工作

iOS 环境搭建页面列出了 SDK 需要在 Info.plist 中声明的隐私使用说明，它们是真实面向用户的界面：Bluetooth、Camera、Microphone、Photo Library、Location When In Use、Location Always and When In Use、Local Network 和 HomeKit。Access Network SDK 还需要 Hotspot、Access WiFi Information 和 Wireless Accessory Configuration 能力，如果设备使用 Matter 协议，还要在 Xcode 中加入 Matter Extension Target。宿主 App 需要 HomeKit AllowSetUpPayload、Matter Allow Setup Payload、Manage Thread Network Credentials 和 App Groups 的权限（entitlement）；Matter Extension 同样需要 App Groups。

由此带来的设计后果，是一套被人低估的同意流程。这些权限并不是在顺利路径中一次性全部请求的：蓝牙、摄像头和本地网络，是在用户做需要它们的事情时才请求的。用户还没有任何上下文时就弹出没有解释的对话框，会扼杀转化率，在 iOS 上还有审核风险。把解释放进那一刻：技术上的理由很简单，接入过程所依赖的局域网内发现功能需要本地网络访问权限。

你必须围绕它设计的 Matter 接入限制

来自 Matter SDK 集成页面，因为它会改变流程：Matter 子设备无法通过 SDK 直接配置和连接。 必须先通过 Aqara Matter 网关，使用 Aqara 的私有协议 Magic Pair 连接，然后才能进行设备配置和控制。这是一个两阶段的接入旅程，你的用户体验必须如实呈现：先让 Matter 网关联网，再向其添加子设备。一个扁平的“添加设备”列表，在 Matter 路径上会走进死胡同，而用户会怪你的 App。

集成检查清单

• [ ] 项目已审核通过；已获得 appId 和 appKey，用于调用 config.app.init 获取 SDK 初始化参数
• [ ] 构建环境已匹配：Java 17、Kotlin 2.1.0、Gradle 9.3.1+（最低 8.9+）、compile/target SDK 36
• [ ] 已按最坏情况，对照应用商店的体积限制预算增量体积
• [ ] 配网 SDK 和控制 SDK 都已集成，或已记录取舍决定
• [ ] 摄像头和门锁被当作独立的集成项目
• [ ] 上线前已就 OTA 分阶段发布和支持流程达成一致
• [ ] 已声明 iOS 使用说明和权限（entitlement），如使用 Matter 则包括 Matter extension
• [ ] 权限提示带有上下文，并在需要的那一刻出现
• [ ] Matter 接入的用户体验反映“先网关、后 Magic Pair”的顺序
• [ ] Zigbee 路径围绕由网关驱动的配对模式构建