帮你快速理解、总结文档立即下载
文档中心>物联网开发平台>通用功能（应用端）>快速接入>iOS

iOS

最近更新时间：2026-07-30 12:00:38

我的收藏

本页目录：

本文将介绍如何快速完成腾讯云物联网（IoT）应用端 SDK 的接入，在 iOS 平台完成登录、家庭管理、设备绑定和设备命令下发等基础能力验证。

前提条件

开通服务

请先按照 开通服务 文档，完成服务开通、设备创建和应用创建，并获取设备信息：
AppKey
AppSecret
ProductId
DeviceName

定义物模型

请先参考 配置物模型 文档，完成上面 ProductId 对应产品物模型的定义。

环境准备

Xcode 11.0 及以上版本。
确保项目已设置有效的开发者签名。
一台 iOS 9.0 及以上真机。

创建项目

参考以下步骤创建一个新的 iOS 项目。如果已有项目，可跳过本节。
1. 打开 Xcode，选择 New Project（新建项目）。
2. 在平台标签中选择 iOS，然后选择 App 模板，单击 Next。

3. 在 Choose options for your new project 页面设置 Product Name、Team、Organization Identifier 等项目基本信息，单击 Next 并选择保存路径，最后单击 Create 完成创建。


集成 SDK

1. 在项目根目录的 Podfile 中添加 IoT SDK 依赖：
说明：
Podfile 是 iOS 项目的 CocoaPods 依赖配置文件，位于项目根目录（与 .xcodeproj 同级），用文本编辑器编辑即可。如果目录下没有 Podfile，先在终端进入项目目录执行 pod init 生成。
# 将下方的 'YourApp' 替换为您 Xcode 项目中实际的 Target 名称
platform :ios, '12.0'

target 'YourApp' do
  # 物联网应用端 SDK（IOT 定制版）
  pod 'TXLiteAVSDK_Professional',:podspec =>'https://liteav.sdk.qcloud.com/pod/liteavsdkspec/customer/TXLiteAVSDK_Professional_IOT_13.4.0.25016.podspec'
end
Xcode 16 兼容性问题：若使用 Xcode 16 及以上版本，pod install 后可能报部署目标版本错误。请在 Podfile 末尾添加以下配置解决：
post_install do |installer|
  installer.pods_project.build_configurations.each do |config|
    config.build_settings['IPHONEOS_DEPLOYMENT_TARGET'] = '12.0'
  end
  installer.pods_project.targets.each do |target|
    target.build_configurations.each do |config|
      config.build_settings['IPHONEOS_DEPLOYMENT_TARGET'] = '12.0'
    end
  end
end
2. 完成配置后，在终端执行 pod install，SDK 将自动下载并集成到工程中。

3. pod install 完成后，在 Finder 中找到项目目录下的 .xcworkspace 文件并双击打开（请打开 .xcworkspace 而非 .xcodeproj）。
4. 在 Xcode 的 Build Settings 中搜索 User Script Sandboxing，将其值设置为 No。
5. 在 Signing & Capabilities 中确认已配置有效的开发者签名。

接入步骤

步骤 1：获取 SDK 实例

调用 TXIoTEngine.getInstance 获取 SDK 实例，并注册 TXIoTEngineDelegate 监听登录、签名过期和设备状态推送。
// 获取单例实例
TXIoTEngine *iotEngine = [TXIoTEngine getInstance];
// 注册监听（self 需遵循 TXIoTEngineDelegate 协议）
[iotEngine addDelegate:self];
在监听对象中实现 TXIoTEngineDelegate 协议方法：
#pragma mark - TXIoTEngineDelegate

- (void)onLoginSuccess {
    // 登录成功
}

- (void)onLoginFailure:(TXIoTErrorCode)errCode errMsg:(NSString *)errMsg {
    // 登录失败
}

- (void)onUserSignatureExpired {
    // 登录签名过期，请重新计算签名后再次调用 login
}

- (void)onReceivePushMessage:(TXIoTPushMessage *)pushMessage {
    // 接收设备在线、离线等状态变更
}

步骤 2：计算登录签名

说明：
快速接入阶段可直接在客户端计算签名进行调试。正式上线时请将签名计算逻辑放在业务后台，不要将 AppSecret 保存在客户端。

签名参数

参与签名的参数：
参数
说明
RequestId
唯一请求 ID，建议使用 UUID。
Timestamp
当前 UNIX 秒级时间戳。
Nonce
随机正整数，用于和时间戳一起防重放。
AppKey
控制台应用详情中的 AppKey。
OpenID
用户标识，需与后续登录的 userId 保持一致。支持数字、字母、下划线，长度不超过 32 字节。
注意：
OpenID 与 UserID 的关系：签名参数名为 OpenID，SDK 登录接口参数名为 userId，两者是同一个东西，值必须保持一致。

签名计算规则

1. 去掉值为空的参数。
2. 将参数按参数名的字典序升序排列。
3. 将排序后的参数按 Key=Value 格式拼接。
4. 使用 & 连接所有参数，得到签名原文。
5. 使用从开通服务文档获取的 AppSecret 对签名原文进行 HMAC-SHA1 签名。
6. 对签名结果进行 Base64 编码，得到最终 Signature。

签名计算示例

例如，参与签名的参数如下：
RequestId=8b8d499bbba1ac28b6da21b4
Timestamp=1546315200
Nonce=71087795
AppKey=your_app_key
OpenID=user_001
排序后的签名原文：
AppKey=your_app_key&Nonce=71087795&OpenID=user_001&RequestId=8b8d499bbba1ac28b6da21b4&Timestamp=1546315200
参考以下 Python 示例计算签名：
import base64
import hashlib
import hmac

def generate_signature(app_secret, request_id, timestamp, nonce, app_key, user_id):
    params = {
        "RequestId": request_id,
        "Timestamp": str(timestamp),
        "Nonce": str(nonce),
        "AppKey": app_key,
        "OpenID": user_id,
    }
    # 去掉值为空的参数
    params = {
        key: value
        for key, value in params.items()
        if value is not None and value != ""
    }
    # 按参数名的字典序升序排列
    sorted_items = sorted(params.items(), key=lambda item: item[0])
    # 按 Key=Value 格式拼接，使用 & 连接
    source = "&".join([f"{key}={value}" for key, value in sorted_items])
    # 使用 AppSecret 对签名原文进行 HMAC-SHA1 签名
    digest = hmac.new(
        app_secret.encode("utf-8"),
        source.encode("utf-8"),
        hashlib.sha1,
    ).digest()
    # 对签名结果进行 Base64 编码
    signature = base64.b64encode(digest).decode("utf-8")
    return signature

signature = generate_signature(
    app_secret="your_app_secret",
    request_id="8b8d499bbba1ac28b6da21b4",
    timestamp=1546315200,
    nonce=71087795,
    app_key="your_app_key",
    user_id="user_001",
)
print(signature)

Running Environment

Operating System: Ubuntu 24.04.3 LTS / x86_64
Runtime Version: Python 3.11.1

步骤 3：登录 SDK

调用 TXIoTEngine.login 登录 SDK，传入上一步计算得到的签名参数。

参数说明

参数
类型
说明
appKey
NSString
控制台应用详情中的 AppKey。
userId
NSString
用户标识，支持数字、字母、下划线，长度不超过 32 字节。
首次使用会自动注册，已注册则登录原有账号，该账号下的设备绑定关系仍然保留。需与签名参数 OpenID 保持一致。
userSignature.requestId
NSString
对应签名参数 RequestId。
userSignature.timestamp
int64_t
对应签名参数 Timestamp。
userSignature.nonce
NSInteger
对应签名参数 Nonce。
userSignature.signature
NSString
签名计算结果。
TXIoTUserSignature *userSignature = [[TXIoTUserSignature alloc] init];
userSignature.requestId = requestId;
userSignature.timestamp = timestamp;
userSignature.nonce = nonce;
userSignature.signature = signature;

[iotEngine login:appKey userId:userId userSignature:userSignature];

步骤 4：获取家庭列表

登录成功后，调用 getFamilyManager 获取家庭管理实例，再调用 getFamilyList 获取家庭列表。后续绑定设备时需要 familyId。
TXIoTFamilyManager *familyManager = [iotEngine getFamilyManager];
if (familyManager == nil) {
    // SDK 未登录或登录态已失效
    return;
}

TXIoTCallback<NSArray<TXIoTFamilyInfo *> *> *callback = [[TXIoTCallback alloc] init];
callback.onSuccess = ^(NSArray<TXIoTFamilyInfo *> * _Nullable familyList) {
    // 选择一个家庭，记录 familyId
    NSString *familyId = familyList.firstObject.familyId;
};
callback.onError = ^(TXIoTErrorCode errorCode, NSString * _Nullable errorMessage) {
    // 获取家庭列表失败
};
[familyManager getFamilyList:callback];
如果当前账号下没有家庭，可调用 createFamily 创建：
TXIoTCallback<TXIoTFamilyInfo *> *callback = [[TXIoTCallback alloc] init];
callback.onSuccess = ^(TXIoTFamilyInfo * _Nullable familyInfo) {
    // 创建成功，记录 familyId
};
callback.onError = ^(TXIoTErrorCode errorCode, NSString * _Nullable errorMessage) {
    // 创建家庭失败
};
[familyManager createFamily:@"我的家庭" callback:callback];

步骤 5：绑定设备

绑定设备时需要设备绑定签名（DeviceSignature），通过 API Explorer 在线调试获取。
打开 GenSingleDeviceSignatureOfPublic 接口，填入从 开通服务 文档获取的 ProductId、DeviceName（Expire 自己选合适的就行），单击在线调试，从返回结果的 Response.DeviceSignature 中获取签名值。

调用 getDeviceManager 获取设备管理实例，再调用 bindDevice 将设备绑定到指定家庭。
TXIoTDeviceManager *deviceManager = [iotEngine getDeviceManager];
if (deviceManager == nil) {
    // SDK 未登录或登录态已失效
    return;
}

TXIoTCallback<TXIoTDeviceInfo *> *callback = [[TXIoTCallback alloc] init];
callback.onSuccess = ^(TXIoTDeviceInfo * _Nullable deviceInfo) {
    // 绑定成功，记录 deviceId 用于后续控制设备
    TXIoTDeviceId *deviceId = deviceInfo.deviceId;
};
callback.onError = ^(TXIoTErrorCode errorCode, NSString * _Nullable errorMessage) {
    // 绑定失败
};
[deviceManager bindDevice:familyId deviceBindSignature:@"您的签名" callback:callback];

步骤 6：发送设备命令

调用 sendCommand 向设备发送物模型命令。jsonData 需与本文 前提条件 章节产品物模型定义保持一致。
sendCommand 的 deviceId 参数有以下两种来源，二者选其一即可：
方式一（推荐，需先完成步骤5的设备绑定）：从绑定成功回调的 deviceInfo.deviceId 中获取。
方式二：使用控制台获取的 ProductId 和 DeviceName 手动构造（仍需完成步骤5的设备绑定）。
// 获取 deviceId（以下两种方式任选其一）：

// 【方式一：推荐】从步骤5绑定成功回调中获取
// TXIoTDeviceId *deviceId = deviceInfo.deviceId;

// 【方式二】使用 ProductId + DeviceName 手动构造
// ProductId 和 DeviceName 来自前提条件章节从控制台获取的值
// TXIoTDeviceId *deviceId = [[TXIoTDeviceId alloc] init];
// deviceId.productId = @"your_product_id";
// deviceId.deviceName = @"your_device_name";

NSString *jsonData = @"{\\"power_switch\\":1}"; // 需要与产品物模型定义保持一致
TXIoTCallback<NSString *> *callback = [[TXIoTCallback alloc] init];
callback.onSuccess = ^(NSString * _Nullable result) {
    // 命令发送成功
};
callback.onError = ^(TXIoTErrorCode errorCode, NSString * _Nullable errorMessage) {
    // 命令发送失败
};
[deviceManager sendCommand:deviceId jsonData:jsonData callback:callback];  // 传入方式一或方式二获取的 deviceId

常见问题

为什么 getFamilyManager 或 getDeviceManager 返回 nil？

SDK 尚未登录或登录态已失效。请先调用 TXIoTEngine.login，并在收到 onLoginSuccess 后再获取对应 Manager。

登录签名过期后如何处理？

当收到 onUserSignatureExpired 回调时，请重新计算登录签名，然后再次调用 TXIoTEngine.login。

绑定设备失败如何排查？

请检查 familyId 是否属于当前登录用户，设备绑定签名是否正确，以及设备是否已被其他家庭绑定。SDK 会在 onError 中返回具体错误码和错误信息。

下一步

完成基础接入后，您还可以继续接入以下能力：
绑定与分享
远程控制
实时监控
视频通话
中国站