物联网开发平台 应用端接入

一、前提条件

在调用这篇 API 前，请确保已完成以下准备工作：

·已开通腾讯云物联网相关服务，并在控制台完成实例、应用和设备的准备工作（可参见 开通服务）。

·已在客户端工程中集成 IoT 应用端 SDK。

·已通过业务后台生成登录签名，并调用 TXIoTEngine.login 完成登录。

·目标设备已绑定到当前登录账户名下（请参考 设备绑定 完成设备绑定）。

·使用本地麦克风/摄像头对讲前，确保已在工程中申请并获取相应系统权限。

二、使用建议

·调用顺序：获取监控会话对象 → 注册监听 → 尽早 startRemoteView 设置渲染视图（可在 startSession 之前调用）→ startSession → 会话建立后自动播放画面；结束时调用 stopSession 停止会话。

·提前绑定设备：确保目标设备已绑定到当前账户，否则相关调用会返回权限类错误。

·尽早注册监听：在 startSession 之前完成 addListener，避免错过 onSessionEstablished 等早期回调。

·及时释放：不再需要监控时调用 stopSession 并 removeListener，避免资源泄漏与重复回调。

·统一错误处理：在 onError 中集中处理错误码，结合错误码表给出用户可理解的提示。

三、获取监控会话对象

在 Android、iOS、小程序与鸿蒙上，登录成功后，均可通过 TXIoTEngine 单例实例调用 getMonitorSession() 获取监控会话对象 TXIoTMonitorSession，无需为每个设备单独创建。

注意：警告：

注意：监控会话对象为单例，同一时刻只存在一个监控会话。若已有会话正在运行中（已调用 startSession 且尚未 stopSession），再次调用 startSession 会被直接忽略，不会打断或切换已有会话；无需也不能重复获取多个会话实例。

与视频通话的优先级关系：

实时监控的优先级低于视频通话。若设备当前正处于实时监控拉流状态，应用端对该设备发起视频通话时，视频通话会打断并抢占实时监控的拉流，监控会话会被中断（详见 视频通话）。

四、注册监听回调

监控会话的状态变化与错误均通过监听接口返回。请在调用 startSession 之前完成监听注册，避免错过 onSessionEstablished 等早期回调。

AndroidiOS小程序鸿蒙TXIoTMonitorSessionListener monitorListener = new TXIoTMonitorSessionListener() { @Override public void onSessionEstablished() { // 会话建立成功，可开始播放画面 } // 其他回调…};session.addListener(monitorListener);@interface ViewController () <TXIoTMonitorSessionDelegate>@end@implementation ViewController- (void)onSessionEstablished { // 会话建立成功}- (void)onError:(NSInteger)channelId errorCode:(TXIoTErrorCode)errorCode errorMessage:(NSString *)errorMessage { // 发生错误，统一处理错误码与提示}@end// 注册代理[session addDelegate:self];// 退出时注销// [session removeDelegate:self];const monitorListener = { onSessionEstablished() { // 会话建立成功，可开始播放画面 }, // 其他回调…};session.addListener(monitorListener);import { TXIoTMonitorSessionListener } from '@tencentcloud/liteavsdk_iot'const monitorListener: TXIoTMonitorSessionListener = { onSessionEstablished: () => { // 会话建立成功，可开始播放画面 }, // 其他回调按需实现…}session.addListener(monitorListener)

五、开始与停止监控

通过 startSession 与目标设备建立监控会话，会话建立成功后即可播放实时画面。结束监控时调用 stopSession 释放资源。

AndroidiOS小程序鸿蒙TXIoTMonitorSession session = TXIoTEngine.getInstance(context).getMonitorSession();if (session == null) { // SDK 未登录或登录已过期，请先完成登录 return;}// 监听已在“监听会话状态与错误回调”一节注册，此处直接开始监控// 构造目标设备标识TXIoTDeviceId deviceId = new TXIoTDeviceId();deviceId.productId = "已绑定到当前账户的 productId";deviceId.deviceName = "已绑定到当前账户的 deviceName";// 开始监控session.startSession(deviceId);// 结束时停止监控session.stopSession();TXIoTMonitorSession *session = [[TXIoTEngine getInstance] getMonitorSession];if (session == nil) { // SDK 未登录或登录已过期，请先完成登录 return;}// 监听已在“监听会话状态与错误回调”一节注册，此处直接开始监控// 构造目标设备标识TXIoTDeviceId *deviceId = [[TXIoTDeviceId alloc] init];deviceId.productId = @"已绑定到当前账户的 productId";deviceId.deviceName = @"已绑定到当前账户的 deviceName";// 开始监控[session startSession:deviceId];// 结束时停止监控[session stopSession];const { TXIoTEngine, TXIoTDeviceId } = requirePlugin('tx-iot-sdk');const iotEngine = await TXIoTEngine.getInstance();const session = iotEngine.getMonitorSession();if (session == null) { // SDK 未登录或登录已过期，请先完成登录 return;}// 监听已在“监听会话状态与错误回调”一节注册，此处直接开始监控// 构造目标设备标识const deviceId = new TXIoTDeviceId('已绑定到当前账户的 productId', '已绑定到当前账户的 deviceName');// 开始监控session.startSession(deviceId);// 结束时停止监控session.stopSession();import { getIoTEngineInstance, TXIoTEngine, TXIoTDeviceId } from '@tencentcloud/liteavsdk_iot'const iotEngine: TXIoTEngine = getIoTEngineInstance()const session = iotEngine.getMonitorSession()if (session == null) { // SDK 未登录或登录已过期，请先完成登录 return}// 监听已在“监听会话状态与错误回调”一节注册，此处直接开始监控// 构造目标设备标识const deviceId = new TXIoTDeviceId()deviceId.productId = '已绑定到当前账户的 productId'deviceId.deviceName = '已绑定到当前账户的 deviceName'// 开始监控session.startSession(deviceId)// 结束时停止监控session.stopSession()

六、播放设备实时画面

通过 startRemoteView 为指定通道设置渲染视图并播放实时音视频。你可以在调用 startSession 之前就调用 startRemoteView 设置好渲染视图。

AndroidiOS小程序鸿蒙// remoteView 为布局中的 TXCloudVideoViewTXCloudVideoView remoteView = findViewById(R.id.remote_view);// 开始播放0号通道高清流int channelId = 0; // channelId 表示设备的视频通道，需要与设备端的通道 Id 对齐，单通道设备使用 0TXIoTStreamType streamType = TXIoTStreamType.HD; // 需要查看的视频清晰度，SDK 会将该信息同步给设备端session.startRemoteView(channelId, streamType, remoteView);// 停止播放0号通道session.stopRemoteView(channelId);// remoteView 为布局中的 UIViewUIView *remoteView = self.remoteVideoView;// 开始播放0号通道高清流NSInteger channelId = 0; // channelId 表示设备的视频通道，需要与设备端的通道 Id 对齐，单通道设备使用 0TXIoTStreamType streamType = TXIoTStreamTypeHD; // 需要查看的视频清晰度，SDK 会将该信息同步给设备端// 开始播放高清流[session startRemoteView:channelId streamType:streamType view:remoteView];// 停止播放[session stopRemoteView:0];const { TXIoTStreamType } = requirePlugin('tx-iot-sdk');// WXML 中需放置 <iot-player component-id="remote-player"> 组件const channelId = 0; // channelId 表示设备的视频通道，需要与设备端的通道 Id 对齐，单通道设备使用 0const streamType = TXIoTStreamType.HD; // 需要查看的视频清晰度，SDK 会将该信息同步给设备端// 先把通道绑定到 <iot-player> 组件，再订阅视频流session.setIoTPlayer(channelId, 'remote-player');session.startRemoteView(channelId, streamType);// 停止播放0号通道session.stopRemoteView(channelId);import { TXIoTStreamType } from '@tencentcloud/liteavsdk_iot'// remote-view 为页面中 XComponent 组件的 id（需设置 type: XComponentType.SURFACE、libraryname: 'liteavsdk'）const channelId = 0 // channelId 表示设备的视频通道，需要与设备端的通道 Id 对齐，单通道设备使用 0const streamType = TXIoTStreamType.HD // 需要查看的视频清晰度，SDK 会将该信息同步给设备端session.startRemoteView(channelId, streamType, 'remote-view')// 停止播放0号通道session.stopRemoteView(channelId)

七、切换视频清晰度

查看监控期间，应用端可动态切换通道画面的清晰度（高清 HD / 流畅 SD）。切换通过 switchRemoteStream 完成，无需重新建立会话；应用端切换后，设备端会收到 on_monitor_switch 回调并推送对应清晰度的视频流（设备端处理逻辑见 切换清晰度）。

注意：不同清晰度可能对应不同的计费标准，请确保应用端实际调用的清晰度与用户购买的套餐一致，避免因清晰度与计费套餐不匹配引发计费争议。

八、接口说明

九、调用示例

AndroidiOS小程序鸿蒙// 切换为流畅流session.switchRemoteStream(0, TXIoTMonitorSession.TXIoTStreamType.SD);// 切换为高清流session.switchRemoteStream(0, TXIoTMonitorSession.TXIoTStreamType.HD);// 切换为流畅流[session switchRemoteStream:0 streamType:TXIoTStreamTypeSD];// 切换为高清流[session switchRemoteStream:0 streamType:TXIoTStreamTypeHD];const { TXIoTStreamType } = requirePlugin('tx-iot-sdk');// 切换为流畅流session.switchRemoteStream(0, TXIoTStreamType.SD);// 切换为高清流session.switchRemoteStream(0, TXIoTStreamType.HD);import { TXIoTStreamType } from '@tencentcloud/liteavsdk_iot'// 切换为流畅流session.switchRemoteStream(0, TXIoTStreamType.SD)// 切换为高清流session.switchRemoteStream(0, TXIoTStreamType.HD)

十、音频控制

监控过程中可静音远端音频。通过 muteRemoteAudio（单通道）与 muteAllRemoteAudio（全部通道）控制远端音频播放。

AndroidiOS小程序鸿蒙// 远端音频控制session.muteRemoteAudio(0, true);session.muteAllRemoteAudio(false);// 远端音频控制[session muteRemoteAudio:0 mute:YES];[session muteAllRemoteAudio:NO];// 远端音频控制session.muteRemoteAudio(0, true);session.muteAllRemoteAudio(false);// 远端音频控制session.muteRemoteAudio(0, true)session.muteAllRemoteAudio(false)

十一、状态与回调通知

监控会话通过监听接口（Android 与鸿蒙：TXIoTMonitorSessionListener，iOS：TXIoTMonitorSessionDelegate，小程序：addListener 回调对象）回调状态与错误，回调接口如下：

注意：会话连接中断时会触发 onSessionReconnecting，SDK 会自动尝试重连；重连成功触发 onSessionRecovery，无需业务层主动重建会话。若重连持续失败，最终会通过 onError 回调错误。

十二、错误处理

监控会话的所有错误均通过 onError 回调错误码与错误信息。常见错误码如下，各端命名不同，请按所用平台查看：

完整错误码定义见 TXIoTErrorCode。

AndroidiOS小程序鸿蒙

十三、下一步：高级功能

完成基础接入后，你可以进一步接入以下高级功能，丰富实时监控的使用场景：

·云台控制： 通过 PTZ 指令控制摄像头转动、变焦，调整监控视角。

·录制与截图：本地录制监控画面，并抓取实时截图保存。

·语音对讲 ： 与设备端进行双向语音对讲。