帮你快速理解、总结文档立即下载
文档中心>物联网开发平台>通用功能（应用端）>集成与登录>小程序

小程序

最近更新时间：2026-09-20 16:47:02
我的收藏

本页目录：

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

前提条件

开通服务

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

环境准备

安装 微信开发者工具。
一部 iPhone 或 Android 真机，安装并登录微信。模拟器不支持原生组件（即 <live-pusher> 和 <live-player> 标签），需要在真机上进行运行体验。
申请小程序 AppID。由于小程序测试号不具备 <live-pusher> 和 <live-player> 的使用权限，需要申请常规小程序账号进行开发。
申请 live-pusher、live-player 和双人音视频对话权限。该权限仅接入实时监控、视频通话能力时需要，仅完成本文的登录接入可跳过。

创建项目

参考以下步骤创建一个新的小程序项目。如果已有项目，可跳过本节。
1. 打开微信开发者工具，单击 +（新建项目）。
2. 项目类型选择小程序，填写项目名称与本地目录。
3. AppID 填写前提条件中申请的常规小程序 AppID（小程序测试号不具备 <live-pusher> 和 <live-player> 的使用权限）。
4. 后端服务选择不使用云服务，模板选择 JS-基础模板，单击确定完成创建。

集成插件

1. 在小程序根目录的 app.json 中添加腾讯云物联网插件声明：
{
  "plugins": {
    "tx-iot-sdk": {
      "version": "latest",
      "provider": "wx5201edc27c631209"
    }
  }
}
2. 保存后重新编译工程，插件即集成到小程序中。version 为 latest 时会自动使用插件的最新版本，正式项目建议固定为具体版本号，避免插件升级引入非预期变更。
3. 在需要使用 SDK 的页面或逻辑文件中，通过 requirePlugin 引入插件导出的接口：
const { TXIoTEngine, TXIoTUserSignature } = requirePlugin('tx-iot-sdk');

接入步骤

步骤 1：获取 SDK 实例

调用 TXIoTEngine.getInstance 获取 SDK 实例，注册登录、签名过期和设备状态推送监听。
const engine = await TXIoTEngine.getInstance();
engine.addListener({
  onLoginSuccess() {
    // 登录成功
  },
  // 其他回调按需实现
});

步骤 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=，可用于自验签名实现是否正确。
参考以下示例计算签名。客户端调试示例基于 js-sha1 库（需通过 npm 安装并在微信开发者工具中执行「构建 npm」）；正式上线时签名在业务后台计算，参考服务端示例：
客户端（小程序）
import { sha1 } from 'js-sha1';

function generateSignature(
  appSecret: string,
  requestId: string,
  timestamp: number,
  nonce: number,
  appKey: string,
  openId: string,
): string {
  const params: Record<string, string> = {
    RequestId: requestId,
    Timestamp: String(timestamp),
    Nonce: String(nonce),
    AppKey: appKey,
    OpenID: openId,
  };
  // 去掉值为空的参数，按参数名的字典序升序排列，使用 & 连接
  const source = Object.keys(params)
    .filter((key) => params[key] !== undefined && params[key] !== '')
    .sort()
    .map((key) => `${key}=${params[key]}`)
    .join('&');
  // 使用 AppSecret 对签名原文进行 HMAC-SHA1 签名
  const buffer = sha1.hmac.arrayBuffer(appSecret, source);
  // 对签名结果进行 Base64 编码
  return wx.arrayBufferToBase64(buffer);
}

const signature = generateSignature(
  'your_app_secret',
  '8b8d499bbba1ac28b6da21b4',
  1546315200,
  71087795,
  'your_app_key',
  'user_001',
);
console.log(signature); // aSLzd4Ett7RsiLhrYht6Yk9+0qY=

步骤 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
签名计算结果。
const userSignature = new TXIoTUserSignature();
userSignature.requestId = requestId;   // 对应签名参数 RequestId
userSignature.timestamp = timestamp;   // 对应签名参数 Timestamp（秒级）
userSignature.nonce = nonce;           // 对应签名参数 Nonce
userSignature.signature = signature;   // 上一步计算得到的签名

engine.login(appKey, userId, userSignature);

步骤 4：验证登录结果

登录成功后，调用 getFamilyManager 获取家庭管理实例并拉取家庭列表，以此验证登录态与网络链路是否正常。返回的 familyId 是后续绑定设备、查询设备列表的必备参数，请妥善保存。
const familyManager = engine.getFamilyManager();
if (!familyManager) {
  // SDK 未登录或登录态已失效
  return;
}

try {
  let familyList = await familyManager.getFamilyList();
  if (familyList.length === 0) {
    // 当前账号下没有家庭，先创建一个
    const familyInfo = await familyManager.createFamily('我的家庭');
    familyList = [familyInfo];
  }
  // familyList: TXIoTFamilyInfo[]
  // 选择一个家庭，记录 familyId
  const familyId = familyList[0].familyId;
} catch (err) {
  // err: { code, message }
  console.error('获取家庭信息失败:', err.code, err.message);
}

常见问题

为什么 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=）自验签名实现是否正确。

调用 requirePlugin 报错或提示插件不存在？

确认 app.json 中已正确声明 plugins（插件名 tx-iot，provider 为 wx5201edc27c631209），保存后重新编译工程。
确认使用的是常规小程序 AppID，小程序测试号不支持插件能力。

下一步

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