Aqara SDK Android and iOS Integration: Picking the Right One

Answer up front — The Aqara SDK set splits into a device pairing SDK, which puts devices onto a hub and activates them in the cloud, and a device control SDK, which draws Aqara-styled UI components and lets your app control those devices. You normally need both, because the first is onboarding and the second is the product. Camera and door lock are separate vertical SDKs because they are genuinely different jobs — camera brings P2P playback and two-way audio, lock brings its own pairing and control surface. The hard requirements are the build toolchain and the mobile permissions, not the code: the documented Android requirements include minSdk 26, target and compile SDK 36, Java 17, Kotlin 2.1.0, KSP 2.1.0 and Gradle 9.3.1+ (minimum 8.9+), and the iOS side requires iOS 15.1, iPadOS 15.1 and Swift 5.0+.

Our AqaraLink developer platform overview listed the SDK families. This post is about choosing between them, and the build and permission work people discover three days into a sprint.

The SDK family map

From the English Android and iOS development guides:

Those sizes are the documented maximum incremental figures, assuming no overlap between your app's dependencies and the SDK's. In practice they are usually smaller — the docs say so explicitly. Budget for the worst case anyway, because that is what hits a user on a low-end Android phone. The camera SDK is the heavy one at about 70MB: playback (about 24MB, P2P), control and settings (about 22MB), and other third-party components (about 24MB). If your app does not stream video, do not ship it.

Onboarding and control are different jobs

This is the split people get wrong, and it is structural rather than cosmetic.

The pairing SDK is for putting hardware on a network and into the cloud — the docs describe it as configuring Aqara devices onto a router and completing cloud activation, through Aqara-style UI pages. Supported onboarding types are MagicPair, Wi-Fi AP, Ethernet wired and Bluetooth.

The without-UI variant is much narrower than its name suggests: it only adds the gateway device, and sub-devices are then added through the write.device.openConnect interface. If your product promises white-label onboarding you design every screen yourself, and you still do not onboard sub-devices through the SDK.

The control SDK is the product. It mainly provides Aqara-style UI components and supports direct calls from third-party apps — that is what makes your app look like an Aqara app without your team designing Aqara's control surfaces. You need both in the ordinary case: pairing without control ships an onboarding wizard to nowhere, and control without pairing forces users into Aqara Home first.

Four onboarding types are explicitly not supported by the pairing SDK, and each routes elsewhere: Zigbee child devices (implement via APIs in the third-party app), Matter pairing (Matter SDK), Camera pairing (Camera SDK) and Door lock pairing (Door Lock SDK). Zigbee deserves its own note, being how most Aqara sensors get added: onboarding is hub-driven, so the app only calls the cloud HTTP API to put the hub into pairing mode and the hub discovers and binds the surrounding devices. Your app is a trigger, not the mechanism.

Camera and lock are separate because they are separate

Camera supports pairing, real-time preview, playback and two-way audio, plus control and settings. Playback is P2P — peer-to-peer, device to phone, not relayed through a cloud stream. That is a different engineering shape from controlling a light: you hold a media connection open, manage reconnection, and deal with a codec and a renderer.

Door lock supports lock pairing and lock control — a smaller surface, shipped as a distinct SDK with its own pairing path, error codes and FAQ. It carries a different risk profile: an unlock path in a shipping app is a security surface, not a UI convenience, and deserves its own review. Neither camera nor lock is a module you bolt on; both are separate integration projects.

OTA changes what you are shipping

The app-side implication of firmware management is easy to miss: the moment you integrate OTA, you are not shipping an app, you are operating a device fleet. That means a compatibility view of your own fleet, a staged rollout policy (not every device in a 2,000-unit estate should update on the same afternoon), a rollback conversation with Aqara before launch, and end-user consent UX, because a firmware update is an action your customer can see. Treat it as operational tooling with a support process behind it, not a feature.

The build environment is the hard part

This is where integrations stall. From the Android environment build page:

The Matter vertical category SDK states its own set: minSdk 26, target 36, compile 36, plus Gradle 8.9, JDK 17, Kotlin 2.1.0 and SDK Build Tools 34.0.0 as required, with Android Studio 2024.3.1, AGP 8.7 and NDK 27.0.12077973 optional. The documentation is blunt: if these conditions are not met, the demo or SDK may not function properly. If your app is on AGP 8.5 or Gradle 8.7, adding the Matter SDK is a build-system migration — schedule it as one.

The iOS side is lighter but still specific: iOS 15.1, iPadOS 15.1, Swift 5.0+. The iOS public SDK ships as a static library integrated into the host app; the Android public SDK is remote Maven integration only. Neither provides source downloads except for customised SDKs, so owning the source is a conversation with Aqara, not a build flag. One practical note: if you also integrate the scan and IR modules, zxing conflicts may occur and you may need to exclude com.google.zxing:core.

Permissions and consent: the other half of the work

The iOS environment build page lists the privacy usage descriptions the SDK needs declared in Info.plist, and they are a real user-facing surface: Bluetooth, Camera, Microphone, Photo Library, Location When In Use, Location Always and When In Use, Local Network and HomeKit. The Access Network SDK additionally needs Hotspot, Access WiFi Information and Wireless Accessory Configuration capabilities, plus a Matter Extension Target in Xcode if the device is under the Matter protocol. The host app needs entitlements for HomeKit AllowSetUpPayload, Matter Allow Setup Payload, Manage Thread Network Credentials and App Groups; the Matter Extension needs App Groups as well.

The design consequence is a consent flow people underestimate. These permissions are not all requested at once in a happy path — Bluetooth, camera and local network are requested when the user does the thing that needs them. A dialog with no explanation, before the user has any context, is a conversion killer and, on iOS, a review risk. Build the explanation into the moment: the technical fact is easy, since local network access is required for the on-LAN discovery onboarding depends on.

The Matter onboarding constraint you must design around

From the Matter SDK integration page, because it changes the flow: Matter sub-devices cannot be directly configured and connected through the SDK. They must be connected via an Aqara Matter hub, using Aqara's private Magic Pair protocol, before device configuration and control can be performed. That is a two-stage onboarding journey your UX has to show honestly — get the Matter hub onto the network first, then add sub-devices to it. A flat "add device" list dead-ends on the Matter path, and the user will blame your app.

Integration checklist

• [ ] Project approved; appId and appKey obtained, used to call config.app.init for SDK init parameters
• [ ] Build environment matched — Java 17, Kotlin 2.1.0, Gradle 9.3.1+ (min 8.9+), compile/target SDK 36
• [ ] Incremental app size budgeted, worst case, against your store size limit
• [ ] Pairing SDK and control SDK both integrated, or the decision documented
• [ ] Camera and lock treated as separate integration projects
• [ ] OTA staged-rollout and support process agreed before launch
• [ ] iOS usage descriptions and entitlements declared, including the Matter extension if used
• [ ] Permission prompts written with context, at the moment of need
• [ ] Matter onboarding UX reflects the hub-first, Magic-Pair-second sequence
• [ ] Zigbee path built around hub-driven pairing mode