快速集成

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

SDK 版本

• 如果您采用的 5.x.x 以下版本 SDK，请提前根据 迁移指南 进行升级。
• 若您已经集成过低版本 SDK，更新至 5.0 SDK 后，请删除项目中的低版 t_s.bmp 安全图片文件，并从 涂鸦开发者平台 上获取新的 5.0 版本 App 密钥。

集成 SDK

构建和下载 SDK

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

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

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

   

3. 选择构建 SDK。

   

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

   

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

   • Build：存放您的 App 专属安全 SDK，它和 App 密钥信息一样重要，请妥善保管，谨防资源泄漏或对外公开。
   • ThingSmartCryption.podspec：用于在引用、集成使用 5.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
       # 从涂鸦开发者平台构建和获取 ThingSmartCryption
       # 购买正式版后，需重新在平台构建 SDK 并重新集成
       # ./ 代表将 ios_core_sdk.tar.gz 解压之后所在目录与 podfile 同级
       # 若自定义存放目录，可以修改 path 为自定义目录层级
       pod "ThingSmartCryption", :path =>'./'
       pod "ThingSmartHomeKit"
   end
   
   target 'Your_Extension_Target_Name' do
       # 所有扩展程序 target ，只要引入 ThingSmartHomeKit 则必须同时引入 ThingSmartCryption
       pod "ThingSmartCryption", :path =>'./'
       pod "ThingSmartHomeKit"
   end
   

3. 如果您的 App 包含扩展程序 target，例如 Siri 和 Widget，确保 Podfile 配置正确。

4. 在项目根目录下，执行 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 应用市场进行分发即可。

初始化 SDK

1. 在 Target > General 中打开项目设置，修改 Bundle Identifier 为您在 涂鸦开发者平台 设置的 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 唯一凭证信息	平台的 SDK 详情页 - 获取密钥
secretKey	App 密钥 key	平台的 SDK 详情页 - 获取密钥
bundleId	iOS App 应用包名	平台的 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 模式，打印日志用于分析问题。

Objective-C:

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

Swift:

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

语言设置

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

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

配置 Widget 工程

Widget 创建步骤如下：

1. 修改 Podfile。

   target 'Your_Extension_Target_Name' do
       # 1. 所有扩展程序 target ，只要引入 ThingSmartHomeKit 则必须同时引入 ThingSmartCryption
       # 2. 从涂鸦开发者平台构建和获取 ThingSmartCryption
       # 购买正式版后，需重新在平台构建 SDK 并重新集成
       # ./ 代表将 ios_core_sdk.tar.gz 解压之后所在目录与 podfile 同级
       # 若自定义存放目录，可以修改 path 为自定义目录层级
       pod "ThingSmartCryption", :path =>'./'
       pod "ThingSmartHomeKit"
   end
   
   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
   

   • 配置 Target，在 Target 中按需引入组件或 SDK。
   • 需要注意，引入 SDK 的同时必须引入 ThingSmartCryption。

2. 设置 AppGroups。

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

3. 使用 AppKey 和 AppSecret 初始化 SDK。

4. 在用 AppKey 初始化 SDK 之前，设置 App Groups Name。

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

Demo App

准备 Demo

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

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

Demo 概述

演示工程提供了 Swift 与 Objective-C 的版本，访问 Objective-C 示例 获取演示工程。工程主要包括了以下功能：

• 用户账号注册及登录

• 用户信息管理

• 家庭管理

• Wi-Fi 快连和热点模式配网

• 设备控制

  

常见问题

SING_VALIDATE_FALED

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

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

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