快速集成安卓 App SDK

本文介绍如何将安卓版涂鸦 cube App SDK 集成到您的开发环境中，例如 Android Studio，并介绍初始化方法以及如何启用调试模式。然后，您可以尝试运行 Demo，快速上手全屋智能移动应用开发。

前提条件

• 开始操作前，请确保您已经完成 准备工作。

• 如果您还未安装 Android Studio，请访问 安卓官网 进行下载安装。

SDK 版本

• 如果您之前采用的是从 1.0.0 版本 cube App SDK，请参考 迁移指南 升级到最新版本 SDK。

• 在涂鸦 IoT 开发平台配置的安卓包名需要与您的工程 packageName 保持一致。否则，系统会报错 ILLEGAL_CLIENT_ID。

• 您需要为 SDK 应用设置 SHA256 密钥。详情请参考 如何获取 SHA 密钥。

  如果您需要上传应用至 Google Play 应用商店，请注意查看是否已开启重签名功能。若已开启，需要将谷歌生成的 SHA256 密钥配置到涂鸦 IoT 开发平台，否则会提示 非法客户端 问题。详情请参考 开启 Android 签名保护。

• 您需要将本地自行放入的 SDK 的相关 so 库移除，使用 SDK 中提供的。如果集成新版本 so 库，请移除之前老版本手动集成的库，防止冲突或者代码版本不一致导致的问题。

集成 SDK

第一步：创建 Android 工程

在 Android Studio 中新建工程。

第二步：配置 build.gradle 文件

在安卓项目的 build.gradle 文件里，添加集成准备中下载的 dependencies 依赖库。

sdk_version 说明

• sdk_version 为 2.0.0-cube.4 时，确保云端部署 Cube 版本为 2.0 及以上版本。
• sdk_version 为 2.1.0-cube 时，确保云端部署 Cube 版本为 2.1 及以上版本。

android {
   defaultConfig {
      ndk {
         abiFilters "armeabi-v7a", "arm64-v8a"
      }
   }
   packagingOptions {
      pickFirst 'lib/*/libc++_shared.so' // 多个 AAR（Android Library）文件中存在此 .so 文件，请选择第一个
   }
}
dependencies {
   implementation 'androidx.core:core-ktx:1.3.2'
    implementation 'androidx.appcompat:appcompat:1.2.0'
    implementation 'com.google.android.material:material:1.3.0-alpha04'
    testImplementation 'junit:junit:4.+'
    androidTestImplementation 'androidx.test.ext:junit:1.1.2'
    androidTestImplementation 'androidx.test.espresso:espresso-core:3.3.0'

    api 'com.thingclips.smart:thingsmart:${sdk_version}'
}

在根目录的 build.gradle 文件中，增加涂鸦 Maven 仓库地址，进行仓库配置。请联系项目经理获取仓库账号密码。

buildscript {
    repositories {
        google()
        mavenCentral()
        maven {
            url 'https://maven-other.tuya.com/repository/maven-private/'
            credentials {
                username "xxxxxx"
                password "xxxxxx"
            }
        }
        maven { url "https://maven-other.tuya.com/repository/maven-releases/" }
        maven { url "https://maven-other.tuya.com/repository/maven-commercial-releases/" }
        maven { url 'https://maven.aliyun.com/repository/public' }
        maven { url 'https://central.maven.org/maven2/' }
        maven { url 'https://oss.sonatype.org/content/repositories/snapshots/' }
        maven { url 'https://developer.huawei.com/repo/' }
        maven { url 'https://jitpack.io' }
        jcenter() //Warning:this repository is going to shut down soon
    }
    dependencies {
        classpath "com.android.tools.build:gradle:4.1.1"

        // NOTE: Do not place your application dependencies here; they belong
        // in the individual module build.gradle files
    }
}

allprojects {
    repositories {
        maven {
            url 'https://maven-other.tuya.com/repository/maven-private/'
            credentials {
                username "xxxxxx"
                password "xxxxxx"
            }
        }
        maven { url "https://maven-other.tuya.com/repository/maven-releases/" }
        maven { url "https://maven-other.tuya.com/repository/maven-commercial-releases/" }
        maven { url 'https://maven.aliyun.com/repository/public' }
        maven { url 'https://central.maven.org/maven2/' }
        maven { url 'https://oss.sonatype.org/content/repositories/snapshots/' }
        maven { url 'https://developer.huawei.com/repo/' }
        maven { url 'https://jitpack.io' }
        google()
        mavenCentral()
        jcenter() //Warning:this repository is going to shut down soon
    }
}

第三步：集成安全组件

1. 在 获取 SDK 页面，勾选一款或多款您需要的 SDK 或者业务包，然后下载对应应用平台的集成资料包。

   

2. 将下载后的资料包解压，并将 security-algorithm.aar 放置到工程 libs 目录下，并确认工程 build.gradle 的 dependencies 中有以下依赖：implementation fileTree(include: ['*.aar'], dir: 'libs')。

   

第四步：设置 Appkey、AppSecret 和证书签名

1. 在 涂鸦 IoT 开发平台，找到您创建的 SDK。

   

2. 在上图中，获取 AppKey 和 AppSecret，并配置在 AndroidManifest.xml中。

   <meta-data
   android:name="THING_SMART_APPKEY"
   android:value="应用 Appkey" />
   <meta-data
   android:name="THING_SMART_SECRET"
   android:value="应用密钥 AppSecret" />
   

3. 配置应用证书：

   1. 生成一个 SHA256 密钥。应用证书请参考 Android 官方文档，以及 如何获取证书 SHA256。
   2. 将您的 SHA256 密钥填入的 证书 中。

第五步：配置 t_cdc.tcfg

具体内容请联系项目经理。

第六步：混淆配置

在 proguard-rules.pro 文件配置相应混淆配置。

#fastJson
-keep class com.alibaba.fastjson.**{*;}
-dontwarn com.alibaba.fastjson.**

#mqtt
-keep class com.thingclips.smart.mqttclient.mqttv3.** { *; }
-dontwarn com.thingclips.smart.mqttclient.mqttv3.**

#OkHttp3
-keep class okhttp3.** { *; }
-keep interface okhttp3.** { *; }
-dontwarn okhttp3.**

-keep class okio.** { *; }
-dontwarn okio.**

-keep class com.thingclips.**{*;}
-dontwarn com.thingclips.**

# Matter SDK
-keep class chip.** { *; }
-dontwarn chip.**

第七步：初始化 SDK

您需要在 Application 的主线程中初始化 SDK，确保所有进程都能初始化。示例代码如下：

public class ThingSmartApp extends Application {
   @Override
   public void onCreate() {
      super.onCreate();
      ThingHomeSdk.init(this);
   }
}

ThingHomeSdk.init(Application application, String appkey, String appSerect)

第八步：注销云连接

在退出应用的时候，调用以下接口可以注销云连接。

ThingHomeSdk.onDestroy();

第九步：开启或关闭日志

• 在 debug 模式下，您可以开启 SDK 的日志开关，查看更多的日志信息，帮助您快速定位问题。

• 在 release 模式下，建议关闭日志开关。

  ThingHomeSdk.setDebugMode(true);
  

运行 Demo 应用

Demo 应用演示 App SDK 的开发流程，展现如何调用 SDK 能力、实现智能家居场景。在开发应用之前，建议您根据需要，先按照以下流程完成 Demo 应用的操作。

Demo 应用介绍

Demo 应用主要包括：

• 用户管理：使用手机号或者邮箱进行登录和注册。

• 家庭管理和设备管理：

  • 创建家庭，切换用户所属的当前家庭。
  • 展现家庭中设备列表，控制设备功能。
  • 设备重命名和设备移除。

• 设备配网：包括 Wi-Fi 快连配网模式、热点配网模式、有线网关配网、网关子设备配网、蓝牙配网和 Mesh 子设备配网。

  

更多详情，请访问 tuya-home-android-sdk-sample-java GitHub 项目。

运行 Demo

1. 替换 app 目录下 build.gradle 文件中的 applicationId 为您的应用包名。

   

2. 确认您已经完成 第三步：集成安全组件 以及 第四步：设置 Appkey，AppSecret 和证书签名。

3. 然后单击运行，运行 Demo。

常见问题

SING_VALIDATE_FALED

API 请求提示签名错误（SING_VALIDATE_FALED）

• 问题现象：运行 Demo 时提示以下错误：

  {
     "success": false,
     "errorCode" : "SING_VALIDATE_FALED",
     "status" : "error",
     "errorMsg" : "Permission Verification Failed",
     "t" : 1583208740059
  }
  

• 解决方法：

  请检查您的 AppKey 和 AppSecret 是否正确配置，是否和 准备工作 中获取到的一致。

ILLEGAL_CLIENT_ID

• 为什么报错 ILLEGAL_CLIENT_ID？

  • 因为 cube App SDK 做了安全校验的升级。
  • 您需要在涂鸦 IoT 开发平台根据说明文档来 获取 SHA256，然后在平台绑定您的 SHA256。详细配置步骤，请参考 准备工作。

• 为什么报错 ILLEGAL_CLIENT_ID？

  • 因为 cube App SDK 做了安全校验的升级。
  • 您在涂鸦 IoT 开发平台配置的安卓包名需要与您的工程 packageName 保持一致。否则，系统会报错 ILLEGAL_CLIENT_ID。

• 为什么在涂鸦 IoT 开发平台配置了 SHA256，直接运行 Demo，还是报错 ILLEGAL_CLIENT_ID？

  解决方法：直接运行 Demo 前，需要在 app 模块的 build.gradle 中配置您自己的签名信息。

  android {
      ...
      signingConfigs {
          debug {
              storeFile file('xxxx.jks')
              storePassword 'xxxxxx'
              keyAlias 'xxx'
              keyPassword 'xxxxxx'
          }
          release {
              storeFile file('xxxx.jks')
              storePassword 'xxxxxx'
              keyAlias 'xxx'
              keyPassword 'xxxxxx'
          }
      }
  }