帮你快速理解、总结文档立即下载

应用端接入

最近更新时间:2026-11-03 19:02:36
本文档已由 AI 辅助审校
我的收藏
本文介绍腾讯云物联网(IoT)应用端 SDK 中实时监控(TXIoTMonitorSession)的使用方法。完成 快速接入 并登录 SDK 后,您可以获取监控会话对象,对已绑定的设备发起实时监控,播放设备实时音视频,并监听会话状态与错误回调。您还可以进一步使用云台控制、录制与截图、语音对讲等功能,详情参见 下一步:高级功能。

前提条件

在调用本文 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 等早期回调。
方法
说明
添加监控会话状态与错误监听器,回调接口定义见 监控事件回调(iOS:addDelegate)。
移除监控会话监听器(iOS:removeDelegate)。
Android
iOS
小程序
鸿蒙
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 释放资源。
方法
说明
与目标设备建立监控会话,deviceId(TXIoTDeviceId)为目标设备标识。
停止当前监控会话并释放资源。
Android
iOS
小程序
鸿蒙
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 设置好渲染视图。
方法
说明
在指定视图播放 channelId 通道的实时画面,streamType 为码流类型(取值见「数据结构体」中的 TXIoTStreamType)。channelId 表示设备的视频通道,每个通道对应这个设备的一个摄像头,单通道设备使用 0。
停止播放 channelId 通道的实时画面。
Android
iOS
小程序
鸿蒙
// remoteView 为布局中的 TXCloudVideoView
TXCloudVideoView remoteView = findViewById(R.id.remote_view);

// 开始播放0号通道高清流
int channelId = 0; // channelId 表示设备的视频通道,需要与设备端的通道 Id 对齐,单通道设备使用 0
TXIoTStreamType streamType = TXIoTStreamType.HD; // 需要查看的视频清晰度,SDK 会将该信息同步给设备端
session.startRemoteView(channelId, streamType, remoteView);

// 停止播放0号通道
session.stopRemoteView(channelId);
// remoteView 为布局中的 UIView
UIView *remoteView = self.remoteVideoView;

// 开始播放0号通道高清流
NSInteger channelId = 0; // channelId 表示设备的视频通道,需要与设备端的通道 Id 对齐,单通道设备使用 0
TXIoTStreamType 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 对齐,单通道设备使用 0
const 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 对齐,单通道设备使用 0
const streamType = TXIoTStreamType.HD // 需要查看的视频清晰度,SDK 会将该信息同步给设备端
session.startRemoteView(channelId, streamType, 'remote-view')

// 停止播放0号通道
session.stopRemoteView(channelId)

切换视频清晰度

查看监控期间,应用端可动态切换通道画面的清晰度(高清 HD / 流畅 SD)。切换通过 switchRemoteStream 完成,无需重新建立会话;应用端切换后,设备端会收到 on_monitor_switch 回调并推送对应清晰度的视频流(设备端处理逻辑见 切换清晰度)。
注意:
不同清晰度可能对应不同的计费标准,请确保应用端实际调用的清晰度与用户购买的套餐一致,避免因清晰度与计费套餐不匹配引发计费争议。

接口说明

方法
说明
将 channelId 通道的视频流切换为指定清晰度,streamType 取值见枚举类型 TXIoTStreamType。

调用示例

Android
iOS
小程序
鸿蒙
// 切换为流畅流
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(全部通道)控制远端音频播放。
方法
说明
mute 为 true 时静音指定通道的远端音频。
一键静音/恢复所有通道的远端音频。
Android
iOS
小程序
鸿蒙
// 远端音频控制
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 回调对象)回调状态与错误,回调接口如下:
回调
触发时机
关键参数
onSessionEstablished
监控会话建立成功。
无。
onSessionReconnecting
会话中断,正在重连。
无。
onSessionRecovery
会话重连成功。
无。
onRemoteStreamAvailable
远端音视频流可用状态变化。
channelId, available
onRenderFirstFrame
指定通道首帧已渲染。
channelId
onPlayStateChanged
播放状态变化。
channelId, state(PLAYING / LOADING / STOPPED)
onError
会话或某通道发生错误。
channelId, errCode, errMsg
注意:
会话连接中断时会触发 onSessionReconnecting,SDK 会自动尝试重连;重连成功触发 onSessionRecovery,无需业务层主动重建会话。若重连持续失败,最终会通过 onError 回调错误。

错误处理

监控会话的所有错误均通过 onError 回调错误码与错误信息。常见错误码如下,各端命名不同,请按所用平台查看:
完整错误码定义见 TXIoTErrorCode。
Android
iOS
小程序
鸿蒙
错误码
说明
建议处理方式
ERR_INVALID_PARAMETER
参数不合法
检查 deviceId、channelId、路径等参数是否为空或格式错误。
ERR_INVALID_ACCESS_TOKEN
登录凭证无效
重新登录 SDK 后再发起监控。
ERR_RATE_LIMITED
请求被限频
降低调用频率后重试。
ERR_UNAUTHORIZED_OPERATION
当前用户无权限
确认目标设备已绑定到当前账户(见 前提条件)。
ERR_DEVICE_NOT_EXIST
设备不存在
确认 deviceId 是否正确、设备是否已绑定。
ERR_DEVICE_OFFLINE
设备离线
确认设备在线后重试。
ERR_SPEAKER_START_FAIL
扬声器启动失败
检查音频输出设备是否正常。
ERR_DEVICE_SWITCH_TO_VOIP
设备已切换到 VoIP 通话
结束通话或等待通话结束后再发起监控。
错误码
数值
说明
建议处理方式
TXIoTErrorCodeInvalidParameter
-2
参数不合法。
检查 deviceId、channelId、路径等参数是否为空或格式错误。
TXIoTErrorCodeInvalidAccessToken
-3
登录凭证无效。
重新登录 SDK 后再发起监控。
TXIoTErrorCodeRateLimited
-4
请求被限频。
降低调用频率后重试。
TXIoTErrorCodeUnauthorizedOperation
-5
当前用户无权限。
确认目标设备已绑定到当前账户(见 前提条件)。
TXIoTErrorCodeDeviceNotExist
-1009
设备不存在。
确认 deviceId 是否正确、设备是否已绑定。
TXIoTErrorCodeDeviceOffline
-1010
设备离线。
确认设备在线后重试。
TXIoTErrorCodeSpeakerStartFail
-2006
扬声器启动失败。
检查音频输出设备是否正常。
TXIoTErrorCodeDeviceSwitchToVoIP
-2010
设备已切换到 VoIP 通话。
结束通话或等待通话结束后再发起监控。
错误码
说明
建议处理方式
InvalidParameter
参数不合法
检查 deviceId、channelId、路径等参数是否为空或格式错误。
InvalidAccessToken
登录凭证无效
重新登录 SDK 后再发起监控。
RateLimited
请求被限频
降低调用频率后重试。
UnauthorizedOperation
当前用户无权限
确认目标设备已绑定到当前账户(见 前提条件)。
DeviceNotExist
设备不存在
确认 deviceId 是否正确、设备是否已绑定。
DeviceOffline
设备离线
确认设备在线后重试。
SpeakerStartFail
扬声器启动失败
检查音频输出设备是否正常。
DeviceSwitchToVoIP
设备已切换到 VoIP 通话
结束通话或等待通话结束后再发起监控。
错误码
说明
建议处理方式
ERR_INVALID_PARAMETER
参数不合法
检查 deviceId、channelId、路径等参数是否为空或格式错误。
ERR_INVALID_ACCESS_TOKEN
登录凭证无效
重新登录 SDK 后再发起监控。
ERR_RATE_LIMITED
请求被限频
降低调用频率后重试。
ERR_UNAUTHORIZED_OPERATION
当前用户无权限
确认目标设备已绑定到当前账户(见 前提条件)。
ERR_DEVICE_NOT_EXIST
设备不存在
确认 deviceId 是否正确、设备是否已绑定。
ERR_DEVICE_OFFLINE
设备离线
确认设备在线后重试。
ERR_SPEAKER_START_FAIL
扬声器启动失败
检查音频输出设备是否正常。
ERR_DEVICE_SWITCH_TO_VOIP
设备已切换到 VoIP 通话
结束通话或等待通话结束后再发起监控。

下一步:高级功能

完成基础接入后,您可以进一步接入以下高级功能,丰富实时监控的使用场景:
云台控制: 通过 PTZ 指令控制摄像头转动、变焦,调整监控视角。
录制与截图:本地录制监控画面,并抓取实时截图保存。
语音对讲 : 与设备端进行双向语音对讲。