Integrasi SDK Aqara untuk Android dan iOS: Memilih yang Betul

Jawapan ringkas — Set SDK Aqara terbahagi kepada SDK pemasangan pasangan peranti, yang meletakkan peranti pada hab dan mengaktifkannya dalam awan, dan SDK kawalan peranti, yang melukis komponen UI bergaya Aqara dan membolehkan aplikasi anda mengawal peranti itu. Anda biasanya memerlukan kedua-duanya, kerana yang pertama ialah onboarding dan yang kedua ialah produknya. Kamera dan kunci pintu ialah SDK menegak yang berasingan kerana ia memang kerja yang berbeza: kamera membawa main semula P2P dan audio dua hala, kunci membawa permukaan pemasangan pasangan dan kawalannya sendiri. Keperluan keras ialah rantaian alat binaan dan kebenaran mudah alih, bukan kod: keperluan Android yang didokumenkan termasuk minSdk 26, SDK sasaran dan kompil 36, Java 17, Kotlin 2.1.0, KSP 2.1.0 dan Gradle 9.3.1+ (minimum 8.9+), dan sebelah iOS memerlukan iOS 15.1, iPadOS 15.1 dan Swift 5.0+.

Gambaran keseluruhan platform pembangun AqaraLink kami menyenaraikan keluarga SDK. Catatan ini tentang memilih antaranya, dan kerja binaan serta kebenaran yang orang temui pada hari ketiga sesuatu sprint.

Peta keluarga SDK

Daripada panduan pembangunan Android dan iOS bahasa Inggeris:

Saiz itu ialah angka tokokan maksimum yang didokumenkan, dengan andaian tiada pertindihan antara kebergantungan aplikasi anda dengan SDK. Dalam praktik ia biasanya lebih kecil: dokumen menyatakan demikian secara jelas. Tetap peruntukkan bajet untuk kes terburuk, kerana itulah yang menimpa pengguna telefon Android hujung rendah. SDK kamera yang paling berat pada kira-kira 70MB: main semula (kira-kira 24MB, P2P), kawalan dan tetapan (kira-kira 22MB), dan komponen pihak ketiga lain (kira-kira 24MB). Jika aplikasi anda tidak menstrim video, jangan sertakannya.

Onboarding dan kawalan ialah kerja yang berbeza

Ini pembahagian yang sering disalahfahami orang, dan ia bersifat struktur, bukan kosmetik.

SDK pemasangan pasangan adalah untuk meletakkan perkakasan pada rangkaian dan ke dalam awan: dokumen menerangkannya sebagai mengkonfigurasi peranti Aqara ke penghala dan melengkapkan pengaktifan awan, melalui halaman bergaya Aqara. Jenis onboarding yang disokong ialah MagicPair, Wi-Fi AP, Ethernet berwayar dan Bluetooth.

Varian tanpa UI jauh lebih sempit daripada yang dinamakan: ia hanya menambah peranti gateway, dan sub-peranti kemudian ditambah melalui antara muka write.device.openConnect. Jika produk anda menjanjikan onboarding label putih (white-label), anda mereka bentuk setiap skrin sendiri, dan anda masih tidak meng-onboard sub-peranti melalui SDK.

SDK kawalan ialah produknya. Ia terutamanya menyediakan komponen UI bergaya Aqara dan menyokong panggilan terus daripada aplikasi pihak ketiga: itulah yang menjadikan aplikasi anda kelihatan seperti aplikasi Aqara tanpa pasukan anda mereka bentuk permukaan kawalan Aqara. Anda memerlukan kedua-duanya dalam kes biasa: pemasangan pasangan tanpa kawalan menghantar wizard onboarding ke mana-mana, dan kawalan tanpa pemasangan pasangan memaksa pengguna ke Aqara Home dahulu.

Empat jenis onboarding secara jelas tidak disokong oleh SDK pemasangan pasangan, dan setiap satu dialihkan ke tempat lain: peranti anak Zigbee (laksanakan melalui API dalam aplikasi pihak ketiga), pemasangan pasangan Matter (SDK Matter), pemasangan pasangan kamera (SDK Kamera) dan pemasangan pasangan kunci pintu (SDK Kunci Pintu). Zigbee wajar diberi catatan tersendiri, kerana begitulah kebanyakan penderia Aqara ditambah: onboarding dipacu oleh hab, jadi aplikasi hanya memanggil API HTTP awan untuk meletakkan hab dalam mod pemasangan pasangan dan hab menemui serta mengikat peranti di sekelilingnya. Aplikasi anda ialah pencetus, bukan mekanisme.

Kamera dan kunci berasingan kerana ia memang berasingan

Kamera menyokong pemasangan pasangan, pratonton masa nyata, main semula dan audio dua hala, serta kawalan dan tetapan. Main semula ialah P2P: rakan ke rakan, peranti ke telefon, tidak disampaikan melalui strim awan. Itu bentuk kejuruteraan yang berbeza daripada mengawal lampu: anda memegang sambungan media terbuka, menguruskan sambungan semula, dan berurusan dengan codec serta perender.

Kunci pintu menyokong pemasangan pasangan kunci dan kawalan kunci: permukaan yang lebih kecil, dihantar sebagai SDK berbeza dengan laluan pemasangan pasangan, kod ralat dan soalan lazimnya sendiri. Ia membawa profil risiko yang berbeza: laluan buka kunci dalam aplikasi yang dihantar ialah permukaan keselamatan, bukan kemudahan UI, dan wajar disemak secara berasingan. Kamera mahupun kunci bukan modul yang dipasang sambil lalu; kedua-duanya projek integrasi yang berasingan.

OTA mengubah apa yang anda hantar

Implikasi pengurusan perisian tegar di sebelah aplikasi mudah terlepas pandang: sebaik sahaja anda mengintegrasikan OTA, anda bukan menghantar aplikasi, anda mengendalikan armada peranti. Itu bermakna pandangan keserasian bagi armada anda sendiri, dasar pelancaran berperingkat (bukan semua peranti dalam premis 2,000 unit patut dikemas kini pada petang yang sama), perbualan tentang pemulihan (rollback) dengan Aqara sebelum pelancaran, dan UX persetujuan pengguna akhir, kerana kemas kini perisian tegar ialah tindakan yang boleh dilihat pelanggan anda. Anggap ia sebagai perkakas operasi dengan proses sokongan di belakangnya, bukan sebagai ciri.

Persekitaran binaan ialah bahagian yang sukar

Di sinilah integrasi tersekat. Daripada halaman pembinaan persekitaran Android:

SDK kategori menegak Matter menyatakan set keperluannya sendiri: minSdk 26, sasaran 36, kompil 36, ditambah Gradle 8.9, JDK 17, Kotlin 2.1.0 dan SDK Build Tools 34.0.0 sebagai wajib, dengan Android Studio 2024.3.1, AGP 8.7 dan NDK 27.0.12077973 sebagai pilihan. Dokumentasi berterus terang: jika syarat ini tidak dipenuhi, demo atau SDK mungkin tidak berfungsi dengan betul. Jika aplikasi anda menggunakan AGP 8.5 atau Gradle 8.7, menambah SDK Matter ialah migrasi sistem binaan: jadualkan ia sedemikian.

Sebelah iOS lebih ringan tetapi tetap khusus: iOS 15.1, iPadOS 15.1, Swift 5.0+. SDK awam iOS dihantar sebagai pustaka statik yang diintegrasikan ke dalam aplikasi hos; SDK awam Android ialah integrasi Maven jauh sahaja. Kedua-duanya tidak menyediakan muat turun kod sumber kecuali untuk SDK tersuai, jadi memiliki kod sumber ialah perbualan dengan Aqara, bukan bendera binaan. Satu nota praktikal: jika anda turut mengintegrasikan modul imbasan dan IR, konflik zxing mungkin berlaku dan anda mungkin perlu mengecualikan com.google.zxing:core.

Kebenaran dan persetujuan: separuh lagi kerja

Halaman pembinaan persekitaran iOS menyenaraikan perihalan penggunaan privasi yang perlu diisytiharkan SDK dalam Info.plist, dan ia ialah permukaan sebenar yang menghadap pengguna: Bluetooth, Camera, Microphone, Photo Library, Location When In Use, Location Always and When In Use, Local Network dan HomeKit. SDK Access Network juga memerlukan keupayaan Hotspot, Access WiFi Information dan Wireless Accessory Configuration, serta Matter Extension Target dalam Xcode jika peranti menggunakan protokol Matter. Aplikasi hos memerlukan hak (entitlement) untuk HomeKit AllowSetUpPayload, Matter Allow Setup Payload, Manage Thread Network Credentials dan App Groups; Matter Extension turut memerlukan App Groups.

Akibat reka bentuknya ialah aliran persetujuan yang diperkecilkan orang. Kebenaran ini tidak semuanya diminta sekali gus dalam laluan yang lancar: Bluetooth, kamera dan rangkaian setempat diminta apabila pengguna melakukan perkara yang memerlukannya. Dialog tanpa penjelasan, sebelum pengguna mempunyai sebarang konteks, ialah pembunuh penukaran dan, pada iOS, risiko semakan. Bina penjelasan itu ke dalam detik berkenaan: fakta teknikalnya mudah, kerana akses rangkaian setempat diperlukan untuk penemuan dalam LAN yang menjadi tunjang onboarding.

Kekangan onboarding Matter yang mesti anda reka bentuk mengelilinginya

Daripada halaman integrasi SDK Matter, kerana ia mengubah aliran: sub-peranti Matter tidak boleh dikonfigurasi dan disambungkan secara terus melalui SDK. Ia mesti disambungkan melalui hab Matter Aqara, menggunakan protokol persendirian Aqara Magic Pair, sebelum konfigurasi dan kawalan peranti dapat dilakukan. Itu perjalanan onboarding dua peringkat yang mesti ditunjukkan UX anda dengan jujur: letakkan hab Matter pada rangkaian dahulu, kemudian tambah sub-peranti kepadanya. Senarai "tambah peranti" yang rata menemui jalan buntu pada laluan Matter, dan pengguna akan menyalahkan aplikasi anda.

Senarai semak integrasi

• [ ] Projek diluluskan; appId dan appKey diperoleh, digunakan untuk memanggil config.app.init bagi parameter permulaan SDK
• [ ] Persekitaran binaan dipadankan: Java 17, Kotlin 2.1.0, Gradle 9.3.1+ (min 8.9+), SDK kompil/sasaran 36
• [ ] Saiz aplikasi tokokan diperuntukkan bajet, kes terburuk, berbanding had saiz kedai aplikasi anda
• [ ] SDK pemasangan pasangan dan SDK kawalan kedua-duanya diintegrasikan, atau keputusan didokumenkan
• [ ] Kamera dan kunci dianggap projek integrasi berasingan
• [ ] Pelancaran berperingkat OTA dan proses sokongan dipersetujui sebelum pelancaran
• [ ] Perihalan penggunaan dan hak iOS diisytiharkan, termasuk extension Matter jika digunakan
• [ ] Gesaan kebenaran ditulis dengan konteks, pada detik keperluan
• [ ] UX onboarding Matter mencerminkan urutan hab dahulu, Magic Pair kedua
• [ ] Laluan Zigbee dibina sekitar mod pemasangan pasangan yang dipacu hab