iOS RTCLib SDK 开发指南

    开通方式

    音视频服务开通,请参考音视频开通方式说明。

    集成 SDK

    开发环境要求

    操作系统 开发工具 开发平台
    iOS 8.0 及以上 Xcode 8.3 及以上 Mac OSX

    工程配置

    1、 手动添加 RongRTCLib.framework 以及以下库(必须)

    • GPUImage.framework

    2、 添加以下系统依赖库

    • Foundation.framework
    • AudioToolbox.framework
    • VideoToolbox.framework
    • UIKit.framework
    • GLKit.framework
    • CoreFoundation.framework
    • CFNetwork.framework
    • AVFoundation.framework
    • SystemConfiguration.framework
    • Security.framework
    • libz.tbd
    • libbz2.tbd
    • libiconv.tbd
    • libstdc++.tbd

    3、 在工程的 Target 下选择 Build Settings 后,搜索 Enable Bitcode 将此设置为 NO,搜索 Other Linker Flags 在此设置里添加 -ObjC

    4、 权限访问 info.plist,由于音视频中需要用到摄像头和麦克风,请在 info.plist 中添加以下两个 Key 值,以便 iOS 系统提示权限请求时显示出描述内容,否则可能导致运行时出错

    • NSCameraUsageDescription
    • NSMicrophoneUsageDescription

    5、 如果需要用到 GCDAsyncSocket 或 GCDAsyncUdpSocket,请勿将源码导入工程,否则会导致冲突, RongRTCLib.framework 中已经包含,直接用

    CocoaPods 导入 SDK

    1、 Cocoapods 的安装、使用,可以参考IM SDK - 下载与导入SDK文档。

    2、 使用 CocoaPods 导入融云 SDK

    在您的工程根目录下新建一个 Podfile 文件,在文件中输入以下内容。(在此以 2.9.6 版本为例,其中 “MyApp” 为自己工程名)

      target 'MyApp' do
        pod 'RongCloudRTC', '~> 2.9.6'
      end
    

    然后在终端中运行以下命令:

      pod install
    

    完成后,CocoaPods 会在您的工程根目录下生成一个 .xcworkspace 文件。您需要通过此文件打开您的工程,而不是之前的 .xcodeproj

    RongRTC 音视频通话流程

    image

    集成使用

    1、 引入头文件

    #import <RongRTCLib/RongRTCEngine.h>
    

    2、 初始化 RongRTCEngine 实例对象

    // 配置完成后以后可以直接通过 sharedRongRTCEngine 获取该实例对象
    RongRTCEngine *rongRTCEngine = [[RongRTCEngine alloc] initEngine:@"rtccmp.ronghub.com:80"];
    

    3、 设置 RongRTCEngine 引擎实例的代理 ( RongRTCEngineDelegate ),等待状态变化的回调

    加入音视频

    1、RongRTCEngine 配置完成之后 SDK 内部会发起音视频相关长连接建立,长连接建立成功之后会通过下面代理方法进行回调:

    /*!
     @method
     @abstract 系统连接状态回调方法. 初始化成功后, 通过此方法返回RongRTC_ConnectionState_Connected. 如果出现断开连接情况还会返回RongRTC_ConnectionState_Disconnected, 重连成功后返回RongRTC_ConnectionState_Connected, 以正确反应系统连接状态. 如果连接一直不成功会不停的尝试连接直至成功.
     @param state 系统连接状态
     */
    - (void)rongRTCEngine:(RongRTCEngine *)engine onConnectionStateChanged:(RongRTCConnectionState)state;
    

    2、连接成功之后加入音视频会话(也称音视频会议,音视频房间),加入成功才能进行音视频会议,加入方法如下:

    /*!
     @method
     @abstract 加入房间
     @param channel 不同房间的唯一标识
     @param token 通过HTTP的POST方式查询回来的字符串
     @param userID 用户ID
     */
    - (void)joinChannel:(NSString*)channel withKeyToken:(NSString *)token withUserID:(NSString *)userID withUserName:(NSString *)userName;
    

    3、加入成功(或者失败)会通过下面的代理方法进行回调

    /*!
     @method
     @abstract 调用加入房间joinChannel:方法后, 通过此方法返回加入状态
     @param success Yes:加入成功  NO:加入失败
     */
    - (void)rongRTCEngine:(RongRTCEngine *)engine onJoinComplete:(BOOL)success;
    

    4、token 说明:

    a. 获取 Token

    token 即用户令牌,相当于您 APP 上当前用户连接融云的身份凭证。 在您连接融云服务器之前,您需要请求您的 App Server,您的 App Server 通过 Server API 获取 Token 并返回给您的客户端,客户端获取到这个 Token 即可进入下一步连接融云服务器。

    b. 为什么必须在服务器端请求 Token,客户端不提供获取 Token 的接口?

    因为获取 Token 时需要提供 App Key 和 App Secret 。如果在客户端请求 Token,假如您的 App 代码一旦被反编译,则会导致您的 App Key 和 App Secret 泄露。所以,务必在您的服务器端获取 Token。详细描述请参考 Server 开发指南 中的用户服务和获取 Token 方法小节。

    创建视图

    1、用户加入音视频会话成功之后需要创建一个视图来展示自己的摄像头视频,使用 RongRTCEngine 的实例方法进行创建

    /*!
     @method
     @abstract 根据自定义frame和视频的显示类型, 创建本地视频View
     @param frame 自定义本地视频的frame
     @param type 视频显示类型
     */
    - (UIView *)createLocalVideoViewFrame:(CGRect)frame withDisplayType:(RongRTCVideoViewDisplayType)type;
    

    使用示例:

    UIView *localVideoView = [RongRTCEngine sharedRongRTCEngine] createLocalVideoViewFrame:CGRectMake(0, 0, ScreenWidth, ScreenHeight) withDisplayType:RongRTC_VideoViewDisplay_CompleteView]];
    
    [self.view addSubview:localVideoView];
    

    2、 如果有用户加入该会话,SDK 会通过下面的代理方法进行回调,App 收到该回调之后需要创建一个视图用来呈现该用户的视频

    /*!
     @method
     @abstract 自己已经加入房间, 其他用户加入房间后, 自己收到的有用户加入的回调
     @param userId 新加入用户ID
     @param userName 用户名
     @param type 用户类型
     @param avType 音视频类型
     @param screenSharingStatus 屏幕共享打开/关闭
     */
    - (void)rongRTCEngine:(RongRTCEngine *)engine onUserJoined:(NSString *)userId userName:(NSString *)userName  userType:(RongRTCUserType)type audioVideoType:(RongRTCAudioVideoType)avType screenSharingStatus:(RongRTCScreenSharingState)screenSharingStatus;
    

    3、在第二步收到远端用户加入会话的回调之后可以通过下面方法来创建远端用户的视频展示页面,其中的 userId 需要使用上面回调时的 userId

    /*!
     @method
     @abstract 根据userId确定某个远端用户, 用自定义frame和视频的显示类型type, 创建远端视频View
     @param frame 自定义本地视频的frame
     @param userId 远端用户Id
     @param type 视频显示类型
     */
    - (UIView *)createRemoteVideoViewFrame:(CGRect)frame forUser:(NSString *)userId withDisplayType:(RongRTCVideoViewDisplayType)type;
    

    4、进行完第二步和第三步之后则已经正常使用 RTCLib 的音视频功能,如果网络正常,则可以进行音视频会议。

    退出会话

    如果需要退出该音视频会话,调用下面的方法来正常退出,其他端收到远端用户离开的回调时需要做视图移除和 UI 调整相关逻辑处理

    /*!
     @method
     @abstract 离开当前房间
     */
    - (void)leaveChannel;
    

    收到其他端离开会话的回调方法如下:

    /*!
     @method
     @abstract 自己已经加入房间, 其他用户离开后, 通过userId可知是该用户已离开, 据此处理用户离开操作
     @param userId 离开用户ID
     */
    - (void)rongRTCEngine:(RongRTCEngine *)engine onUserLeft:(NSString *)userId;
    

    白板功能

    音视频会议提供白板的功能,App 如果需要使用白板的功能时可以使用下面方法,注:白板功能的发起目前只能在 Web 端进行,其他端只能昨为接收端,另外白板的功能使用 html 的页面进行展现,App 需要获取白板的 URL 地址,然后将 html 的页面加载到 WebView 中即可。

    获取白板地址

    1、App 需要先调用 RongRTCEngine 的 requestWhiteBoardURL 请求白板地址的方法

    /*!
    @method
    @abstract 请求白板页面HTTP URL, 自己已在聊天室中且聊天室中至少还有一个远程用户, 在请求之后会异步通过delegate中的rongRTCEngine: onWhiteBoardURL:方法返回白板页面的URL
    */
    - (void)requestWhiteBoardURL;
    

    此时如果有人已经发起白板直播,会通过下面方法进行回调

    /*!
     @method
     @abstract 自己已经加入房间, 且房间中至少还有一个用户, - (void)requestWhiteBoardURL 请求白板页面的HTTP URL之后的回调
     @param url Web白板连接
     */
    - (void)rongRTCEngine:(RongRTCEngine *)engine onWhiteBoardURL:(NSString *)url;
    

    2、将上面回调方法中的 url 放到一个 WebView 中进行展示即可,此时白板功能创建完成

    3、App 也可以通过下面方法查询是否存在远端用户正在进行白板功能,如果白板存在,则用户可以通过 requestWhiteBoardURL 来获取板板地址。

    /*!
     @method
     @abstract 请求白板页面是否存在, 在请求之后会异步通过delegate中的rongRTCEngine:onWhiteBoardExist:方法返回是否存在
     */
    - (void)requestWhiteBoardExist;
    
    //请求白板地址是否存在的回调
    /*!
     @method
     @abstract 自己已经加入房间, 查询该房间内是否已经创建白板, - (void)requestWhiteBoardExist 之后的回调
     @param isExist YES:存在 NO:不存在
     */
    - (void)rongRTCEngine:(RongRTCEngine *)engine onWhiteBoardExist:(BOOL)isExist;
    

    4、如果远端有人创建白板,SDK 会回调白板创建的方法,同样,如果需要使用白板功能,也需要调用 requestWhiteBoardURL 来获取白板的展示地址,远端有人创建白板的回调方法如下:

    /*!
     @method
     @abstract 自己已经加入房间, 其他用户创建白板后, 自己收到的回调
     @param userId 创建白板的用户ID
     */
    - (void)rongRTCEngine:(RongRTCEngine *)engine onNotifyWhiteBoardCreateBy:(NSString *)userId;