互动白板 iOS SDK 开发集成指南

SDK 概述

网易云通信 SDK 提供完善的互动白板(实时会话)开发框架,用于在线白板教学和文件传输等实时场景。屏蔽其内部复杂细节,对外提供较为简洁的 API 接口,方便开发者快速集成互动白板功能。SDK 兼容 iOS 7.0+ ,Demo 兼容 iOS 8.0+。

开发准备

互动白板能力作为网易云通信 IM SDK 的 plugin 与 IM SDK 一起发布,并且依赖 IM SDK 的帐号系统。在接入互动白板时,开发者需要参考 IM 即时通讯开发指南 的 以下几个章节:

互动白板主要依赖以下几个类:

实时会话 (白板)

SDK 的实时会话管理类是 NIMRTSManager,提供数据通道 (可靠 TCP 传输通道/语音通道) 以满足实时会话的需求,用于在线白板教学和文件传输等实时场景,其中 TCP 通道可以同时存在多个,语音通道全局只能有一个,并且与音视频通话和互动直播功能互斥。

实时会话流程

- (NSString *)requestRTS:(NSArray<NSString *> *)callees
                services:(NSUInteger)types
                  option:(NIMRTSOption *)option
              completion:(NIMRTSRequestHandler)completion

需要在 callees 中指定被叫用户列表,当前只支持一个被叫。

需要指定服务类型,为 NIMRTSService 的组合,如果要同时发起可靠传输通道和音频通话,使用 NIMRTSServiceReliableTransfer | NIMRTSServiceAudio

可以指定发起会话附带选项 option:

每一通发起请求都会返回会话 ID sessionID,用于后续操作和回调中唯一标识这通请求。

发起结果由 NIMRTSRequestHandler返回:

typedef void(^NIMRTSRequestHandler)(NSError * __nullable error,NSString * __nullable sessionID,UInt64 channelID)

如果发起成功,返回的 error 为 nil。

- (void)onRTSRequest:(NSString *)sessionID
                from:(NSString *)caller
            services:(NSUInteger)types
             message:(NSString *)extendMessage

用户每收到一个实时会话请求都由唯一的 sessionID 标识,用于后续操作和回调中指定这通请求。

extendMessage 是主叫传递过来的附加信息。

- (void)responseRTS:(NSString *)sessionID
             accept:(BOOL)accept
             option:(NIMRTSOption *)option
         completion:(NIMRTSResponseHandler)completion

用于接受或拒绝一通实时会话请求。

在开启了服务器录制功能的 APP 中, 可用 option 中的 disableRecord 选项禁用该通实时会话的录制功能。

响应结果由 NIMRTSResponseHandler 返回:

typedef void(^NIMRTSResponseHandler)(NSError * __nullable error,NSString * __nullable sessionID,UInt64 channelID)

如果响应成功,返回的 error 为 nil。

- (void)onRTSResponse:(NSString *)sessionID
                 from:(NSString *)callee
             accepted:(BOOL)accepted

被叫拒绝接听时,主叫不需要再调用 terminateRTS: 接口。

- (void)onRTSResponsedByOther:(NSString *)sessionID
                     accepted:(BOOL)accepted

对于已经被其他端处理过的实时会话请求,本端不能再做接听、拒绝或挂断操作。

- (void)onRTS:(NSString *)sessionID
      service:(NIMRTSService)type
       status:(NIMRTSStatus)status
        error:(NSError *)error;

如果该实时会话包含多个服务,会有多个回调分别表示各个服务的状态。

- (BOOL)sendRTSData:(NSData *)data
               from:(NSString *)sessionID
                 to:(NSString *)userID
               with:(NIMRTSService)service

发送的数据长度不允许超过 50 KB,推荐不超过 4 KB。

发送数据的周期建议控制在 50 ms 以上,否则可能引起延迟增大等问题。

可以指定发送数据的目标用户 ID,也可以不指定用户表示广播给所有其他用户。

需要指定发送数据的服务通道,现在只支持 TCP 通道。

- (void)onRTSReceive:(NSString *)sessionID
                data:(NSData *)data
                from:(NSString *)user
              withIn:(NIMRTSService)channel
- (void)sendRTSControl:(NSString *)controlInfo
            forSession:(NSString *)sessionID

实时会话控制指令用于方便双方沟通信息,可以选择性使用。

- (void)onRTSControl:(NSString *)controlInfo
                from:(NSString *)user
          forSession:(NSString *)sessionID
- (void)onRTSRecordingInfo:(NIMRTSRecordingInfo *)info
                forSession:(NSString *)sessionID;

包含了一通实时会话的服务器录制文件信息,仅在启用了服务器录制的 APP 中有效。

- (void)terminateRTS:(NSString *)sessionID

被叫在响应请求之前不要调用挂断接口。

- (void)onRTSTerminate:(NSString *)sessionID
                    by:(NSString *)user

音频控制

- (BOOL)setMute:(BOOL)mute

静音后对端将听不到本端的声音。

- (BOOL)setSpeaker:(BOOL)useSpeaker

用于在扬声器和听筒间切换。

服务器录制文件格式

在开启了相关功能后,服务器为实时会话中的每个成员发送的所有数据录制一个单独的文件,其中写入数据的格式根据网易云通信客户端 SDK 版本的不同有所区别:

用户发送的数据包直接被写入文件,不包含任何数据包头

用户发送每一个数据包前增加包头(包长字段和时间戳字段)后再写入录制文件,每一个写入文件的包格式如下:

| 包长 | 时间戳 | 数据 |

包长:4字节,写入文件的整个包的字节长度,包含包长和时间戳字段的长度

时间戳:4字节,从会话开始到服务器收到该数据经历的相对时间,单位是毫秒

数据:客户端调用 SDK 发送的实时会话数据

多人实时会话

与点对点实时会话的流程不同,多人实时会话暂不支持呼叫、推送和挂断等服务,只提供基本的预订、加入和离开会话接口。

多人实时会话也不配套提供语音通话通道,如果需要,可以与多人会议功能组合使用。

多人实时会话服务由 NIMRTSConferenceManager 提供,基本的流程如下:

多人实时会话流程

- (nullable NSError *)reserveConference:(NIMRTSConference *)conference

需要先预订,本人和其他人才能加入多人实时会话。

多人实时会话通过 conferencename 字段做标识;可以通过 conference 的扩展字段 ext 在多人实时会话的创建和加入之间传递额外信息。

同一个会话名称,只在会话使用完以后才可以重复使用,开发者需要保证不会出现重复预订某会话名称而不使用的情况。

该接口的返回值只是表示 SDK 是否接受本次预订的请求,并不表示预订是否成功,预订结果通过以下接口回调:

- (void)onReserveConference:(NIMRTSConference *)conference
                     result:(nullable NSError *)result

如果预订成功, result 为 nil。

- (nullable NSError *)joinConference:(NIMRTSConference *)conference

多人会话的操作对象为 conference

会话通过 name 字段做标识。

需要指定接收数据的 dataHandler 以接收其他用户发来的实时会话数据。

可以通过 serverRecording 开启本次实时会话的服务器的数据录制。该功能需要服务器提前开启才能使用。录制文件的格式与点对点实时会话相同。

加入成功以后,可以通过 channelID 获取当前通话对应的服务器的频道 id,可以通过 serverRecordName 获取服务器录制的文件名称。

该接口的返回值只是表示 SDK 是否接受本次加入的请求,并不表示加入是否成功,加入结果通过以下接口回调:

- (void)onJoinConference:(NIMRTSConference *)conference
                  result:(nullable NSError *)result

如果预订成功, result 为 nil。

- (BOOL)sendRTSData:(NIMRTSConferenceData *)data

其中 data 的:

conference 字段是需要发送数据的实时会话。

data 字段是需要发送的数据。数据长度不允许超过50KB,推荐不超过4KB,发送数据的周期建议控制在50ms以上。

uid 字段是发送的目标,如果需要广播发送,请把该字段留空。

接收数据通过加入会话时 conferencedataHandler 回调。回调的 data 中:

conference 字段是数据来自的会话。

data 字段是接收到数据。

uid 字段是发送者的 id。

- (void)onLeftConference:(NIMRTSConference *)conference
                   error:(NSError *)error

当某些异常情况发生导致会话断开时,SDK 通过该回调通知应用。

- (void)onUserJoined:(NSString *)uid
          conference:(NIMRTSConference *)conference

当有用户加入会话时,已经在会话中的用户会收到该回调。

- (void)onUserLeft:(NSString *)uid
        conference:(NIMRTSConference *)conference
            reason:(NIMRTSConferenceUserLeaveReason)reason

当会话中的用户主动或异常离开时,其他用户会收到该回调。

- (nullable NSError *)leaveConference:(NIMRTSConference *)conference

当所有加入的人都离开了某会话以后,该会话对应的名称才可以被重复预订。

文档转码

文档转码功能可以在 PC 端提交文件转码任务,将 ppt 和 pdf 等文档转码为各种清晰度的图片存储在云端,在移动端获取、下载使用或者删除转码后的文档。

文档转码接口

文档转码相关接口由 NIMDocTranscodingManager 提供:

- (void)fetchMyDocsInfo:(nullable NSString *)lastDocId
                  limit:(NSUInteger)limit
             completion:(nullable NIMDocTranscodingFetchCompleteBlock)completion

在 PC 端提交文档转码任务后,该用户可以通过该接口获取自己的转码文档列表。

其中:

lastDocId 最后一个文档的锚点,不包括此文档。填 nil 会从最新提交的转码文档开始往前查询。

limit 是拉取文档的最大个数,每次拉取的个数不能超过 30。

拉取的结果通过 completion 回调给应用,其声明如下:

typedef void(^NIMDocTranscodingFetchCompleteBlock)(NSError * __nullable error, NSArray<NIMDocTranscodingInfo *> * __nullable infos)

如果拉取成功则 error 为 nil,可以通过 infos 获取拉取到的文档列表。

- (void)inquireDocInfo:(NSString *)docId
            completion:(nullable NIMDocTranscodingInquireCompleteBlock)completion

文档的提交者和其他用户可以通过文档转码任务提交时 SDK 返回的文档 id docId 查询该文档的转码信息。

查询的结果通过 completion 回调给应用,其声明如下:

typedef void(^NIMDocTranscodingInquireCompleteBlock)(NSError * __nullable error, NIMDocTranscodingInfo * __nullable info)

如果查询成功则 error 为 nil,可以通过 info 获取查询到的文档信息。

拉取或查询到的文档信息都在 NIMDocTranscodingInfo 中。

可以查询到转码文档的 id,名称,源文档类型、大小、下载路径,转码目标图像的类型,转码状态等。发起文档转码时的附带信息 ext 是 PC 端提交文档转码任务时传入的额外信息。

如果文档转码失败,可以通过 transcodingFlag 定位具体失败原因。

如果文档转码成功,可以通过指定清晰度、页码等获得如下几个信息:

某清晰度的转码后文件总尺寸

- (UInt64)transcodedTotalSize:(NIMDocTranscodingQuality)quality

返回转码后某清晰度的所有图片的总尺寸,单位是字节;

某清晰度转码后图片的长宽信息

- (CGSize)transcodedImagesSize:(NIMDocTranscodingQuality)quality

返回转码后某清晰度的图片的长宽信息;

转码后某清晰度的文件页码对应的下载 url

- (nullable NSString *)transcodedUrl:(NSUInteger)pageNumber
                           ofQuality:(NIMDocTranscodingQuality)quality

返回的 url 可以直接下载使用。

- (void)deleteDoc:(NSString *)docId
       completion:(nullable NIMDocTranscodingDeleteCompleteBlock)completion

文档转码任务的提交者可以通过该接口删除云端的转码文档,删除的结果通过 completion 回调给应用,其声明如下:

typedef void(^NIMDocTranscodingDeleteCompleteBlock)(NSError * __nullable error)

如果删除成功则 error 为 nil。

API 文档