NIM SDK 使用指南

SDK 概述

网易云信 SDK (NIM SDK) 为移动应用提供完善的 IM 开发框架,屏蔽其内部复杂细节,对外提供较为简洁的 API 接口,方便第三方应用快速集成 IM 功能。SDK 兼容 iOS 7.0+ ,Demo 兼容 iOS 8.0+ 。

开发准备

NIM SDK 提供两种集成方式:您既可以通过 CocoaPods 自动集成我们的 SDK,也可以通过手动下载 SDK, 然后添加到您的项目中。

我们提供两个下载地址。分别为:

手动添加 SDK

通过 CocoaPods 集成

Podfile 文件中加入

  pod 'NIMSDK'

安装

  pod install

如果无法安装 SDK 最新版本,运行以下命令更新本地的 CocoaPods 仓库列表

  pod repo update

SDK 类说明

NIM SDK 主要提供了如下类(协议)与方法

NIMAVChat 主要提供了如下类(协议)与方法

配置 HTTPS 支持

在默认情况下,SDK 认为用户资料头像,群头像,聊天室类用户头像等信息都是默认托管在云信上,所以 SDK 会针对他们自动开启 HTTPS 支持,开发者不需要任何额外配置。

但如果开发者需要将这些信息都托管在自己的服务器上,需要在 NIMSDKConfig.h 中,将

@property (nonatomic,assign)    BOOL    enabledHttpsForInfo
@property (nonatomic,assign)    BOOL    enabledHttpsForMessage;

设置为 NO,避免 SDK 自动将开发者设置的 HTTP URL 自动转换为 HTTPS URL

因为苹果的 ATS 政策,如果应用中使用了 HTTP 请求,需要将工程配置文件中的 info.plist 文件,NSAppTransportSecurity 条目中适配好 NSExceptionDomains。需要注意的是,2017 年以后,应用中存在 HTTP 请求会有审核被拒的风险。

初始化 SDK

推荐在 APP 启动时尽快注册 NIM SDK。

登录与登出

在使用 SDK 之前,需要对云信的体系流程有基本的认知,推荐开发者首先阅读这里

手动登录

调用

[[[NIMSDK sharedSDK] loginManager] login:account
                                   token:token
                              completion:^(NSError *error) {}];

error为登录错误信息,成功则为nil。不要在登录完成的回调中直接获取 SDK 缓存数据,而应该在 同步完成的回调里获取数据 或者 监听相应的数据变动回调后获取

注:在不特殊说明的情况下,SDK 的所有回调都是在主线程中发起,无论是以 block 还是 delegate 的形式,也推荐开发者仅在主线程调用 SDK 相关接口。

获取登录帐号的云信 id:

NSString *userID = [NIMSDK sharedSDK].loginManager.currentAccount;

SDK 不支持直接添加网易云通信用户,请参考服务端API文档 的 创建网易云通信 ID 章节,在您的应用服务器上使用 Http 接口进行添加。

自动登录

NIM SDK 有两种自动登录的场景:

1.SDK 发起的自动登录:登录完毕后因网络发生切换,断网等情况发生而需要重连,SDK 将自动进行重连重登,无需 APP 干预。

2.APP 发起的自动登录:APP 启动时,如果已保存用户名和密码可以选择调用自动登录接口,并立刻打开主界面。此时 APP 可以在无网络,未登录成功的状态下直接访问用户本地数据。

//APP主动发起自动登录
- (void)autoLogin:(NIMAutoLoginData *)loginData

NIMAutoLoginData 中的 forcedMode 为强制模式开关。非强制模式下的自动登录,服务器将检查当前登录设备是否为上一次登录设备,如果不是,服务器将拒绝这次自动登录(返回 error code 为 417 的错误);强制模式下的自动登录,服务器将不检查当前登录设备是否为上一次登录设备,安全性较低,但较为便捷。

和手动登录不同,自动登录通过委托通知登录状态。 APP 需要实现如下回调 (手动登录也会收到同样的委托回调)

- (void)onLogin:(NIMLoginStep)step

自动登录过程不需要 APP 加以干预,SDK 会在有网络的情况下有策略地不断重试直到登录为止。但下面两种异常情况需要 APP 处理:被踢和特殊的登录错误。

-(void)onKick:(NIMKickReason)code 
   clientType:(NIMLoginClientType)clientType

APP收到被踢回调后需要进行注销并切换到登录界面。

- (void)onAutoLoginFailed:(NSError *)error

大部分自动登录回调错误 APP 并不需要关心,只需注意如下几种情况:

1.用户名密码错误导致自动登录失败,error code 为 302。这种情况一般发生于用户在其他设备上修改了密码。

2.已有一端登录导致自动登录失败,error code 为 417。这种情况发生于非强制登录模式下已有一端在线而当前设备进行自动登录(设置为只允许一端同时登录时),出于安全方面的考虑,云信服务器判定当前端需要重新手动输入用户密码进行登录,故拒绝登录。

3.NIMSDKConfig 设置了 maxAutoLoginRetryTimes 属性,即 App 设定当前 SDK 自动登录失败的重试次数,那么在当前会话中如果登录出错超过预定次数,将抛出 code 为 NIMLocalErrorCodeAutoLoginRetryLimit 的本地错误

一旦发生如上情况,APP 同样需要进行额外处理:注销或重试。

登出

调用

[[[NIMSDK sharedSDK] loginManager] logout:^(NSError *error){}];

应用层登出/注销自己的账号时需要调用 SDK 的登出操作,该操作会通知云信服务器进行 APNS 推送信息的解绑操作,避免用户已登出但推送依然发送到当前设备的情况发生。

考虑到用户体验,登出的超时时间会比其他请求短一些。上层应用不管登出请求是否成功,UI 表现上都应该做出登出行为。

多端登录

当用户在某个客户端登录时,其他没有被踢掉的端会触发回调:

- (void)onMultiLoginClientsChanged;

同时,可以查询当前时间登录的设备列表:

- (NSArray<NIMLoginClient *> *)currentLoginClients;

云信内置踢人策略为:移动端(Android,iOS)互踢,桌面端(PC,Web)互踢,移动端和桌面端共存。

如果当前的互踢策略无法满足业务需求的话,可以联系我们取消内置互踢,根据多端登录的回调和当前的设备列表,判断本设备是否需要被踢出。如果需要踢出,直接调用登出接口并在界面上给出相关提示即可。

登录与用户信息同步

NIM SDK 的登录一共有大约十个步骤,包括正在连接,连接成功,正在登录等。详见 NIMLoginStep 枚举。其中重要的两个步骤为:登录成功 (NIMLoginStepLoginOK) 和 同步成功 (NIMLoginStepSyncOK)。

NIM SDK 在登录后会同步群信息,离线消息,漫游消息,系统通知等数据。

基础消息功能

消息功能概述

SDK 中用户与同一个对象的聊天信息集合,称为一个会话,用 NIMSession 来表示。会话有单人会话,群组会话,聊天室会话等类型。

SDK 中用于表示消息的结构为 NIMMessage,目前提供如下几种消息类型,不同的消息类型对应不同的 MessageObject

消息格式 MessageObject
文本消息 nil
图片消息 NIMImageObject
音频消息 NIMAudioObject
视频消息 NIMVideoObject
地理位置消息 NIMLocationObject
通知消息 NIMNotificationObject
提醒消息 NIMTipObject
自定义消息 NIMCustomObject

消息 NIMMessage 定义了一些额外的状态属性,推荐只在主线程对这些属性进行读写

发送消息

1.构造并发送消息

//构造消息
NIMMessage *message = [[NIMMessage alloc] init];
message.text    = text;

//构造会话
NIMSession *session = [NIMSession session:userId type:NIMSessionTypeP2P];

//发送消息
[[NIMSDK sharedSDK].chatManager sendMessage:message toSession:session error:nil];
//构造消息
NIMImageObject * imageObject = [[NIMImageObject alloc] initWithImage:image];
NIMMessage *message          = [[NIMMessage alloc] init];
message.messageObject        = imageObject;

//构造会话
NIMSession *session = [NIMSession session:userId type:NIMSessionTypeP2P];

//发送消息
[[NIMSDK sharedSDK].chatManager sendMessage:message toSession:session error:nil];
//构造消息
NIMAudioObject *audioObject = [[NIMAudioObject alloc] initWithSourcePath:filePath];
NIMMessage *message        = [[NIMMessage alloc] init];
message.messageObject      = audioObject;

//构造会话
NIMSession *session = [NIMSession session:userId type:NIMSessionTypeP2P];

//发送消息
[[NIMSDK sharedSDK].chatManager sendMessage:message toSession:session error:nil];
//构造消息
NIMVideoObject *videoObject = [[NIMVideoObject alloc] initWithSourcePath:filePath];
NIMMessage *message         = [[NIMMessage alloc] init];
message.messageObject       = videoObject;

//构造会话
NIMSession *session = [NIMSession session:userId type:NIMSessionTypeP2P];

//发送消息
[[NIMSDK sharedSDK].chatManager sendMessage:message toSession:session error:nil];
//构造消息
//其中,latitude为纬度,longitude为经度,title为位置的描述字段
NIMLocationObject *locationObject = [[NIMLocationObject alloc] initWithLatitude:latitude Longitude:longitude address:title];
NIMMessage *message               = [[NIMMessage alloc] init];
message.messageObject             = locationObject;

//构造会话
NIMSession *session = [NIMSession session:userId type:NIMSessionTypeP2P];

//发送消息
[[NIMSDK sharedSDK].chatManager sendMessage:message toSession:session error:nil];
通知类型 NIMNotificationContent
群通知 NIMTeamNotificationContent
网络电话通知 NIMNetCallNotificationContent
聊天室通知 NIMChatroomNotificationContent
未被支持类型通知 NIMUnsupportedNotificationContent

由于系统升级,旧版本的 SDK 可能无法解析新版本数据,所有无法解析的新通知显示为未被支持。

当不需要一些通知时,开发者可以实现 NIMSDKConfig 的委托 delegate,来控制哪些通知需要忽略。

  - (BOOL)shouldIgnoreNotification:(NIMNotificationObject *)notification

当消息将要存储到本地时,会调用此回调,开发者只应该在这个回调里做简单逻辑判断,如果做耗时操作会严重影响存储性能。

不支持从客户端发出通知消息。

//构造消息
NIMTipObject *tipObject = [[NIMTipObject alloc];
NIMMessage *message     = [[NIMMessage alloc] init];
message.messageObject   = tipObject;

//构造会话
NIMSession *session = [NIMSession session:userId type:NIMSessionTypeP2P];

//发送消息
[[NIMSDK sharedSDK].chatManager sendMessage:message toSession:session error:nil];

自定义消息用于 APP 拓展自己的消息类型,实现不同业务逻辑。自定义消息的 MessageObject(NIMCustomObject) 仅有一个 id 字段,SDK 会负责透传这个对象序列化后的结果。NIMCustomAttachment 协议包括一个必须实现的序列化接口和三个与上传相关的可选接口。如果需要在自定义消息中上传文件作为附件的一部分,必须实现这三个上传接口,缺一不可。实现自定义消息参考教程

//构造消息
NIMCustomObject *customObject     = [[NIMCustomObject alloc] init]; 
customObject.attachment           = attachment;
NIMMessage *message               = [[NIMMessage alloc] init];
message.messageObject             = customObject;

//构造会话
NIMSession *session = [NIMSession session:userId type:NIMSessionTypeP2P];

//发送消息
[[NIMSDK sharedSDK].chatManager sendMessage:message toSession:session error:nil];

2.检查调用状态

正常情况这一步可以省略,但刚开始集成 SDK 时,因为上层开发对 API 不熟悉有可能传入一些无效参数,推荐在开发前期务必检查 sendMessage:toSession:error 的返回值和 error 信息,并以此为依据排查问题。

3.处理回调

在调用完发送消息接口后,通常会收到如下回调

- (void)willSendMessage:(NIMMessage *)message

建议开发者仅在收到这个回调后才将消息加入显示用的数据源中。

- (void)sendMessage:(NIMMessage *)message
           progress:(CGFloat)progress

图片,视频等需要上传附件的消息会有比较详细的进度回调,文本消息则没有这个回调。

- (void)sendMessage:(NIMMessage *)message
didCompleteWithError:(NSError *)error

如果消息发送成功 error 为 nil,反之 error 会被填充具体的失败原因。

4.重发

因为网络原因等导致的发送消息失败而需要重发的情况,直接调用

- (BOOL)resendMessage:(NIMMessage *)message
                error:(NSError **)error

此时如果再次调用 sendMessage,则会被 NIM SDK 认作新消息。

5.消息的发送设置

SDK 提供消息发送设置来满足开发者的对服务器自定义需求,这些设置可以在 NIMMessageNIMMessageSetting 属性中找到。

接收消息

- (void)onRecvMessages:(NSArray<NIMMessage *> *)messages

如果收到的是图片,视频等需要下载附件的消息,在回调的处理中还需要调用

(SDK 默认会在第一次收到消息时自动调用)

- (BOOL)fetchMessageAttachment:(NIMMessage *)message
                         error:(NSError **)error

进行附件的下载,附件的下载过程会通过

- (void)fetchMessageAttachment:(NIMMessage *)message
                      progress:(CGFloat)progress
- (void)fetchMessageAttachment:(NIMMessage *)message
          didCompleteWithError:(NSError *)error;

这两个回调返回进度和结果。

消息转发

除了 通知消息 之外,其他类型消息均支持转发给其他会话。

- (BOOL)forwardMessage:(NIMMessage *)message
             toSession:(NIMSession *)session
                 error:(NSError **)error

这里返回的 error 参数只是表示当前这个函数调用是否成功,需要后续的回调才能够判断消息是否已经发送至服务器。后续回调和普通消息发送流程相同。

已读回执

在会话界面中调用发送已读回执的接口并传入最后一条消息,即表示这之前的消息都已读,对端将收到此回执。

发送已读回执

- (void)sendMessageReceipt:(NIMMessageReceipt *)receipt
                completion:(NIMSendMessageReceiptBlock)completion;

接受已读回执

- (void)onRecvMessageReceipt:(NIMMessageReceipt *)receipt;

在发送端 NIMMessageReceipt 需要通过最后一条消息 NIMMessage 进行初始化并进行发送,而接收端可以通过 NIMMessageReceipt 中的 timestamp 来得知发送端当前已读时间戳。此功能仅在 P2P 消息中有效。重复发送和通过无效消息构造的已读回执都将被 SDK 忽略。

消息撤回

在会话时,允许用户撤回一定时间内发送过的消息。

- (void)revokeMessage:(NIMMessage *)message
           completion:(NIMRevokeMessageBlock)completion;

在撤回消息请求调用成功后, SDK 会先回调给上层成功,再自动将本地的这条消息删除。如果需要在撤回后显示一条已撤回的提示 ( 见 Demo 交互 ) ,开发者可以自行构造一条提醒消息并插入本地数据库。

以下情况消息撤回会失败

当有消息撤回发生时,被撤回方 SDK 会触发回调:

- (void)onRecvRevokeMessageNotification:(NIMRevokeMessageNotification *)notification

SDK 在收到消息撤回后,会先从本地数据库中找到对应消息并进行删除,之后通知上层消息已删除。如果需要在撤回后显示一条已撤回的提示 ( 见 Demo 交互 ) ,开发者在这个回调中自行构造一条提醒消息并插入本地数据库。

由于用户业务场景不一致,在撤回后可能在撤回后用一条提醒消息替代,也有可能不做任何提示,而被撤回的消息本身可能是未读的,这样不同的业务逻辑就造成了未读数的不一致。 在 NIMSDKConfig.h 中统一封装了撤回未读配置 接口:

@property (nonatomic,assign) BOOL shouldConsiderRevokedMessageUnreadCount;

默认为 NO。设置成 YES 的情况下,如果被撤回的消息本地还未读,那么当消息发生撤回时,对应会话的未读计数将减 1 以保持最近会话未读数的一致性。 当不做任何提示时,可以设置为 YES,以保持未读计数的一致性。

最近会话

NIMConversationManager 提供最近消息的本地存储管理功能。

最近会话 NIMRecentSession 用于表示会话列表页的数据模型。当用户发送,收取及删除消息时,都会同时去修改最近会话。

当收到或者一条消息时,会自动生成这个消息对应的最近会话。但值得注意的是最近会话和会话并不是一一对应的关系,删除最近会话并不会影响会话。

- (NSArray<NIMRecentSession *> *)allRecentSessions

NIMConversationManager 提供了最近会话的三个回调通知上层:

分别为增加,修改,删除最近会话的回调:

- (void)didAddRecentSession:(NIMRecentSession *)recentSession
           totalUnreadCount:(NSInteger)totalUnreadCount

- (void)didUpdateRecentSession:(NIMRecentSession *)recentSession
              totalUnreadCount:(NSInteger)totalUnreadCount

- (void)didRemoveRecentSession:(NIMRecentSession *)recentSession
              totalUnreadCount:(NSInteger)totalUnreadCount

开发者无法自己添加最近消息,最近消息会在发送或者收到消息的时候自动添加,并触发增加最近会话的回调。

单条消息的删除

- (void)deleteMessage:(NIMMessage *)message;

调用此方法时,如果删除的是最后一条消息,消息所属的最近会话的 lastMessage 属性会自动变成上一条消息(没有则为空消息),同时触发最近消息修改的回调。

单个会话批量消息删除

- (void)deleteAllmessagesInSession:(NIMSession *)session
               removeRecentSession:(BOOL)removeRecentSession

removeRecentSession 标记了最近会话是否会被保留,会话内消息将会标记为已删除。调用此方法会触发最近消息修改的回调,如果选择保留最近会话, lastMessage 属性将会被置成一条空消息。

- (void)deleteRecentSession:(NIMRecentSession *)recentSession

只会删除最近会话,但保留会话内消息。调用时,总未读消息数会减去当前会话的未读数。调用此方法触发最近消息删除的回调。

- (void)deleteAllMessages:(BOOL)removeRecentSessions

removeRecentSession 标记了最近会话是否会被保留。调用这个接口只会触发 - (void)allMessagesDeleted 回调,其他针对单个 recentSession 的回调都不会被调用。

- (NSInteger)allUnreadCount
- (void)markAllMessagesReadInSession:(NIMSession *)session

调用这个方法时,会将所有属于这个会话的消息都置为已读状态。相应的最近会话(如果有的话)未读数会自动置 0 并且触发最近消息修改的回调

最近会话提供本地扩展能力,可以用来开发 @ 以及 置顶 等功能。

开发者可以通过 RecentSessionlocalExt 接口读取扩展。

并通过调用 NIMConversationManager 修改本地扩展信息

- (void)updateRecentLocalExt:(NSDictionary *)ext
               recentSession:(NIMRecentSession *)recentSession

历史记录

云端记录

NIMConversationManager 支持从云信服务器上远程获取之前的聊天历史记录。

- (void)fetchMessageHistory:(NIMSession *)session
                     option:(NIMHistoryMessageSearchOption *)option
                     result:(NIMFetchMessageHistoryBlock)block;

其中 option 为搜索选项,具体选项如下:

本地记录

语音录制及播放

多媒体管理 NIMMediaManager 提供了音频播放、高清语音录制的功能。需要注意的是 NIM SDK 中的语音播放和录制仅支持 aac 和 amr,如果需要更多格式的支持,APP 需要自己实现,但并不推荐。

播放音频

- (BOOL)switchAudioOutputDevice:(NIMAudioOutputDevice)outputDevice
- (BOOL)isPlaying
- (void)play:(NSString *)filepath;

其中 filePath 为音频文件的路径,该操作会触发以下回调:

初始化工作完成,准备开始播放音频的时候会触发

- (void)playAudio:(NSString *)filePath didBeganWithError:(NSError *)error

音频播放结束的时候会触发

- (void)playAudio:(NSString *)filePath didCompletedWithError:(NSError *)error
- (void)stopPlay

该操作会触发回调:

- (void)playAudio:(NSString *)filePath didCompletedWithError:(NSError *)error

录制音频

- (BOOL)isRecording
- (void)recordForDuration:(NSTimeInterval)duration;

其中 duration 限制了录音的最大时长,该操作会触发以下回调:

初始化工作完成,准备开始录制的时候会触发

- (void)recordAudio:(NSString *)filePath didBeganWithError:(NSError *)error

当到录音时长达到设置的最大时长,或者手动停止录音会触发

- (void)recordAudio:(NSString *)filePath didCompletedWithError:(NSError *)error

按照一定的时间间隔触发

- (void)recordAudioProgress:(NSTimeInterval)currentTime

其中 currentTime 为当前的录音时长,触发该回调的时间间隔可以通过以下属性设置,默认为 0.3 秒

@property (nonatomic, assign) NSTimeInterval recordProgressUpdateTimeInterval

- (void)stopRecord

该操作会触发

- (void)recordAudio:(NSString *)filePath didCompletedWithError:(NSError *)error
- (void)cancelRecord

该操作会触发

- (void)recordAudioDidCancelled

获取峰值

- (float)recordPeakPower

获取平均值

- (float)recordAveragePower

来电打断

- (void)playAudioInterruptionBegin

- (void)recordAudioInterruptionBegin
- (void)playAudioInterruptionEnd

- (void)recordAudioInterruptionEnd

群组功能

群组功能概述

群组功能对应的管理类为 NIMTeamManagerNIMTeamManager 提供了普通群 (Normal) 以及高级群 (Advanced) 两种形式的群聊功能。高级群拥有更多的权限操作,两种群聊形式在共有操作上保持了接口一致。推荐 APP 开发时只选择一种群类型进行开发。普通群和高级群在原则上是不能互相转换的,他们的群类型在创建时就已经确定。在 SDK 2.4.0 版本后,高级群可以拥有普通群的全部功能,推荐使用高级群进行开发。

开发手册中所提及的普通群都等同于 Demo 中的讨论组。普通群没有权限操作,适用于快速创建多人会话的场景。每个普通群只有一个管理员。管理员可以对群进行增减员操作,普通成员只能对群进行增员操作。在添加新成员的时候,并不需要经过对方同意。

高级群在权限上有更多的限制,权限分为群主、管理员、以及群成员。

获取群组

NIM SDK 在程序启动时会对本地群信息进行同步,所以只需要调用本地缓存接口获取群就可以了。 SDK 提供了批量获取自己的群接口、以及根据单个群 id 查询的接口。同样 SDK 也提供了远程获取群信息的接口。

本地获取

- (NSArray<NIMTeam *> *)allMyTeams
- (NIMTeam *)teamById:(NSString *)teamId

远程获取

- (void)fetchTeamInfo:(NSString *)teamId
           completion:(NIMTeamFetchInfoHandler)block;

创建群组

- (void)createTeam:(NIMCreateTeamOption *)option
             users:(NSArray<NSString *> *)users
        completion:(NIMTeamCreateHandler)completion

加入群组

用户可以通过被动接受邀请和主动加入两种方式进入群组。

邀请用户入群

- (void)addUsers:(NSArray<NSString *>  *)users
          toTeam:(NSString *)teamId
      postscript:(NSString *)postscript
      completion:(NIMTeamMemberHandler)completion

请求完成后,如果是普通群,被邀请者将直接入群;如果是高级群,云信服务器会下发一条系统消息到目标用户,目标用户可以选择同意或者拒绝入群。

同意群邀请(仅限高级群)

- (void)acceptInviteWithTeam:(NSString*)teamId
                   invitorId:(NSString*)invitorId
                  completion:(NIMTeamHandler)block

拒绝群邀请(仅限高级群)

- (void)rejectInviteWithTeam:(NSString*)teamId
                   invitorId:(NSString*)invitorId
                rejectReason:(NSString*)rejectReason
                  completion:(NIMTeamHandler)block

主动申请入群(仅限高级群)

- (void)applyToTeam:(NSString *)teamId
            message:(NSString *)message
         completion:(NIMTeamApplyHandler)block

请求完成后,云信服务器会下发一条系统消息给群管理员,管理员可以选择通过或者拒绝申请。

通过申请(仅限高级群)

- (void)passApplyToTeam:(NSString *)teamId
                 userId:(NSString *)userId
             completion:(NIMTeamApplyHandler)block

拒绝申请(仅限高级群)

- (void)rejectApplyToTeam:(NSString *)teamId
                   userId:(NSString *)userId
             rejectReason:(NSString *)rejectReason
               completion:(NIMTeamHandler)block

编辑群组资料

普通成员可以修改自己的群资料,管理员以上权限的群成员可以修改他人群资料以及群组信息。包括:

修改群成员昵称

- (void)updateUserNick:(NSString *)userId
               newNick:(NSString *)newNick
                inTeam:(NSString *)teamId
            completion:(NIMTeamHandler)block

修改群名称

- (void)updateTeamName:(NSString *)teamName
                teamId:(NSString *)teamId
            completion:(NIMTeamHandler)block

修改群头像

- (void)updateTeamAvatar:(NSString *)teamAvatarUrl
                  teamId:(NSString *)teamId
              completion:(NIMTeamHandler) block

修改群介绍

- (void)updateTeamIntro:(NSString *)intro
                 teamId:(NSString *)teamId
             completion:(NIMTeamHandler)block

修改群公告

- (void)updateTeamAnnouncement:(NSString *)announcement
                        teamId:(NSString *)teamId
                    completion:(NIMTeamHandler)block

修改群验证方式

- (void)updateTeamJoinMode:(NIMTeamJoinMode)joinMode
                    teamId:(NSString *)teamId
                completion:(NIMTeamHandler)block

修改被邀请人验证方式

- (void)updateTeamBeInviteMode:(NIMTeamBeInviteMode)beInviteMode
                        teamId:(NSString *)teamId
                    completion:(NIMTeamHandler)block;

修改谁可以邀请其他人入群

- (void)updateTeamInviteMode:(NIMTeamInviteMode)inviteMode
                      teamId:(NSString *)teamId
                  completion:(NIMTeamHandler)block

修改谁可以修改群资料

- (void)updateTeamUpdateInfoMode:(NIMTeamUpdateInfoMode)updateInfoMode
                          teamId:(NSString *)teamId
                      completion:(NIMTeamHandler)block

修改谁可以修改群自定义属性

- (void)updateTeamUpdateClientCustomMode:(NIMTeamUpdateClientCustomMode)clientCustomMode
                                  teamId:(NSString *)teamId
                              completion:(NIMTeamHandler)block

管理群组权限

高级群群主可以对群进行权限管理,权限管理包括:

提升管理员

- (void)addManagersToTeam:(NSString *)teamId
                    users:(NSArray<NSString *>  *)users
               completion:(NIMTeamHandler)completion

移除管理员

- (void)removeManagersFromTeam:(NSString *)teamId
                         users:(NSArray<NSString *>  *)users
                    completion:(NIMTeamHandler)completion

转让群

- (void)transferManagerWithTeam:(NSString *)teamId
                     newOwnerId:(NSString *)newOwnerId
                        isLeave:(BOOL)isLeave
                     completion:(NIMTeamHandler)block

群组成员

获取群成员

- (void)fetchTeamMembers:(NSString *)teamId
              completion:(NIMTeamMemberHandler)block

获取到的群成员只有云信服务器托管的群相关数据,需要开发者结合自己管理的用户数据进行界面显示。

修改自己的群成员自定义属性

- (void)updateMyCustomInfo:(NSString *)newInfo
                    inTeam:(NSString *)teamId
                completion:(NIMTeamHandler)block

修改后,其他在线用户自动同步获得修改后的属性。

用户退群

- (void)quitTeam:(NSString *)teamId
      completion:(NIMTeamHandler)block

用户退群成功后,相关会话信息仍然会保留,但不再能接收关于此群的消息。

禁言用户

- (void)updateMuteState:(BOOL)mute
                 userId:(NSString *)userId
                 inTeam:(NSString *)teamId
             completion:(NIMTeamHandler)block

禁言用户后,云信服务器会下发一条提示该用户被禁言的群组通知消息。

踢出用户

- (void)kickUsers:(NSArray<NSString *> *)users
         fromTeam:(NSString *)teamId
       completion:(NIMTeamHandler)completion

被踢出的用户相关会话信息仍然会保留,但不再能接收关于此群的消息。

解散群

- (void)dismissTeam:(NSString*)teamId
         completion:(NIMTeamHandler)block

群解散后,所有群用户关于此群会话会被保留,但是不能能够在此群会话里收发消息。

群组委托

用户的群信息会在以下条件下更新:

这些操作成功后,云信服务器会推送一条群通知,同时触发 SDK 更新群信息的委托事件:

- (void)onTeamUpdated:(NIMTeam *)team

用户的群信息会在以下条件下移除:

这些操作成功后,云信服务器同样会推送一条群通知,同时触发 SDK 更新群信息的委托事件:

- (void)onTeamRemoved:(NIMTeam *)team

用户的群成员信息会在以下条件下更新

这些操作成功后,云信服务器同样会推送一条群通知,同时触发 SDK 更新群信息的委托事件:

- (void)onTeamMemberChanged:(NIMTeam *)team;

群组通知

群组通知是一种消息类型 ( NIMMessageTypeNotification ) ,用户在创建群或者进入群成功之后,任何关于群的变动,云信服务器都会下发一条群通知消息。群通知消息和其他消息一样,可从 NIMConversationManager 提供的消息查询接口中获取。

群组通知内容 NIMTeamNotificationContent 的字段说明:

群消息推送设置

SDK 提供了修改群消息通知的接口,上层可以通过设置这个选项以影响群消息的通知行为。当设置 notify 为 NO 时,群内消息将不会有 APNS 通知。当然上层也可以使用这一属性来决定收到在线消息时的 APP 表现 (是否响铃等)。

- (void)updateNotifyState:(BOOL)notify
                   inTeam:(NSString *)teamId
               completion:(NIMTeamHandler)block;

群禁言

群组允许管理员将部分成员禁言,或者全体禁言。禁言属于高级功能,需要调用云信服务器接口,客户端 SDK 仅提供查询功能。

自定义拓展

SDK 提供了群信息的拓展接口,开发者可以自行定义内容。

- (void)updateTeamCustomInfo:(NSString *)info
                      teamId:(NSString *)teamId
                  completion:(NIMTeamHandler)block

开发者可以通过 NIMTeam 的两个属性读取拓展信息:

聊天室

在集成聊天室之前,推荐开发者首先阅读这里

聊天室功能概述

聊天室功能对应的管理类为 NIMChatroomManagerNIMChatroomManager 提供了聊天室的业务管理,如进入/退出聊天室,获取相关信息以及权限操作等。目前不支持通过 SDK 接口建立/解散聊天室。

聊天室模型特点:

进入聊天室

用户要在聊天室内说话,必须先调用接口进入此聊天室。用户进入聊天室后,不会收到此聊天室的历史消息推送。如有历史消息需求,可以调用消息查询接口进行显示。

- (void)enterChatroom:(NIMChatroomEnterRequest *)request
           completion:(NIMChatroomEnterHandler)completion;

NIMChatroomEnterRequest 中包含了聊天室的基本数据信息,包括需要进入的聊天室 id 和一些供用户自定义的扩展字段,后续当前用户的所有聊天室消息都会带上登录时设置的扩展字段。

扩展包括:

进入聊天室会建立新的连接,不同的聊天室对应着不同的连接,开发者可以监听连接状态做一些业务处理。

- (void)chatroom:(NSString *)roomId connectionStateChanged:(NIMChatroomConnectionState)state;

当进入聊天室后,再发生掉线问题时,SDK 将自动重连,无需开发者再次调用进入房间接口。

在重连时,可能遇到一些特殊网络错误(如聊天室用户被封禁,聊天室状态异常),会触发以下回调,开发者应该在这个回调中退出聊天室界面。

- (void)chatroom:(NSString *)roomId autoLoginFailed:(NSError *)error;

离开聊天室

离开聊天室时,会断开聊天室对应的连接,并不再收到关于此聊天室的任何消息。

- (void)exitChatroom:(NSString *)roomId
          completion:(NIMChatroomHandler)completion;

当用户被踢或者聊天室关闭时,会触发被踢回调,这个时候也会断开聊天室对应的连接:

- (void)chatroom:(NSString *)roomId beKicked:(NIMChatroomKickReason)reason;

聊天室消息收发

聊天室消息收发接口与普通消息收发统一,在发送消息时指定会话类型为聊天室即可。会话 id 即为聊天室 id。

查询聊天室消息历史

进入聊天室时,不会下发关于聊天室的历史消息,可以通过下面的接口查询聊天室消息历史。

- (void)fetchMessageHistory:(NSString *)roomId
                     option:(NIMHistoryMessageSearchOption *)option
                     result:(NIMFetchChatroomHistoryBlock)completion;

获取聊天室信息

此接口可以远程获取聊天室信息,NIM SDK 不会缓存聊天室信息,开发者需要根据业务自己做好缓存。

- (void)fetchChatroomInfo:(NSString *)roomId
               completion:(NIMChatroomInfoHandler)completion;

修改聊天室信息

此接口可以修改聊天室信息,调用完这个接口后,开发者应该自己修改内存缓存的 NIMChatroom 对象。

此接口需要生成 NIMChatroomUpdateRequest 对象来完成请求。

NIMChatroomUpdateRequest中的 needNotify 参数可以设置成功修改信息后云信服务器是否推送一条修改的聊天室消息通知。

NIMChatroomUpdateRequest中的 notifyExt 参数可以设置推送的聊天室消息通知里带的自定义扩展字段。

- (void)updateChatroomInfo:(NIMChatroomUpdateRequest *)request
                completion:(nullable NIMChatroomHandler)completion;

获取聊天室成员

此接口可以远程获取聊天室成员列表,NIM SDK 不会缓存聊天室成员列表,开发者需要根据业务自己做好缓存。 NIM SDK 提供两种方式获取聊天室成员:

修改自己的聊天室成员信息

此接口可以修改聊天室成员信息,调用完这个接口后,开发者应该自己修改内存缓存的 NIMChatroomMember 对象。

此接口需要生成 NIMChatroomMemberInfoUpdateRequest 对象来完成请求。

NIMChatroomMemberInfoUpdateRequest中的 needNotify 参数可以设置成功修改信息后云信服务器是否推送一条修改的聊天室消息通知。

NIMChatroomMemberInfoUpdateRequest中的 notifyExt 参数可以设置推送的聊天室消息通知里带的自定义扩展字段。

- (void)updateMyChatroomMemberInfo:(NIMChatroomMemberInfoUpdateRequest *)request
                        completion:(nullable NIMChatroomHandler)completion;

聊天室权限管理

聊天室可以调整成员的类型,分固定成员和非固定成员两种,固定成员又分为创建者、管理员、普通成员和受限成员四种。禁言用户和拉黑用户都属于受限用户。

踢出成员

创建者或管理员可以将权限比自己低的用户踢出聊天室

- (void)kickMember:(NIMChatroomMemberKickRequest *)request
        completion:(NIMChatroomHandler)completion;

聊天室通知消息

在聊天室中所有的通知都以消息 NIMMessage 的形式展示,内部 messageObjectNIMNotificationTypeChatroom 类型的 NIMNotificationObject。上层开发在收到具体消息需要进行过滤和显示。目前支持的聊天室消息事件定义在 NIMChatroomEventType 枚举里,具体有:

解析聊天室通知消息的详细步骤:

  1. 判断消息是否为通知消息

    • 判断 NIMMessagemessageType 字段是否为 NIMMessageTypeNotification
  2. 判断通知消息是否为聊天室通知

    • NIMMessagemessageObject 字段强类型转换为 NIMNotificationObject
    • 判断转换后的 NIMNotificationObjectnotificationType 字段是否为 NIMNotificationTypeChatroom
  3. 解析聊天室通知的具体内容

    • NIMNotificationObjectcontent 字段强类型转换为 NIMChatroomNotificationContent
    • 查看转换后 NIMChatroomNotificationContent 的具体字段。

聊天室通知内容 NIMChatroomNotificationContent 的字段说明:

聊天室禁言

聊天室允许管理员将部分成员禁言,或者全体禁言。禁言属于高级功能,需要调用云信服务器接口,客户端 SDK 仅提供聊天室禁言的通知功能。

聊天室禁言通知类型被同样定义在了 NIMChatroomEventType 中,分别为

具体解析步骤请参考之前小节 聊天室通知消息

系统通知

除消息通道外,NIM SDK 还提供系统通知这种通道用于消息之外的通知分发。目前有两种类型:内置系统通知和自定义系统通知。

内置

这是由 NIM SDK 预定义的通知类型,目前仅支持几种群操作的通知,如被邀请入群,SDK 负责这些通知的持久化。所有的内置系统通知都是通过

-(void)onReceiveSystemNotification:(NIMSystemNotification *)notification;

下发给 APP。为了保证整个程序逻辑的一致性,APP 需要针对不同类型的系统通知进行相应的操作。

内置系统通知的本地存储:(以下接口分为全量和过滤,过滤接口需要传入过滤器 NIMSystemNotificationFilter,可以按类型选择获取内置系统通知)

自定义

除内置系统通知外,NIM SDK 也额外提供自定义系统给开发者,方便开发者进行业务逻辑的通知。这个通知既可以由客户端发起也可以由开发者服务器发起。

注意:自定义通知和自定义消息的不同之处在于,自定义消息归属于 NIM SDK 消息体系内,适用于会话,由 SDK 存储在消息数据库中,与 NIM SDK 其他内建消息类型一同展现给用户。而自定义通知主要用于第三方的一些事件状态通知,SDK 不存储,也不解析这些通知。SDK 仅仅负责替第三方传递和通知这些事件,起到透传的作用,收到自定义通知后的持久化工作需要由上层开发负责。

发送自定义通知(客户端)

- (void)sendCustomNotification:(NIMCustomSystemNotification *)notification
                     toSession:(NIMSession *)session
                    completion:(NIMSystemNotificationHandler)completion

客户端发起的自定义通知目前支持自定义如下字段:通知内容(推荐使用 json 组织),推送文案(如果没有则不进行 APNS 推送),是否只发给在线用户。最后一个字段的意义在于区分自定义通知的使用场景。选择只发给在线用户,当目标用户不在线时这条通知会被云信服务器丢弃,这种实现比较适合发送即时通知,如正在输入。反之云信服务器会缓存当前通知(有上限),并在目标用户上线后推送给目标用户。

接收自定义通知

- (void)onReceiveCustomSystemNotification:(NIMCustomSystemNotification *)notification;

事件订阅(在线状态)

云信允许用户订阅监听其他用户产生的事件,产生的事件的方式分为两种:

具体在线状态的业务逻辑可以参考 Demo 的 NTESSubscribeManager 实现。

发布自定义事件

- (void)publishEvent:(NIMSubscribeEvent *)event
          completion:(NIMEventSubscribeBlock)completion;

在发布的前,需要自行构造出 NIMSubscribeEvent 对象,必须需要填写的字段为 type , valuetype 目前仅支持 “在线状态事件” , 即 NIMSubscribeSystemEventTypeOnline

订阅事件

- (void)subscribeEvent:(NIMSubscribeRequest *)request
            completion:(NIMEventSubscribeResponseBlock)completion;

取消订阅

- (void)unSubscribeEvent:(NIMSubscribeRequest *)request
              completion:(NIMEventSubscribeResponseBlock)completion;

在调用 订阅/取消订阅 事件接口前,需要先构造 NIMSubscribeRequest 订阅请求对象。

在订阅事件中,订阅请求中必需填写 typeexpirypublishers 字段。publishers 字段最多仅支持 100 个账号 id , 某些场景如在线状态,订阅人数会超过限制,需要多次调用此接口来满足业务,具体详见 Demo 中 NTESSubscribeManager- (void)subscribeOnlineState 方法。

在取消订阅中,订阅请求中必须填写 type 字段,如果不填写 publishers 字段,则取消指定事件的全部订阅关系。

查询订阅事件关系

- (void)querySubscribeEvent:(NIMSubscribeRequest *)request
                 completion:(NIMEventSubscribeQueryBlock)completion;

SDK 提供查询本账号和指定账号存在的订阅关系接口,调用接口前,必须先构造 NIMSubscribeRequest 订阅请求对象。 其中,必须填写 type 字段 和 publishers 字段,查询人数最大支持 100 人。

目前不支持直接查询本账号和所有账号的订阅关系,上层需要维护好需要查询的用户 id, 通过多次调用此接口完成查询。

APNS 推送

前期准备

[[NIMSDK sharedSDK] registerWithAppID:您的APPKEY
                              cerName:您的推送证书名];
- (void)registerAPNs
{
    if ([[UIApplication sharedApplication] respondsToSelector:@selector(registerForRemoteNotifications)])
    {
        UIUserNotificationType types = UIRemoteNotificationTypeBadge | UIRemoteNotificationTypeSound |      UIRemoteNotificationTypeAlert;
        UIUserNotificationSettings *settings = [UIUserNotificationSettings settingsForTypes:types
        categories:nil];
        [[UIApplication sharedApplication] registerUserNotificationSettings:settings];
        [[UIApplication sharedApplication] registerForRemoteNotifications];
    }
    else
    {
        UIRemoteNotificationType types = UIRemoteNotificationTypeAlert | UIRemoteNotificationTypeSound |        UIRemoteNotificationTypeBadge;
        [[UIApplication sharedApplication] registerForRemoteNotificationTypes:types];
    }
}
- (void)application:(UIApplication *)app didRegisterForRemoteNotificationsWithDeviceToken:(NSData *)deviceToken
{
    [[NIMSDK sharedSDK] updateApnsToken:deviceToken];
}

推送时机

开发者在 发送消息自定义系统通知 时,可以指定是否同时进行推送服务。为了节省不必要的流量开销,只有当接收者的应用切换到后台时,云信推送服务才会开启;如果应用在前台,则不会有推送通知。如果有应用前台通信需求,建议开发者使用 自定义系统通知 ,并监听回调:

- (void)onReceiveCustomSystemNotification:(NIMCustomSystemNotification *)notification;

属性设置

NIM SDK 提供全局 APNS 属性设置,用于设置免打扰时间和推送样式,详细内容可以参考 NIMPushNotificationSetting

NIMPushNotificationSetting *setting =  [[[NIMSDK sharedSDK] apnsManager] currentSetting];
[[[NIMSDK sharedSDK] apnsManager] updateApnsSetting:setting
completion:^(NSError *error) {}];

APNS 多端设置 NIMPushNotificationMultiportConfig

- (NIMPushNotificationMultiportConfig *)currentConfig;
- (void)updateConfig:(NIMPushNotificationMultiportConfig *)config
          completion:(NIMApnsHandler)completion;

当桌面端在线时,可以通过设置 shouldPushNotificationWhenPCOnline 字段,控制是否需要发推送给手机端。

消息推送内容设置

用户在发送消息的时候,设置 NIMMessageapnsContent 属性进行消息推送内容设置。如果不设置 apnsContent 属性,将使用云信内置文案。设置 NIMMessageapnsPayload 可以自定义推送参数。

示例代码:

NIMAudioObject *audioObject = [[NIMAudioObject alloc] initWithSourcePath:filePath];
NIMMessage *message = [[NIMMessage alloc] init];
message.messageObject = audioObject;
message.apnsContent = @"发来了一段语音";    //对方收到的推送文案

用户在发送自定义系统通知的时候,设置 NIMCustomSystemNotificationapnsContent 属性来定制消息推送内容,同时可以设置 apnsPayload 来配置推送参数。

消息的成员推送选项

用户在发消息的时候,可以通过配置 NIMMessage 里的 apnsMemberOption 字段实现更为复杂的推送逻辑,目前这个字段只能在群会话中生效。

推送问题排查方案

推送配置后在后台仍收不到通知栏提醒可检查如下步骤:

云信IOS推送收不到问题排查方案

用户资料托管

NIMUserManager 提供了用户帐号资料管理。以下几个接口仅当选择云信托管用户资料时有效,如果开发者不希望云信获取自己的用户数据,则需自行维护用户资料。

NIMUserManager 里,使用 NIMUser 对用户进行封装。其中用户信息为 NIMUserInfo 属性。 具体的信息字段由 NIMUserInfoUpdateTag定义。 NIMUserInfoUpdateTag内置了多个常用信息字段(有格式校验)和一个拓展字段 NIMUserInfoUpdateTagEx 供开发者自行拓展。

获取本地用户资料

- (NIMUser *)userInfo:(NSString *)userId;

用户资料除自己之外,不保证其他用户资料实时更新。其他用户数据更新时机为:

获取服务器用户资料

- (void)fetchUserInfos:(NSArray<NSString *> *)users
            completion:(NIMUserInfoBlock)completion

此接口可以批量从服务器获取用户资料,出于用户体验和流量成本考虑,不建议应用频繁调用此接口。对于用户数据实时性要求不高的页面,应尽量调用读取本地缓存接口。

编辑用户资料

- (void)updateMyUserInfo:(NSDictionary *)values completion:(NIMUserBlock)block;

只允许用户编辑自己的资料。此接口可以一次性编辑多个属性。如昵称,头像等,传入的数据键值对是 {@(NIMUserInfoUpdateTag) : NSString},无效数据将被过滤。一些字段有修改格式校验。具体限制为:

属性名 具体字段 类型限制 格式校验
用户昵称 NIMUserInfoUpdateTagNick NSString
用户头像 NIMUserInfoUpdateTagAvatar NSString
用户签名 NIMUserInfoUpdateTagSign NSString
用户性别 NIMUserInfoUpdateTagGender NIMUserGender 只支持指定枚举
用户邮箱 NIMUserInfoUpdateTagEmail NSString 只支持合法邮箱
用户生日 NIMUserInfoUpdateTagBirth NSString yyyy-MM-dd
用户手机 NIMUserInfoUpdateTagBirth NSString 合法手机号 如13588888888、+(86)-13055555555
拓展字段 NIMUserInfoUpdateTagExt NSString

当修改用户资料成功后,会触发回调:

- (void)onUserInfoChanged:(NIMUser *)user;

用户关系托管

NIMUserManager 提供了用户用户关系管理,以及对用户会话的消息设置。在云信中,不是好友也允许聊天。用户关系如果不托管给云信,开发者需要自己在应用服务器维护。

好友关系

黑名单

云信中,黑名单和好友关系是互相独立的,即修改好友关系不会影响黑名单关系,同时,修改黑名单也不会对好友关系进行操作。

- (NSArray<NIMUser *> *)myBlackList;

黑名单列表有本地缓存,缓存会在手动/自动登录后与服务器自动进行同步更新。接口返回的是 NIMUser 列表。 NIMUser 封装了开发者向云信托管的好友ID,对此好友的会话设置(是否需要消息提醒,是否是拉黑用户等), 以及用户的详细信息 NIMUserInfo (需要将用户信息交给云信托管)。

- (void)addToBlackList:(NSString *)userId
            completion:(NIMUserBlock)block;

拉黑成功后,会同时修改本地缓存,并触发回调:

- (void)onBlackListChanged;
- (void)removeFromBlackBlackList:(NSString *)userId
                      completion:(NIMUserBlock)block;

移除成功后,会同时修改本地缓存,并触发回调:

- (void)onBlackListChanged;
- (BOOL)isUserInBlackList:(NSString *)userId;

此接口是根据本地缓存数据来判断是否拉黑的,在调用时请保证本地缓存是正确的(登录后有正常完成数据同步)。

消息提醒

云信中,可以单独设置是否开启某个用户的消息提醒,即对某个用户静音。静音关系和好友关系是互相独立的,修改好友关系不会影响静音关系,同时,修改静音关系也不会对好友关系进行操作。

- (NSArray<NIMUser *> *)myMuteUserList;

静音列表有本地缓存,缓存会在手动/自动登录后与服务器自动进行同步更新。接口返回的是 NIMUser 列表。 NIMUser 封装了开发者向云信托管的好友ID,对此好友的会话设置(是否需要消息提醒,是否是拉黑用户等), 以及用户的详细信息 NIMUserInfo (需要将用户信息交给云信托管)。

- (void)updateNotifyState:(BOOL)notify
                  forUser:(NSString *)userId
               completion:(NIMUserBlock)block;

设置成功之后,同时更新本地缓存数据。

- (BOOL)notifyForNewMsg:(NSString *)userId;

此接口是根据本地缓存数据来判断是否有消息提醒的,在调用时请保证本地缓存是正确的(登录后有正常完成数据同步)。

当修改用户资料成功后,会触发回调:

- (void)onUserInfoChanged:(NIMUser *)user;

文档转码

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

文档转码接口

- (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 文档