环境搭建

一、概述

本文主要介绍在集成绿米 SDK 前，需要在您的项目中添加的一些配置，以及获取 SDK 初始化必要的参数。可参考示例工程 aqara_sdk_sample 对照集成。

二、前提条件

1. 确保您已经完成准备工作
2. 确保您已经安装了 Android Studio 并配置了 JDK、Android SDK 等开发环境，详情介绍请前往Android 开发者官网

三、添加依赖

3.1 编译环境需求

3.2 打开 Android Studio

3.3 编辑根目录下的settings.gradle

pluginManagement {
    repositories {
        gradlePluginPortal()
        google()
        mavenCentral()
        maven { url 'https://jitpack.io' }
        // Aqara Maven 仓库
        maven {
            url 'https://public-maven.aqara.com/repository/lumi-release/'
            credentials {
                username = 'maven_username'
                password = 'maven_password'
            }
        }
    }
}

dependencyResolutionManagement {
    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
    repositories {
        google()
        mavenCentral()
        maven { url 'https://jitpack.io' }
        // Aqara Maven 仓库
        maven {
            url 'https://public-maven.aqara.com/repository/lumi-release/'
            credentials {
                username = 'maven_username'
                password = 'maven_password'
            }
        }
    }
}

maven_username及maven_password从示例工程或者联系商务获取

3.4 编辑根目录下的build.gradle

buildscript {
    dependencies {
        // Aqara SDK 统一初始化插件（Gradle 8.x+ 请使用 3.0.0）
        classpath 'com.lumi.plugin:module-init:3.0.0'
    }
}

plugins {
    id 'com.android.application' version '9.1.0' apply false
}

3.5 编辑app目录下的build.gradle

plugins {
    id 'com.android.application'
}

// Aqara 统一初始化插件
apply plugin: 'lumi-module-init'

android {
    namespace 'com.your.package.name'
    compileSdk 36

    defaultConfig {
        applicationId "com.your.package.name"
        minSdk 26
        targetSdk 36
    }

    compileOptions {
        sourceCompatibility JavaVersion.VERSION_17
        targetCompatibility JavaVersion.VERSION_17
    }

    // 解决 so / 资源冲突（集成多业务 SDK 时建议配置）
    packagingOptions {
        jniLibs {
            pickFirsts += ['lib/arm64-v8a/libc++_shared.so', 'lib/armeabi-v7a/libc++_shared.so']
        }
        resources {
            excludes += ['META-INF/DEPENDENCIES', 'META-INF/com.github.CymChad.brvah.kotlin_module',
                         'META-INF/gradle/incremental.annotation.processors']
        }
    }
}

// 若同时集成扫码与红外等模块，可能出现 zxing 冲突，可按需排除
configurations.configureEach {
    exclude group: 'com.google.zxing', module: 'core'
}

dependencies {
    // Core SDK（必需），请使用最新版本，参见[SDK最新版本](./SDK最新版本.md)
    implementation 'com.lumi.external:core:2.2.62'
    implementation 'com.lumi.commonui:ui:1.5.33'
}

3.6 AndroidX 支持

在gradle.properties中添加对 AndroidX 的支持：

android.useAndroidX=true
android.enableJetifier=true

3.7 权限声明

Core SDK 及多数业务能力依赖网络权限。请在宿主 App 的 AndroidManifest.xml 中声明（部分权限也可能由 SDK AAR 自动合并）：

<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
<uses-permission android:name="android.permission.ACCESS_WIFI_STATE" />

蓝牙、定位、麦克风、存储等权限由具体业务 SDK（配网 / 摄像机 / 门锁等）按需使用，请参见对应业务文档补充声明，并在运行时申请危险权限。

四、初始化

4.1 获取SDK初始化必要的参数

4.1.1 AppId、AppKey获取

参见文档准备工作

4.1.2 其他必要参数获取

根据不同的账户授权方式，获取方式也不一致，详情请参考授权管理

通常来讲，大部份时候都是使用虚拟账户授权模式，即第三方 App 需要请求自身云平台获取相关的参数：

4.2 SDK初始化

集成绿米 Android 端各个业务 SDK，通常情况下仅需通过LumiCoreManager进行统一初始化即可，其他业务 SDK 通常情况下不需要单独进行初始化。

4.2.1 进行统一初始化

初始化接口调用

val extension = HashMap<String, Any>()
extension[LumiReactNativeManager.LumiReactNativeConfig.KEY_BUNDLE_LOAD_TYPE] = RNBundleLoadType.PREFAB_ASSETS
extension[LumiReactNativeManager.LumiReactNativeConfig.KEY_BUNDLE_CONFIG_LOAD_TYPE] = RNBundleConfigLoadType.PREFAB_ASSETS

LumiCoreManager.getInstance().init(
    application,
    true, // true 打开调试日志，false 关闭
    LumiCoreManager.LumiCoreSDKConfig.builder()
        .baseUrl("host")
        .baseH5Url("h5Url")
        .baseImageUrl("imageUrl")
        .appId("appId")
        .appKey("appKey")
        .clientId("clientId")
        .sdkChannel("sdkChannel")
        .userInfo(object : ILumiUserInfo {
            override fun getUserId(): String? = "userId"
            override fun getUserToken(): String? = "userToken"
            override fun getArea(): String = "area"
            override fun getLanguage(): String = "language"
            override fun getSupportDeviceArea(): String = "supportDeviceArea"
            override fun getCountry(): String = "country"
            override fun getCoapServer(): String = "coapServer"
        })
        .positionInfo(object : ILumiPositionInfo {
            override fun getHomeId(): String? = "positionId"
        })
        .extensions(extension)
        .build()
)

参数说明

注意：area 和 supportDeviceArea 部分地区代号存在差异；coapServer 必须与当前云端域名所在区域匹配。

language取值

language 参数会影响 SDK 及云端返回的多语言类型。

注意：该值仅影响动态化获取信息的多语言，例如云端接口、配置文件等，SDK 本身使用到的多语言（存放在 strings.xml 中）则跟随宿主 App 的多语言。

area取值

area 参数会影响云端接口的业务逻辑，在某些地区下可能存在部分业务不可用。

supportDeviceArea取值

supportDeviceArea 参数会影响设备入网配置。部分设备仅能在特定地区进行激活使用,请按实际情况进行填写

country取值

country 参数用于标识用户 / 设备实际所在国家或地区，影响设备 SN 管理与入网校验，请按真实地区填写。

取值请参见地区对照表。

选定 country 后，请同步配套设置对应的 area、supportDeviceArea、coapServer，三者需匹配同一服务地区。

4.2.2 更新用户信息

如果需要切换用户，或者 Token 失效了，需要重新请求接口获取,详情请查看Aqara开发者平台，并且更新 SDK 的用户信息。

更新用户信息接口调用

LumiCoreManager.getInstance()
    .updateUserConfig(object : ILumiUserInfo {
        override fun getUserId(): String? = "userId"
        override fun getUserToken(): String? = "userToken"
        override fun getArea(): String = "area"
        override fun getLanguage(): String = "lang"
        override fun getSupportDeviceArea(): String = "supportDeviceArea"
        override fun getCountry(): String = "country"
        override fun getCoapServer(): String = "coapServer"
    })

4.3 RxJava 统一错误处理

SDK中使用了大量 RxJava，建议在 Application 中统一处理未捕获异常，避免个别异常导致应用崩溃：

override fun onCreate() {
    super.onCreate()
    RxJavaPlugins.setErrorHandler {
        it.printStackTrace()
    }
}

五、推送

SDK 本身不具备获取云端推送的能力，需要依赖宿主 App 的推送。详情请查看消息推送

5.1 订阅推送

LumiCoreManager.getInstance().rePushClientId("clientId")

参数说明

5.2 转发推送

第三方 App 收到关于 Aqara 设备的推送时，可以将其转发给 SDK：

LumiCorePushManager.getInstance().onMessage("content")

注意不要将一整个消息体透传给 SDK，SDK 仅需要 LUMI@ 开头的字符串。

参数说明

5.3 推送消息格式

将content传递给 SDK 即可：

{
  "sequenceNo": "202106031107",
  "osType": "android",
  "content": "LUMI@eyJ0eXBlIjoicmVzX3N1YnNjcmliZSIsInJlc3VsdCI6eyJ0aW1lU3RhbXAiOjE2MjMwNjUwNjA5NzYsImF0dHJDaGFubmVsIjoxLCJzb3VyY2UiOiI0LCwxNjIzMDY1MDYwNzgxLDlmMzgyMTIwNjczMTI0ZDI5N2VmNjI0MV9lOTE3ZjE0MDBhNTIyNDk1LjU0NTU4MTgyNTk4MDg5MTEzNywsIiwiYXR0ciI6IjE0LjcuODUiLCJ2YWx1ZSI6IjEyOTE4MTExNTIiLCJzdWJqZWN0SWQiOiJsdW1pMS41NGVmNDRjOTExNjUiLCJpZGVudGlmeUlkIjoiSE9TVDA0YTZkYzAzNzMyNTM3NTBiMzIyMzMxOGVhMGQ1ZmVhMjk0YSIsInB1c2hUeXBlIjoicmVzX3N1YnNjcmliZSJ9LCJjb2RlIjowfQ==",
  "token": "04a6dc0373253750b3223318ea0d5fea294a"
}