快速入门
本文为您介绍如何使用 NERTC SDK 快速实现音视频通话功能。
前提条件
在开始运行工程之前,需要准备好如下材料:
- 已开通音视频功能的云信应用及其AppKey
- Xcode 10 及以上版本
- iOS 9.0 及以上版本的 iOS 设备
快速跑通Sample Code
注意:在运行前,请联系商务经理开通非安全模式。非安全模式建议只在集成开发阶段使用,正式上线前请改回安全模式。
下载 Sample Code 源码工程,此处以Objective-C工程为例。可以看到 Podfile文件中有如下内容:
# platform :ios, '9.0'
target 'NERTC1to1Sample' do
# Comment the next line if you don't want to use dynamic frameworks
use_frameworks!
pod 'NERtcSDK', 'x.x.x'
end
执行 pod install
完成安装后,双击 NERTC1to1Sample.xcworkspace
通过 Xcode 打开工程。然后打开 AppKey.h
文件,填入您的AppKey,并注释掉 NETSAppDelegate.m
中的 NSAssert
语句。随后运行工程即可。
集成SDK
CocoaPods集成
集成前,请先前往SDK下载页面查看当前最新版本,并查询本地仓库中对应的版本是否为最新版本。若不是最新版本,建议先更新本地仓库,以确保可以集成最新的SDK版本。
pod search NERtcSDK //本地仓库中查询 NERtcSDK 信息
pod repo update //更新本地仓库
pod install //执行安装
至此, NERTC SDK 已经导入完成。
手动导入SDK集成
- 请先前往SDK下载页获取当前最新版本。
- 将解压得到的 NERtcSDK.framework 和 NMCBasicModuleFramework.framework 文件拷贝到工程项目文件夹下。
- 以 Xcode Version 11.5 为例,进入TARGETS > Project Name > General > Frameworks, Libraries, and Embedded Content 菜单,点击 +,再点击 Add Other…,将上述解压得到的SDK文件添加进去。同时,将Embed 属性设置为 Embed & Sign,以使得SDK动态库和应用签名保持一致。
至此, NERTC SDK 已经导入完成。
实现音视频通话
本节主要介绍如何使用 NERTC SDK 实现音视频通话,主要流程如下图所示:
初始化
- 引入头文件
#import <NERtcSDK/NERtcSDK.h>
- 执行初始化
@interface Myapp ()<NERtcEngineDelegateEx>
...
NERtcEngine *coreEngine = [NERtcEngine sharedEngine];
NERtcEngineContext *context = [[NERtcEngineContext alloc] init];
context.engineDelegate = self;
context.appKey = AppKey;
[coreEngine setupEngineWithContext:context];
...
初始化的参数类 NERtcEngineContext 属性说明:
@interface NERtcEngineContext : NSObject
/**
已开通音视频功能的云信应用的AppKey。
*/
@property (nonatomic, copy) NSString *appKey;
/**
log的相关设置,由开发者提供。可选参数。
*/
@property (nonatomic, strong) NERtcLogSetting *logSetting;
/**
通话相关信息的回调接口,由开发者提供。
*/
@property (nonatomic, weak) id<NERtcEngineDelegateEx> engineDelegate;
@end
设置本地视图
启动视频流
- API描述
@protocol INERtcEngine <NSObject>
/**
开启自己的视频。可以在加入频道前和频道后调用。
@param enabled 是否开启
@return 操作返回值,成功则返回 0
*/
- (int)enableLocalVideo:(BOOL)enabled;
@end
- 示例代码
[NERtcEngine.sharedEngine enableLocalVideo:YES];
设置本地视频画布
启动视频流后,可以设置本地视频画布,用来显示本地采集的视频画面。
- API描述
@protocol INERtcEngine <NSObject>
/**
设置本地视频画布
@param canvas 视频窗口,如果需要删除则传 nil
@return 操作返回值,成功则返回 0
*/
- (int)setupLocalVideoCanvas:(NERtcVideoCanvas *)canvas;
@end
- 示例代码
NERtcVideoCanvas *canvas = [[NERtcVideoCanvas alloc] init];
canvas.container = self.localUserView;
[NERtcEngine.sharedEngine setupLocalVideoCanvas:canvas];
设置成功后,即可显示本地视频画面。
加入频道
加入频道前,请确保已完成初始化相关事项。若您的业务中涉及呼叫邀请等机制,可以使用信令。
- API描述
@protocol INERtcEngine <NSObject>
/**
加入频道
@param token 频道token
@param channelName 频道名
@param uId 当前用户的Id
@param completion 操作完成的 block 回调
@return 操作返回值,被执行了则返回 0
*/
- (int)joinChannelWithToken:(NSString *)token
channelName:(nullable NSString *)channelName
myUid:(uint64_t)uId
completion:(NERtcJoinChannelCompletion)completion;
@end
参数说明
- token:频道token。支持传入以下内容:
- 空字符串。该种方式需要先开通非安全模式。安全性不高,建议在产品正式上线前转为安全模式。
- 安全认证签名密钥。安全模式下必需。若未传入正确的token将无法进入频道。建议使用安全模式。
- channelName:频道名称,传入相同频道名称的用户会进入同一个通话频道。
- uId:用户的唯一标识Id,频道内每个用户的 UID 必须是唯一的。
- token:频道token。支持传入以下内容:
示例代码
//加入房间
- (void)joinChannelWithRoomId:(NSString *)roomId
userId:(uint64_t)userId {
__weak typeof(self) weakSelf = self;
[NERtcEngine.sharedEngine joinChannelWithToken:@""
channelName:roomId
myUid:userId
completion:^(NSError * _Nullable error, uint64_t channelId, uint64_t elapesd) {
if (error) {
//加入失败了,弹框之后退出当前页面
} else {
//加入成功
}
}];
}
设置远端视图
视频通话过程中,除了要显示本地的视频画面,通常也要显示参与通话的其他用户的远端视频画面。
监听远端用户进出频道
- API描述
@protocol NERtcEngineDelegate <NSObject>
/**
其他用户加入频道的回调
@param userID 用户的id
@param userName 用户名称
*/
- (void)onNERtcEngineUserDidJoinWithUserID:(uint64_t)userID
userName:(NSString *)userName;
/**
其他用户离开频道的回调
@param userID 用户的id
@param reason 离开的原因
*/
- (void)onNERtcEngineUserDidLeaveWithUserID:(uint64_t)userID
reason:(NERtcSessionLeaveReason)reason;
@end
设置远端视频画布
监听到远端用户加入频道后,可以设置远端视频画布,用来显示远端用户的视频画面。
- API描述
@protocol INERtcEngine <NSObject>
/**
设置远端的视频播放窗口
只能在加入频道后调用
@param userID 用户的id
@param canvas 视频窗口,如果需要删除则传nil
@return 操作返回值,成功则返回 0
*/
- (int)setupRemoteVideoCanvas:(NERtcVideoCanvas *)canvas forUserID:(uint64_t)userID;
@end
- 示例代码
- (void)onNERtcEngineUserDidJoinWithUserID:(uint64_t)userID
userName:(NSString *)userName {
//如果已经setup了一个远端的canvas,则不需要再建立了
...
if (_remoteCanvas != nil) {
return;
}
//建立远端canvas,用来渲染远端画面
NERtcVideoCanvas *canvas = [self setupRemoteCanvasWithUid:userID];
[NERtcEngine.sharedEngine setupRemoteVideoCanvas:canvas
forUserID:userID];
...
}
···
- (void)onNERtcEngineUserDidLeaveWithUserID:(uint64_t)userID
reason:(NERtcSessionLeaveReason)reason {
//如果远端的人离开了,重置远端模型和UI
...
[NERtcEngine.sharedEngine setupRemoteVideoCanvas:nil
forUserID:userID];
...
}
监听远端视频流发布
当频道中的其他用户有视频流发出/关闭时,分别会走入以下回调:
- API描述
@protocol NERtcEngineDelegate <NSObject>
/**
其他用户打开视频的回调
@param userID 用户id
@param profile 用户发送视频的最大分辨率类型
*/
- (void)onNERtcEngineUserVideoDidStartWithUserID:(uint64_t)userID videoProfile:(NERtcVideoProfileType)profile;
/**
其他用户关闭视频的回调
@param userID 用户id
*/
- (void)onNERtcEngineUserVideoDidStop:(uint64_t)userID;
@end
订阅远端视频流
在设置完远端视频画布后,且监听到远端用户有视频发布时,可以订阅远端用户的视频流。
- API描述
@protocol INERtcEngineEx <INERtcEngine>
/**
订阅或取消订阅别人的视频,订阅了才会接收别人的视频数据。
@param subscribe 是否订阅
@param userID 用户的id
@param streamType 订阅的远端视频流类型
@return 操作返回值,成功则返回 0
*/
- (int)subscribeRemoteVideo:(BOOL)subscribe
forUserID:(uint64_t)userID
streamType:(NERtcRemoteVideoStreamType)streamType;
@end
- 示例代码
// 监听到远端用户有视频流发布
- (void)onNERtcEngineUserVideoDidStartWithUserID:(uint64_t)userID
videoProfile:(NERtcVideoProfileType)profile {
//如果已经订阅过远端视频流,则不需要再订阅了
...
if (_remoteCanvas.subscribedVideo) {
return;
}
//订阅远端视频流。
_remoteCanvas.subscribedVideo = YES;
[NERtcEngine.sharedEngine subscribeRemoteVideo:YES
forUserID:userID
streamType:kNERtcRemoteVideoStreamTypeHigh];
...
}
// 监听到远端用户停止视频流发布
- (void)onNERtcEngineUserVideoDidStop:(uint64_t)userID {
if (userID == _remoteCanvas.uid) {
// 收到此回调后,SDK 内部会取消对应的视频流订阅,无需开发者主动取消订阅。
...
_remoteStatLab.hidden = YES;
...
}
}
订阅成功后,即可显示远端的视频画面。
音频流
在 NERtcSDK 中,本地音频的采集发布和远端音频订阅播放是默认启动的,正常情况下无需开发者主动干预。
离开频道
当通话结束,需要离开频道,可以调用以下接口:
- API描述
@protocol INERtcEngine <NSObject>
/**
离开频道
@return 操作返回值,成功则返回 0
*/
- (int)leaveChannel;
@end
- 示例代码
//UI 挂断按钮事件
- (IBAction)onHungupAction:(UIButton *)sender {
[NERtcEngine.sharedEngine leaveChannel];
[self dismiss];
}
执行完 leaveChannel
方法后,SDK 会触发 离开频道回调通知开发者:
- API描述
@protocol NERtcEngineDelegate <NSObject>
/**
离开频道回调
@param result 离开的结果
*/
- (void)onNERtcEngineDidLeaveChannelWithResult:(NERtcError)result;
@end
- 示例代码
- (void)onNERtcEngineDidLeaveChannelWithResult:(NERtcError)result{
// 进行业务数据清理
}
销毁音视频实例
释放当前的 NERtcEngine 实例,建议在 App 确定不再需要使用 NERtcEngine 实例时,通过该接口释放 NERtcEngine 实例的对象资源。
- API描述
@interface NERtcEngine : NSObject <INERtcEngineEx>
/**
释放当前的 NERtcEngine 实例
建议在 App 确定不再需要使用 NERtcEngine 实例时,通过该接口释放 NERtcEngine 实例的对象资源;
1. 该接口的工作方式为同步调用方式,必须在子线程中才能调用,否则会调用失败;如:
dispatch_async(dispatch_get_global_queue(DISPATCH_QUEUE_PRIORITY_DEFAULT, 0), ^{
[NERtcEngine destroyEngine];
});
2. 该接口不得在 SDK 的回调中调用,在接口返回前也不允许调用 SDK 的其他任何接口;
3. 接口调用返回之后,如果需要再次使用 SDK,可以重新调用 sharedEngine 来获取一个新的 NERtcEngine 实例。
*/
+ (int)destroyEngine;
@end
- 示例代码
- (void)dealloc {
[NERtcEngine destroyEngine]; //销毁实例
}


此文档对你是否有帮助

