物联网开发平台 Android（集成与登录）

二、开通服务

请先按照 开通服务 文档，完成服务开通和应用创建，并获取以下信息：

·AppKey：登录必需。

·AppSecret：登录必需，用于计算登录签名。

·ProductId：接入设备绑定、物模型等能力时使用，这篇不涉及。

·DeviceName：接入设备绑定、物模型等能力时使用，这篇不涉及。

三、环境准备

·Android Studio 3.5 及以上版本。

·最低兼容 Android 4.4（SDK API Level 19），建议 Android 5.0（SDK API Level 21）及以上。

四、创建项目

参考以下步骤创建一个新的 Android 项目。如果已有项目，可跳过本节。

1. 打开 Android Studio，选择 New Project（新建项目）。

2. 选择 Empty Views Activity 模板，单击 Next。

3. 在 Configure your project 页面配置：

·Language 选择 Java。

·Minimum SDK 建议 Android 5.0（API 21）及以上。

·Build configuration language 选择 Groovy DSL (build.gradle)。

五、集成 SDK

1. 在 app/build.gradle（非根目录的 build.gradle）的 dependencies 中添加 IoT SDK 依赖：

dependencies { // 物联网应用端 SDK implementation 'com.tencent.liteav:LiteAVSDK_IOT:latest.release'}

2. 完成以上配置后，在 Android Studio 的工具栏单击 Sync Now（或执行 File > Sync Project with Gradle Files）后 SDK 将自动集成到目标工程中。

七、步骤 1：获取 SDK 实例

调用 TXIoTEngine.getInstance 获取 SDK 实例，注册登录、签名过期和设备状态推送监听。

TXIoTEngine iotEngine = TXIoTEngine.getInstance(getApplicationContext());iotEngine.addListener(new TXIoTEngine.TXIoTEngineListener() { @Override public void onLoginSuccess() { // 登录成功 } //其他回调省略实现});

八、步骤 2：计算登录签名

注意：说明：

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

九、签名参数

参与签名的参数：

注意：OpenID 与 UserID 的关系：签名参数名为 OpenID，SDK 登录接口参数名为 userId，两者是同一个东西，值必须保持一致。

十、签名计算规则

1. 去掉值为空的参数。

2. 将参数按参数名的字典序升序排列。

3. 将排序后的参数按 Key=Value 格式拼接。

4. 使用 & 连接所有参数，得到签名原文。

5. 使用从 开通服务 文档获取的 AppSecret 对签名原文进行 HMAC-SHA1 签名。

6. 对签名结果进行 Base64 编码，得到最终 Signature。

十一、签名计算示例

例如，参与签名的参数如下：

RequestId=8b8d499bbba1ac28b6da21b4Timestamp=1546315200Nonce=71087795AppKey=your_app_keyOpenID=user_001

排序后的签名原文：

AppKey=your_app_key&Nonce=71087795&OpenID=user_001&RequestId=8b8d499bbba1ac28b6da21b4&Timestamp=1546315200

使用 your_app_secret 作为 AppSecret 对上述原文计算，期望得到的签名为 aSLzd4Ett7RsiLhrYht6Yk9+0qY=，可用于自验签名实现是否正确。

参考以下示例计算签名。客户端示例基于 Java 标准库（Android 端 Base64 请使用 android.util.Base64）；正式上线时签名在业务后台计算，参考服务端示例：

客户端（Java）

import javax.crypto.Mac;import javax.crypto.spec.SecretKeySpec;import java.util.Base64;import java.util.Map;import java.util.TreeMap;public class SignatureDemo { static String generateSignature(String appSecret, String requestId, long timestamp, int nonce, String appKey, String openId) throws Exception { // TreeMap 按参数名的字典序升序排列 Map<String, String> params = new TreeMap<>(); params.put("RequestId", requestId); params.put("Timestamp", String.valueOf(timestamp)); params.put("Nonce", String.valueOf(nonce)); params.put("AppKey", appKey); params.put("OpenID", openId); // 去掉值为空的参数，按 Key=Value 格式拼接，使用 & 连接 StringBuilder source = new StringBuilder(); for (Map.Entry<String, String> entry : params.entrySet()) { if (entry.getValue() == null || entry.getValue().isEmpty()) { continue; } if (source.length() > 0) { source.append("&"); } source.append(entry.getKey()).append("=").append(entry.getValue()); } // 使用 AppSecret 对签名原文进行 HMAC-SHA1 签名 Mac mac = Mac.getInstance("HmacSHA1"); mac.init(new SecretKeySpec(appSecret.getBytes("UTF-8"), "HmacSHA1")); byte[] digest = mac.doFinal(source.toString().getBytes("UTF-8")); // 对签名结果进行 Base64 编码（Android 端请使用 android.util.Base64，flag 传 NO_WRAP） return Base64.getEncoder().encodeToString(digest); } public static void main(String[] args) throws Exception { String signature = generateSignature( "your_app_secret", "8b8d499bbba1ac28b6da21b4", 1546315200L, 71087795, "your_app_key", "user_001" ); System.out.println(signature); // aSLzd4Ett7RsiLhrYht6Yk9+0qY= }}

import base64import hashlibimport hmacdef 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 signaturesignature = 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_64Runtime Version: Python 3.11.1

十三、步骤 3：登录 SDK

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

十四、参数说明

TXIoTEngine.TXIoTUserSignature userSignature = new TXIoTEngine.TXIoTUserSignature();userSignature.requestId = requestId;userSignature.timestamp = timestamp;userSignature.nonce = nonce;userSignature.signature = signature;iotEngine.login(appKey, userId, userSignature);

十五、步骤 4：验证登录结果

登录成功后，调用 getFamilyManager 获取家庭管理实例并拉取家庭列表，以此验证登录态与网络链路是否正常。返回的 familyId 是后续绑定设备、查询设备列表的必备参数，请妥善保存。

TXIoTFamilyManager familyManager = iotEngine.getFamilyManager();if (familyManager == null) { // SDK 未登录或登录态已失效 return;}familyManager.getFamilyList(new TXIoTCallback<List<TXIoTFamilyInfo>>() { @Override public void onSuccess(List<TXIoTFamilyInfo> familyList) { if (familyList.isEmpty()) { // 当前账号下没有家庭，调用 createFamily 创建（见下方示例） return; } // 选择一个家庭，记录 familyId String familyId = familyList.get(0).familyId; } @Override public void onError(TXIoTErrorCode errorCode, String errorMessage) { // 获取家庭列表失败 }});

如果当前账号下没有家庭，可调用 createFamily 创建：

familyManager.createFamily("我的家庭", new TXIoTCallback<TXIoTFamilyInfo>() { @Override public void onSuccess(TXIoTFamilyInfo familyInfo) { // 创建成功，记录 familyId String familyId = familyInfo.familyId; } @Override public void onError(TXIoTErrorCode errorCode, String 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=）自验签名实现是否正确。

20、下一步

完成基础接入后，你还可以继续接入以下能力：

·设备绑定

·远程控制

·家庭管理