帮你快速理解、总结文档立即下载
文档中心>物联网开发平台>应用端开发>集成与登录>iOS

iOS

最近更新时间：2026-09-20 16:47:02
本文档已由 AI 辅助审校
我的收藏

本页目录：

本文介绍如何在 iOS 平台集成腾讯云物联网（IoT）应用端 SDK 并完成登录：涵盖工程配置、SDK 引入、登录签名计算与登录调用，并通过拉取家庭列表验证接入是否成功。设备绑定、设备分享、远程控制等能力在登录完成后按需接入，参见本文 下一步 章节。

前提条件

开通服务

请先按照 开通服务 文档，完成服务开通和应用创建，并获取以下信息：
AppKey：登录必需。
AppSecret：登录必需，用于计算登录签名。
ProductId：接入设备绑定、物模型等能力时使用，本文不涉及。
DeviceName：接入设备绑定、物模型等能力时使用，本文不涉及。

环境准备

Xcode 11.0 及以上版本。
确保项目已设置有效的开发者签名。
一台 iOS 12.0 及以上真机（与 Podfile 的 platform :ios, '12.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
使用 your_app_secret 作为 AppSecret 对上述原文计算，期望得到的签名为 aSLzd4Ett7RsiLhrYht6Yk9+0qY=，可用于自验签名实现是否正确。
参考以下示例计算签名。客户端示例基于系统自带的 CommonCrypto 框架；正式上线时签名在业务后台计算，参考服务端示例：
客户端（Objective-C）
#import <CommonCrypto/CommonHMAC.h>

+ (NSString *)generateSignatureWithAppSecret:(NSString *)appSecret
                                   requestId:(NSString *)requestId
                                   timestamp:(int64_t)timestamp
                                       nonce:(NSInteger)nonce
                                      appKey:(NSString *)appKey
                                      openId:(NSString *)openId {
    NSDictionary<NSString *, NSString *> *params = @{
        @"RequestId": requestId,
        @"Timestamp": @(timestamp).stringValue,
        @"Nonce": @(nonce).stringValue,
        @"AppKey": appKey,
        @"OpenID": openId,
    };

    // 去掉值为空的参数，按参数名的字典序升序排列
    NSArray<NSString *> *sortedKeys = [params.allKeys sortedArrayUsingSelector:@selector(compare:)];
    NSMutableArray<NSString *> *pairs = [NSMutableArray array];
    for (NSString *key in sortedKeys) {
        NSString *value = params[key];
        if (value.length == 0) {
            continue;
        }
        [pairs addObject:[NSString stringWithFormat:@"%@=%@", key, value]];
    }
    // 按 Key=Value 格式拼接，使用 & 连接
    NSString *source = [pairs componentsJoinedByString:@"&"];

    // 使用 AppSecret 对签名原文进行 HMAC-SHA1 签名
    NSData *keyData = [appSecret dataUsingEncoding:NSUTF8StringEncoding];
    NSData *sourceData = [source dataUsingEncoding:NSUTF8StringEncoding];
    unsigned char digest[CC_SHA1_DIGEST_LENGTH];
    CCHmac(kCCHmacAlgSHA1, keyData.bytes, keyData.length,
           sourceData.bytes, sourceData.length, digest);

    // 对签名结果进行 Base64 编码
    NSData *digestData = [NSData dataWithBytes:digest length:CC_SHA1_DIGEST_LENGTH];
    return [digestData base64EncodedStringWithOptions:0];
}
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 获取家庭管理实例并拉取家庭列表，以此验证登录态与网络链路是否正常。返回的 familyId 是后续绑定设备、查询设备列表的必备参数，请妥善保存。
TXIoTFamilyManager *familyManager = [iotEngine getFamilyManager];
if (familyManager == nil) {
    // SDK 未登录或登录态已失效
    return;
}

TXIoTCallback<NSArray<TXIoTFamilyInfo *> *> *callback = [[TXIoTCallback alloc] init];
callback.onSuccess = ^(NSArray<TXIoTFamilyInfo *> * _Nullable familyList) {
    if (familyList.count == 0) {
        // 当前账号下没有家庭，调用 createFamily 创建（见下方示例）
        return;
    }
    // 选择一个家庭，记录 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];

常见问题

为什么 getFamilyManager 或 getDeviceManager 返回 nil？

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

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

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

登录失败或提示签名错误如何排查？

请按以下顺序逐项核对：
1. AppKey 与 AppSecret 是否来自同一个应用且配对正确。
2. 签名参数 OpenID 与登录接口的 userId 是否完全一致。
3. Timestamp 是否为 UNIX 秒级时间戳（非毫秒），且与当前时间偏差在允许范围内。
4. 参与签名的参数是否已去掉空值、并按参数名字典序升序排列后以 & 连接。
5. 签名算法是否为 HMAC-SHA1，且签名结果经过 Base64 编码。
可使用 签名计算示例 中给出的期望输出（aSLzd4Ett7RsiLhrYht6Yk9+0qY=）自验签名实现是否正确。

下一步

完成基础接入后，您还可以继续接入以下能力：
设备绑定
远程控制
家庭管理
中国站