v4.x 迁移指南
QNRTC iOS SDK v4.x 是基于 v3.x 版本开发的全量重构版本，简化了接口调用逻辑，提高了接口的易用性，提供了更友好的事件监听机制。
升级指南
- 由于 QNRTC iOS SDK v4.x 向下不兼容，因此，如果您是老版本用户并希望升级到最新版本以获得更好的用户体验，可参考本文提供的升级指南进行迁版本升级。
- 老版本文档可查看 3.x 及之前版本的相关文档。
改动简介
4.x 版本优化了 SDK 接口调用逻辑，主要改动如下：
优化实时音视频管理方式
在 4.x 版本 SDK 中，我们提供了 QNRTC 和 QNRTCClient 两个类来替代 QNRTCEngine 来进行 SDK 的初始化、Track 的创建以及房间的管理等操作。其中：
- QNRTC 主要负责处理 SDK 的初始化以及本地音视频 Track 的创建采集等房间无关的操作。
- QNRTCClient 主要负责处理房间的加入、离开，音视频 Track 的发布、订阅等房间交互相关的操作。
上述管理方式的改动将影响到 SDK 的主要交互流程，若您需要升级，可以参考当前使用指南下的核心场景使用文档分模块进行更新。
优化音视频 Track 的定义及使用方式
区别于 3.x 版本所有 Track 均使用 QNTrackInfo，在 4.x 版本 SDK 中，我们细化了音视频 Track 的分类，基于不同类型的 Track 提供了不同的控制接口，新版本的 Track 对本地 Track 和远端 Track 做了区分，继承结构定义如下：
注意：本地仅支持创建一路音频 Track，重复创建会返回 nil。
4.x 版本除了对音视频 Track 的结构进行了调整，还将部分 Track 的操作接口从 QNRTCEngine 移到了 Track 上，包括采集、渲染、美颜以及音视频回调监听的设置等。更详细接口定义请参考对应的 API 文档。
优化事件监听接口
v4.x 细化了不同场景下的事件监听，移除了 QNRTCEngineDelegate 回调监听。新版本事件监听定义如下：
- QNRTCClientDelegate: 核心回调接口，定义了房间相关的回调事件，包括房间连接状态、用户加入离开状态等
- QNCameraTrackVideoDataDelegate: 视频数据帧回调接口
- QNMicrophoneAudioTrackDataDelegate: 音频数据帧回调接口
- QNAudioMixerDelegate: 混音相关回调接口，监听混音状态、进度等事件
- QNRemoteTrackDelegate 音视频 Track 信息变化监听接口，监听是否静默
- QNRemoteTrackVideoDataDelegate 视频 Track 信息变化监听接口，监听大小流切换
核心步骤迁移详解
为了更方便您的版本迁移，本部分详细介绍了新老版本针对通话核心步骤的不同处理方式。
初始化
3.x 及之前的版本，初始化操作需要调用 QNRTCEngine 的相关方法，示例代码如下：
QNRTCConfiguration *configuration = [QNRTCConfiguration defaultConfiguration]; // 创建并初始化 SDK 默认配置
QNRTCEngine *engine = [[QNRTCEngine alloc] initWithConfiguration:configuration];// 创建 QNRTCEngine 对象
4.x 版本，初始化操作直接通过 QNRTC 类方法即可实现，示例代码如下：
QNRTCConfiguration *configuration = [QNRTCConfiguration defaultConfiguration]; // 创建并初始化 SDK 默认配置
[QNRTC configRTC:configuration]; // QNRTC 初始化
QNRTCClient *rtcClient = [QNRTC createRTCClient]; // 创建 QNRTCClient
实现差异：
- 4.x 版本 SDK 直接通过 QNRTC.init 即可完成初始化操作。
更详细的 4.x 版本初始化使用方式可参考初始化使用指南
加入房间
3.x 及之前的版本，通过 - (void)joinRoomWithToken:(NSString *)token; 的方式加入房间，示例代码如下：
[rtcEngine joinRoomWithToken:roomToken]; // 加入房间
// 加入房间成功后会触发如下回调
- (void)RTCEngine:(QNRTCEngine *)engine roomStateDidChange:(QNConnectionState)roomState {
if (state == QNConnectionStateConnected) {
// 成功加入房间
}
}
4.x 版本加入房间首先需要创建 QNRTCClient 对象，再通过 QNRTCClient.join 的方式加入房间，示例代码如下：
rtcClient = [QNRTC createRTCClient]; // 创建 QNRTCClient 对象，并设置房间事件监听函数
[rtcClient join:roomToken]; // 加入房间
// 加入房间成功后会触发如下回调
- (void)RTCClient:(QNRTCClient *)client didConnectionStateChanged:(QNConnectionState)state disconnectedInfo:(QNConnectionDisconnectedInfo *)info {
if (state == QNConnectionStateConnected) {
// 成功加入房间
}
}
实现差异：
- 4.x 版本移除了
QNRTCEngine的接口调用，使用 QNRTCClient 进行房间的相关操作 - 4.x 版本房间连接状态监听回调改为 QNRTCClientDelegate.didConnectionStateChanged，监听事件包括加入房间成功、失败以及成功离开房间等
更详细的 4.x 版本房间管理使用方式可参考房间管理使用指南
创建本地 Track
3.x 及之前的版本，通过 QNRTCEngine 创建本地 Track，示例代码如下：
// 创建本地音频 Track
QNTrackInfo *audioInfo = [[QNTrackInfo alloc] initWithSourceType:QNRTCSourceTypeAudio master:YES bitrateBps:self.audioBitrate * 1000];
// 创建本地 Camera 视频 Track
QNTrackInfo *videoInfo = [[QNTrackInfo alloc] initWithSourceType:QNRTCSourceTypeCamera master:YES bitrateBps:self.videoBitrate * 1000 videoEncodeSize:self.videoEncodeSize];
4.x 版本通过 QNRTC 创建本地 Track，示例代码如下：
// 创建本地音频 Track
QNMicrophoneAudioTrack *microphoneAudioTrack = [QNRTC createMicrophoneAudioTrack];
// 创建本地 Camera 视频 Track
QNCameraVideoTrackConfig *cameraVideoTrackConfig = [QNRTC createCameraVideoTrack];
实现差异：
- 4.x 版本移除了
QNRTCEngine创建 Track 的接口，改用 QNRTC 相关接口创建 - 4.x 版本 Track 相关的配置通过 QNCameraVideoTrackConfig 或者 QNMicrophoneAudioTrackConfig 等类似 Config 实现，创建时不传该参数则使用 SDK 提供的默认配置。3.x 版本需要在
QNTrackInfo初始化配置中传入，不传则使用默认配置。
更详细的 4.x 版本音视频采集使用方式可参考音视频采集使用指南
Track 的使用
3.x 及之前的版本对 Track 的大部分操作都由 QNRTCEngine 来实现，这里以部分功能举例，示例代码如下：
// 开启 Camera Track 内置美颜并设置美颜参数
[rtcEngine setBeautifyModeOn:YES]; // 开启美颜
[rtcEngine setBeautify:0.5]; // 设置美颜参数
[rtcEngine setWhiten:0.5]; // 设置美白参数
[rtcEngine setRedden:0.5]; // 设置红润参数
[rtcEngine startCapture]; // 开启 Camera Track 采集
[rtcEngine stopCapture]; // 停止 Camera Track 采集
// 静默本地 Track
[rtcEngine muteAudio:YES]; // 设置音频静默状态
[rtcEngine muteVideo:YES]; // 设置视频静默状态
4.x 版本对 Track 的操作都由对应的 Track 来实现，示例代码如下：
// 开启 Camera Track 内置美颜并设置美颜参数
[cameraVideoTrack setBeautifyModeOn:YES]; // 开启美颜
[cameraVideoTrack setBeautify:0.5]; // 设置美颜参数
[cameraVideoTrack setWhiten:0.5]; // 设置美白参数
[cameraVideoTrack setRedden:0.5]; // 设置红润参数
[cameraVideoTrack startCapture]; // 开启 Camera Track 采集
[cameraVideoTrack stopCapture]; // 停止 Camera Track 采集
// 静默本地 Track
[localAudio updateMute:YES]; // 设置音频静默状态
[localVideo updateMute:YES]; // 设置视频静默状态
[microphoneAudioTrack setVolume:0.8]; // 设置麦克风采集音量
实现差异：
- 4.x 版本将 Track 相关操作接口都移交给对应的 Track 来实现，移除了
QNRTCEngine的相关调用
上述示例代码仅展示了部分功能的示例，更多 Track 相关的接口使用请参考对应的接口文档
发布本地 Track
3.x 及之前的版本发布 Track 通过 QNRTCEngine 来实现，示例代码如下：
// 发布本地 Track
[rtcEngine publishTracks:tracks];
// 发布成功后，会触发 QNRTCEngineDelegate.didPublishLocalTracks 回调
- (void)RTCEngine:(QNRTCEngine *)engine didPublishLocalTracks:(NSArray<QNTrack *> *)tracks {
// 回调发布成功的 Track 列表
}
4.x 版本发布 Track 通过 QNRTCClient 来实现，示例代码如下：
// 发布本地 Track
[rtcClient publish:tracks completeCallback:^(BOOL onPublished, NSError *error) {
if (onPublished) {
// Track 发布成功
} else {
// Track 发布失败
}
}];
实现差异：
- 4.x 版本通过 QNRTCClient.publish 来实现本地 Track 的发布，移除了
QNRTCEngine的相关调用 - 4.x 版本发布结果回调改为了 QNPublishResultCallback，可在 QNRTCClient.publish 中传入，移除了
QNRTCEngineDelegate.didPublishLocalTracks回调
更详细的 4.x 版本发布和订阅使用方式可参考发布和订阅使用指南
订阅远端 Track
3.x 及之前的版本订阅 Track 通过 QNRTCEngine 来实现，示例代码如下：
rtcEngine.autoSubscribe = YES; // 设置是否自动订阅远端 Track，默认开启
[rtcEngine subscribeTracks:tracks]; // 手动订阅场景下，订阅远端 Track
// 订阅成功后，会触发 QNRTCEngineDelegate.didSubscribedRemoteVideoTracks 回调
- (void)RTCEngine:(QNRTCEngine *)engine didSubscribedRemoteVideoTracks:(NSArray<QNRemoteVideoTrack *> *)videoTracks audioTracks:(NSArray<QNRemoteAudioTrack *> *)audioTracks ofUserID:(NSString *)userID {
// 回调订阅成功的 Track 列表
}
4.x 版本订阅 Track 通过 QNRTCClient 来实现，示例代码如下：
rtcClient.autoSubscribe = YES; // 设置是否自动订阅远端 Track，默认开启
[rtcClient subscribe:tracks]; // 手动订阅场景下，订阅远端 Track，支持可变参数
// 订阅成功后，会触发 QNRTCClientDelegate.didSubscribedRemoteVideoTracks 回调
- (void)RTCClient:(QNRTCClient *)client didSubscribedRemoteVideoTracks:(NSArray<QNRemoteVideoTrack *> *)videoTracks audioTracks:(NSArray<QNRemoteAudioTrack *> *)audioTracks ofUserID:(NSString *)userID {
// 回调订阅成功的 Track 列表
}
实现差异：
- 4.x 版本通过 QNRTCClient.subscribe 来实现对 Track 的订阅，移除了
QNRTCEngine的相关调用 - 4.x 版本订阅结果通过 QNRTCClientDelegate.didSubscribedRemoteVideoTracks 回调，移除了
QNRTCEngineDelegate相关的回调
更详细的 4.x 版本发布和订阅使用方式可参考发布和订阅使用指南
CDN 转推
3.x 及之前的版本 CDN 转推通过 QNRTCEngine 来实现，示例代码如下：
// 创建并配置单路转推任务，配置步骤省略
QNForwardStreamConfiguration *forwardConfig = [QNForwardStreamConfiguration alloc] init];
[rtcEngine createForwardJobWithConfiguration:forwardConfig]; // 开始单路转推任务
[rtcEngine stopForwardJobWithJobId:forwardConfig.jobId]; // 停止单路转推任务
// 创建并配置合流转推任务，配置步骤省略
QNMergeStreamConfiguration *mergeConfig = [QNMergeStreamConfiguration alloc] init];
[rtcEngine createMergeStreamJobWithConfiguration:mergeConfig; // 开始合流转推任务
[rtcEngine setMergeStreamLayouts:layouts jobId:mergeConfig.jobId]; // 更新合流布局
[rtcEngine removeMergeStreamLayouts:layouts jobId:mergeConfig.jobId]; // 移除合流布局
[rtcEngine stopMergeStreamWithJobId:mergeConfig.jobId]; // 停止合流转推任务
// 创建成功后会触发 QNRTCEngineDelegate 的相关回调
- (void)RTCEngine:(QNRTCEngine *)engine didCreateForwardJobWithJobId:(NSString *)jobId {
// 回调创建成功的单路转推 job id
}
- (void)RTCEngine:(QNRTCEngine *)engine didCreateMergeStreamWithJobId:(NSString *)jobId {
// 回调创建成功的合流转推 job id
}
4.x 版本 CDN 转推通过 QNRTCClient 来实现，示例代码如下：
// CDN 转推相关回调
- (void)RTCClient:(QNRTCClient *)client didStartLiveStreamingWith:(NSString *)streamID {
// 对应 streamID 的单路/合流转推任务开始转推
}
- (void)RTCClient:(QNRTCClient *)client didStopLiveStreamingWith:(NSString *)streamID {
// 对应 streamID 的单路/合流转推任务已停止转推
}
- (void)RTCClient:(QNRTCClient *)client didTranscodingTracksUpdated:(BOOL)success withStreamID:(NSString *)streamID {
// 合流布局更改时触发此回调
}
- (void)RTCClient:(QNRTCClient *)client didErrorLiveStreamingWith:(NSString *)streamID errorInfo:(QNLiveStreamingErrorInfo *)errorInfo {
// 转推任务出错时触发此回调
}
// 创建并配置单路转推任务，配置步骤省略
QNDirectLiveStreamingConfig *directLiveStreamingConfig = [[QNDirectLiveStreamingConfig alloc] init];
[rtcClient startLiveStreamingWithDirect:directLiveStreamingConfig]; // 开始单路转推任务
[rtcClient stopLiveStreamingWithDirect:directLiveStreamingConfig]; // 停止单路转推任务
// 创建并配置合流转推任务，配置步骤省略
QNTranscodingLiveStreamingConfig *transcodingLiveStreamingConfig = [[QNTranscodingLiveStreamingConfig alloc] init];
[rtcClient startLiveStreamingWithTranscoding:transcodingLiveStreamingConfig]; // 开始合流转推任务
[rtcClient setTranscodingLiveStreamingID:transcodingLiveStreamingConfig.streamID withTracks:transcodingTracks]; // 更新合流布局
[rtcClient removeTranscodingLiveStreamingID:transcodingLiveStreamingConfig.streamID withTracks:transcodingTracks]; // 移除合流布局
[rtcClient stopLiveStreamingWithTranscoding:transcodingLiveStreamingConfig]; // 停止合流转推任务
实现差异：
- 4.x 版本通过 QNDirectLiveStreamingConfig 代替
QNForwardStreamConfiguration实现单路转推的配置；通过 QNTranscodingLiveStreamingConfig 代替QNMergeStreamConfiguration实现合流转推的配置；通过 QNTranscodingLiveStreamingTrack 代替QNMergeStreamLayout实现合流布局的控制 - 4.x 版本通过 QNRTCClientDelegate 代替
QNRTCEngineDelegate相关方法来实现 CDN 转推状态的监听
更详细的 4.x 版本 CDN 转推使用方式可参考 CDN 转推使用指南
离开房间
3.x 及之前的版本离开房间通过 QNRTCEngine 来实现，示例代码如下：
[rtcEngine leaveRoom]; // 离开房间
4.x 版本离开房间通过 QNRTCClient 来实现，示例代码如下：
[rtcClient leave]; // 离开房间
实现差异：
- 4.x 版本通过 QNRTCClient.leave 来实现离开房间的操作，移除了
QNRTCEngine的相关调用
文档反馈
(如有产品使用问题，请 提交工单)
售前 
售后 