物联网开发平台鸿蒙

本文将介绍如何在鸿蒙（HarmonyOS）平台集成腾讯云物联网（IoT）应用端 SDK 并完成登录：涵盖工程配置、SDK 引入、签名计算与登录调用，并通过拉取家庭列表验证接入是否成功。设备绑定、设备分享、远程控制等能力在登录完成后按需接入，参见本文 下一步 章节。
前提条件
开通服务
请先按照 开通服务 文档，完成服务开通和应用创建，并获取以下信息：
AppKey：登录必需。
AppSecret：登录必需，用于计算登录签名。
ProductId：接入设备绑定、物模型等能力时使用，本文不涉及。
DeviceName：接入设备绑定、物模型等能力时使用，本文不涉及。
环境准备
DevEco Studio 5.0 及以上版本。
一台 HarmonyOS NEXT 真机，且项目已配置有效的签名信息。
创建项目
参考以下步骤创建一个新的鸿蒙项目。如果已有项目，可跳过本节。
1. 打开 DevEco Studio，选择 Create Project（新建项目）。
2. 选择 Application 下的 Empty Ability 模板，单击 Next。
3. 设置 Project name、Bundle name、Compile SDK 等项目基本信息，单击 Finish 完成创建。
集成 SDK
1. 将 SDK 的 HAR 包（如 liteavsdk.har）拷贝到模块目录下（例如 entry/lib/），并在模块的 oh-package.json5 中添加依赖：
// entry/oh-package.json5
{
  "dependencies": {
    "@tencentcloud/liteavsdk_iot": "file:./lib/liteavsdk.har"
  }
}
2. 在模块的 module.json5 中声明所需权限。网络权限为必需；麦克风与摄像头权限在涉及语音对讲或视频通话时需要，且需在运行时向用户动态申请：
// entry/src/main/module.json5
{
  "module": {
    "requestPermissions": [
      { "name": "ohos.permission.INTERNET" },
      { "name": "ohos.permission.MICROPHONE" },
      { "name": "ohos.permission.CAMERA" }
    ]
  }
}
3. 执行 Sync Now 同步依赖后，即可在 ArkTS 代码中引用 SDK：
import { getIoTEngineInstance } from '@tencentcloud/liteavsdk_iot'
接入步骤
步骤 1：获取 SDK 实例
调用全局函数 getIoTEngineInstance 获取 SDK 单例，并注册 TXIoTEngineListener 监听登录、签名过期和设备状态推送。该单例在整个 App 生命周期内复用，以保证登录态在各页面间共享。
import { getIoTEngineInstance, TXIoTEngine, TXIoTEngineListener } from '@tencentcloud/liteavsdk_iot'
﻿
// 获取单例实例（context 为可选参数）
const iotEngine: TXIoTEngine = getIoTEngineInstance()
﻿
// 注册监听：TXIoTEngineListener 为接口，所有回调均为可选，按需实现
const engineListener: TXIoTEngineListener = {
  onLoginSuccess: () => {
    // 登录成功
  },
  onLoginFailure: (errCode, errMsg) => {
    // 登录失败
  },
  onUserSignatureExpired: () => {
    // 登录签名过期，请重新计算签名后再次调用 login
  },
  onReceivePushMessage: (pushMessage) => {
    // 接收设备在线、离线等状态变更
  }
}
iotEngine.addListener(engineListener)
步骤 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=，可用于自验签名实现是否正确。
参考以下示例计算签名。客户端示例基于系统自带的 CryptoFramework（加解密算法框架）；正式上线时签名在业务后台计算，参考服务端示例：
客户端（ArkTS）
服务端（Python）
import cryptoFramework from '@ohos.security.cryptoFramework'
import util from '@ohos.util'
﻿
// 去掉空值参数，按参数名字典序升序排列后以 & 连接，得到签名原文
function createSignSource(appKey: string, openId: string, requestId: string,
                          timestamp: number, nonce: number): string {
  const pairs = [
    `AppKey=${appKey}`,
    `Nonce=${nonce}`,
    `OpenID=${openId}`,
    `RequestId=${requestId}`,
    `Timestamp=${timestamp}`
  ]
  return pairs.sort().join('&')
}
﻿
// 使用 AppSecret 对签名原文进行 HMAC-SHA1 签名，结果 Base64 编码
async function generateSignature(appSecret: string, source: string): Promise<string> {
  const encoder = new util.TextEncoder()
  const symKeyGenerator = cryptoFramework.createSymKeyGenerator('HMAC')
  const symKey = await symKeyGenerator.convertKey({ data: encoder.encodeInto(appSecret) })
  const mac = cryptoFramework.createMac('SHA1')
  await mac.init(symKey)
  await mac.update({ data: encoder.encodeInto(source) })
  const result = await mac.doFinal()
  return new util.Base64Helper().encodeToStringSync(result.data)
}
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)
步骤 3：登录 SDK
调用 TXIoTEngine.login 登录 SDK，传入上一步计算得到的签名参数。
参数说明
参数
类型
说明
appKey
string
从 开通服务 文档获取的 AppKey。
userId
string
用户标识，支持数字、字母、下划线，长度不超过 32 字节。
首次使用会自动注册，已注册则登录原有账号，该账号下的设备绑定关系仍然保留。需与签名参数 OpenID 保持一致。
userSignature.requestId
string
对应签名参数 RequestId。
userSignature.timestamp
number
对应签名参数 Timestamp。
userSignature.nonce
number
对应签名参数 Nonce。
userSignature.signature
string
签名计算结果。
region
TXIoTRegion
服务区域，见 TXIoTRegion。境内使用 TXIoTRegion.DEFAULT，海外使用 TXIoTRegion.OVERSEAS。
import { TXIoTUserSignature, TXIoTRegion } from '@tencentcloud/liteavsdk_iot'
﻿
const userSignature = new TXIoTUserSignature()
userSignature.requestId = requestId
userSignature.timestamp = timestamp
userSignature.nonce = nonce
userSignature.signature = signature
﻿
// region：境内使用 TXIoTRegion.DEFAULT，海外使用 TXIoTRegion.OVERSEAS
iotEngine.login(appKey, userId, userSignature, TXIoTRegion.DEFAULT)
步骤 4：验证登录结果
登录成功后，调用 getFamilyManager 获取家庭管理实例并拉取家庭列表，以此验证登录态与网络链路是否正常。返回的 familyId 是后续绑定设备、查询设备列表的必备参数，请妥善保存。
const familyManager = iotEngine.getFamilyManager()
if (!familyManager) {
  // SDK 未登录或登录态已失效
  return
}
﻿
familyManager.getFamilyList({
  onSuccess: (familyList) => {
    if (familyList.length === 0) {
      // 当前账号下没有家庭，调用 createFamily 创建（见下方示例）
      return
    }
    // 选择一个家庭，记录 familyId
    const familyId = familyList[0].familyId
  },
  onError: (errorCode, errorMessage) => {
    // 获取家庭列表失败
  }
})
如果当前账号下没有家庭，可调用 createFamily 创建：
familyManager.createFamily('我的家庭', {
  onSuccess: (familyInfo) => {
    // 创建成功，记录 familyInfo.familyId
  },
  onError: (errorCode, errorMessage) => {
    // 创建家庭失败
  }
})
常见问题
为什么 getFamilyManager 或 getDeviceManager 返回 null？
SDK 尚未登录或登录态已失效。请先调用 TXIoTEngine.login，并在收到 onLoginSuccess 后再获取对应 Manager。
登录签名过期后如何处理？
当收到 onUserSignatureExpired 回调时，请重新计算登录签名，然后再次调用 TXIoTEngine.login。
登录失败或提示签名错误如何排查？
请按以下顺序逐项核对：
1. AppKey 与 AppSecret 是否来自同一个应用且配对正确。
2. 签名参数 OpenID 与登录接口的 userId 是否完全一致。
3. Timestamp 是否为 UNIX 秒级时间戳（非毫秒），且与当前时间偏差在允许范围内。
4. 参与签名的参数是否已去掉空值、并按参数名字典序升序排列后以 & 连接。
5. 签名算法是否为 HMAC-SHA1，且签名结果经过 Base64 编码。
可使用 签名计算示例 中给出的期望输出（aSLzd4Ett7RsiLhrYht6Yk9+0qY=）自验签名实现是否正确。
下一步
完成基础接入后，您还可以继续接入以下能力：
﻿设备绑定﻿
﻿远程控制﻿
﻿家庭管理﻿

参数	说明
`RequestId`	唯一请求 ID，建议使用 UUID。
`Timestamp`	当前 UNIX 秒级时间戳。
`Nonce`	随机正整数，用于和时间戳一起防重放。
`AppKey`	从开通服务文档获取的 AppKey。
`OpenID`	用户标识，需与后续登录的 `userId` 保持一致。支持数字、字母、下划线，长度不超过 32 字节。

参数	类型	说明
`appKey`	string	从开通服务文档获取的 AppKey。
`userId`	string	用户标识，支持数字、字母、下划线，长度不超过 32 字节。首次使用会自动注册，已注册则登录原有账号，该账号下的设备绑定关系仍然保留。需与签名参数 `OpenID` 保持一致。
`userSignature.requestId`	string	对应签名参数 `RequestId`。
`userSignature.timestamp`	number	对应签名参数 `Timestamp`。
`userSignature.nonce`	number	对应签名参数 `Nonce`。
`userSignature.signature`	string	签名计算结果。
`region`	TXIoTRegion	服务区域，见 `TXIoTRegion`。境内使用 `TXIoTRegion.DEFAULT`，海外使用 `TXIoTRegion.OVERSEAS`。

鸿蒙

本页目录：

前提条件

开通服务

环境准备

创建项目

集成 SDK

接入步骤

步骤 1：获取 SDK 实例

步骤 2：计算登录签名

签名参数

签名计算规则

签名计算示例

步骤 3：登录 SDK

参数说明

步骤 4：验证登录结果

常见问题

为什么 `getFamilyManager` 或 `getDeviceManager` 返回 `null`？

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

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

下一步