帮你快速理解、总结文档立即下载
文档中心>物联网开发平台>实时监控>应用端接入

应用端接入

最近更新时间：2026-07-30 12:00:37

我的收藏

本页目录：

本文介绍腾讯云物联网（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];

开始与停止监控

通过 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];

播放设备实时画面

通过 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];

切换视频清晰度

查看监控期间，应用端可动态切换通道画面的清晰度（高清 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];

音频控制

监控过程中可静音远端音频。通过 muteRemoteAudio（单通道）与 muteAllRemoteAudio（全部通道）控制远端音频播放。
方法
说明
mute 为 true 时静音指定通道的远端音频。
一键静音/恢复所有通道的远端音频。
Android
iOS
// 远端音频控制
session.muteRemoteAudio(0, true);
session.muteAllRemoteAudio(false);

// 远端音频控制
[session muteRemoteAudio:0 mute:YES];
[session muteAllRemoteAudio:NO];


状态与回调通知

监控会话通过监听接口（Android：TXIoTMonitorSessionListener，iOS：TXIoTMonitorSessionDelegate）回调状态与错误，回调接口如下：
回调
触发时机
关键参数
onSessionEstablished
监控会话建立成功。
无。
onSessionReconnecting
会话中断，正在重连。
无。
onSessionRecovery
会话重连成功。
无。
onRemoteStreamAvailable
远端音视频流可用状态变化。
channelId, available
onRenderFirstFrame
指定通道首帧已渲染。
channelId
onPlayStateChanged
播放状态变化。
channelId, state（PLAYING / LOADING / STOPPED）
onError
会话或某通道发生错误。
channelId, errCode, errMsg
注意：
会话连接中断时会触发 onSessionReconnecting，SDK 会自动尝试重连；重连成功触发 onSessionRecovery，无需业务层主动重建会话。若重连持续失败，最终会通过 onError 回调错误。

错误处理

监控会话的所有错误均通过 onError 回调错误码与错误信息。常见错误码如下，Android 与 iOS 命名不同，请按所用平台查看：
完整错误码定义见 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 通话。
结束通话或等待通话结束后再发起监控。

下一步：高级功能

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