快速集成

本文介绍如何使用 CocoaPods 将涂鸦cube App SDK 快速集成到您的项目中。SDK 要求 iOS 版本不低于 9.0。

SDK 版本

• 如果您采用的 2.x.x 以下版本 SDK，请提前根据 迁移指南 进行升级。
• 若您已经集成过低版本 SDK，更新至 2.0 SDK 后，请删除项目中的低版 t_s.bmp 安全图片文件，并从 涂鸦 IoT 开发平台 上获取新的 2.0 版本 App 密钥。
• 从 1.0.0 版本cube App SDK 开始，SDK 分为开发版和正式版。详情请参考 产品定价。开发版 SDK 仅供开发使用，请勿直接商用。如需上架商用，请前往平台购买正式版。购买正式版 SDK 后：
  1. 需在 IoT 平台重新构建正式版 SDK 并下载。
  2. 重新在项目中集成正式版 SDK。

集成 SDK

构建和下载 SDK

1. 前往 涂鸦 IoT 开发平台。

2. 选择 2.x.x 版本 SDK 或其他 UI 业务包。

   若之前使用过低版本 SDK，右上角可切换版本。

   

3. 选择构建 SDK。

   

4. 构建完成后，下载 SDK 进行集成。

   

5. 解压 ios_core_sdk.tar.gz，得到以下两个重要文件信息：

   • Build：存放您的 App 专属安全 SDK，它和 App 密钥信息一样重要，请妥善保管，谨防资源泄漏或对外公开。
   • ThingSmartCryption.podspec：用于在引用、集成使用 2.0 SDK。

6. （建议）将以上两个文件与 podfile 保持同级存放，便于后续引用操作。

使用 CocoaPods 集成

1. 更新 CocoaPods 至最新版本。CocoaPods 的使用请参考 CocoaPods 官方文档。

2. 在 Podfile 文件中添加以下内容：

   source 'https://github.com/tuya/tuya-private-specs.git'
   platform :ios, '11.0'
   
   target 'Your_Project_Name' do
       # 从涂鸦 IoT 开发平台（iot.tuya.com）构建和获取 ThingSmartCryption
       # 购买正式版后，需重新在涂鸦 IoT 开发平台构建 SDK 并重新集成
       # ./ 代表将 `ios_core_sdk.tar.gz` 解压之后所在目录与 `podfile` 同级
       # 若自定义存放目录，可以修改 `path` 为自定义目录层级
       pod "ThingSmartCryption", :path =>'./'
       pod "ThingSmartHomeKit", "2.0.0-cube.1"
   end
   

3. 在项目根目录下，执行 pod update 命令进行集成。

使用 iOS 配置文件

1. 导入独立域名配置文件。

   从平台下载 ThingSmartCryption.xcframework，放在工程目录下后，依次将下面文件夹中的 t_cdc.tcfg 文件替换成 PM 提供的 t_cdc.tcfg，然后执行 pod install 或者 pod update。

   

2. 验证独立域名是否生效。

   在此之前，请确认您已完成 SDK 快速集成 操作。

   您可以通过使用 [TuyaSmartSDK sharedInstance].debugMode = YES，来开启 SDK debug 日志功能。在 App 启动后，在控制台搜索 read custom domain config 日志，来确认是否已成功读取到独立域名配置文件。

   验证正常后，关闭 SDK debug 日志功能，重新打包后，上传到苹果 App Store 应用市场进行分发即可。

常见问题

• 问题 1： 未能读取到配置文件。

  • 分析：App 启动后控制台输出日志：Your project does not include a domain configuration file. To use a custom domain name, please go to the Tuya IoT Development Platform and download a domain configuration file. 此日志表示并未读取到配置文件。

  • 解决方法：请根据上文 导入 iOS 独立域名配置文件 步骤进行配置。

• 问题 2：读取到了配置文件，但解析异常。

  如果抛出 t_cdc.tcfg file load failed! 异常，问题原因通常有：

  可能原因	解决方法
  配置文件与 SDK 的秘钥不配套，导致解析失败。	建议确认 App 包名、秘钥是否配置正确。
  配置文件内容损坏，无法解析。	建议重新下载配置文件。
  TuyaSmartNetworkKit 组件版本较落后，请检查此组件版本在 Podfile.lock 里是否 >= 4.0.2	使用 pod update TuyaSmartNetworkKit 命令，更新此组件。

初始化 SDK

1. 在 Target > General 中打开项目设置，修改 Bundle Identifier 为您在 涂鸦 IoT 开发平台 设置的 iOS 包名。

2. 在项目的 PrefixHeader.pch 文件添加以下内容：

   #import <ThingSmartHomeKit/ThingSmartKit.h>
   

   如果是 Swift 项目，可以在 xxx_Bridging-Header.h 桥接文件中添加以下内容：

   #import <ThingSmartHomeKit/ThingSmartKit.h>
   

3. 打开 AppDelegate.m 文件，在 [AppDelegate application:didFinishLaunchingWithOptions:] 方法中初始化 SDK。

配置 SDK

- (void)startWithAppKey:(NSString *)appKey secretKey:(NSString *)secretKey;

参数说明

参数	说明	来源
appKey	App 唯一凭证信息	涂鸦 IoT 开发平台的 SDK 详情页 - 获取密钥
secretKey	App 密钥 key	涂鸦 IoT 开发平台的 SDK 详情页 - 获取密钥
bundleId	iOS App 应用包名	涂鸦 IoT 开发平台的 SDK 详情页 - iOS 应用包名

示例代码

Objective C：

[[ThingSmartSDK sharedInstance] startWithAppKey:<#your_app_key#> secretKey:<#your_secret_key#>];

Swift：

 ThingSmartSDK.sharedInstance()?.start(withAppKey: <#your_app_key#>, secretKey: <#your_secret_key#>)

至此，准备工作已经全部完毕。

打开 Debug 模式

在开发的过程中可以开启 Debug 模式，打印日志用于分析问题。

Objc:

#ifdef DEBUG
    [[ThingSmartSDK sharedInstance] setDebugMode:YES];
#else
#endif

Swift:

#if DEBUG
   ThingSmartSDK.sharedInstance()?.debugMode = true
#else
#endif

语言设置

接口返回的错误信息与文案等，将会根据您工程所支持的多语言和用户手机的当前语言来显示。如果想要支持某种语言，可以在工程中的 Localization 中添加您想要支持的语言。

演示工程主要介绍了 SDK 开发流程，以及一些简单的业务逻辑。在开发 App 之前，建议先按照本文完成演示工程的操作。

配置 Widget 工程

• Widget 创建步骤

• 修改 Podfile

  post_install do | installer |
      installer.pods_project.targets.each do | target |
          target.build_configurations.each do | config |
              config.build_settings['APPLICATION_EXTENSION_API_ONLY'] = 'NO'
          end
      end
  end
  

• AppGroups

  • 开启 AppGroups 权限
  • 在 SDK 初始化前，给 SDK 设置 AppGroups Name
  • 因为 AppGroups 只有付费开发者账号才能创建权限，所以免费开发者账号不能调试 Widget 应用

• 使用 AppKey、AppSecret 初始化 SDK

• 在用 AppKey 初始化 SDK 前设置 AppGroupName

  [ThingSmartSDK sharedInstance].appGroupId = APP_GROUP_NAME;
  [[ThingSmartSDK sharedInstance] startWithAppKey:SDK_APPKEY secretKey:SDK_APPSECRET];
  

使用 SDK

• 在主工程中设置当前 homeId。
• 使用 ThingSmartDeviceModel.switchDp 判断设备是否支持快捷开关。
• 需要在 viewWillAppear 中判断是否在主工程中切换了账号和房间，如果切换了需要刷新数据。

Demo App

准备 Demo

在 准备工作 阶段，您可以获取 iOS 版本 SDK 的 AppKey、AppSecret。

集成 SDK 时请确认 BundleId、AppKey、AppSecret 是否与涂鸦 IoT 平台上的信息一致，任意一个不匹配会导致 SDK 无法使用。

常见问题

SING_VALIDATE_FALED

• 问题现象 ：API 请求提示以下签名错误。

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

• 解决办法 ：确认 BundleId、AppKey、AppSecret 是否与 涂鸦 IoT 平台 上的信息一致，任意一个不匹配都将校验失败。具体请按照 准备工作 来进行检查。

• 注意事项：如果购买正式版，需重新在 IoT 平台构建 SDK 并替换密钥。