iOS IM SDK客户端开发文档

作者: CarrieQ | 来源:发表于2020-12-08 09:37 被阅读0次

消息

消息：IM 交互实体，在 SDK 中对应的类型是 TDMessage。TDMessage 由 TDMessageBody 组成。

// 消息构建部分
#param mark - 消息基类
TDMessage.h
TDMessageBody.h

#param mark - 1V1消息类
TDTextMessageBody.h
TDImageMessageBody.h
TDVoiceMessageBody.h
TDVideoMessageBody.h
TDFileMessageBody.h
TDLocationMessageBody.h

#param mark - 群消息类
TDCreateGroupMessageBody.h
TDGroupAddMessageBody.h
TDGroupRemoveUidsMessageBody.h
TDDeleteGroupMessageBody.h
TDQuitGroupMessageBody.h
TDReplaceOwnerIdMessageBody.h
TDGroupSucessMessageBody.h

#param mark - 特殊消息类
TDCmdMessageBody.h
TDKeyBoardSoundMessageBody.h
TDConferenceMessageBody.h

/** 消息方法调用部分，比如添加代理，移除代理，发送消息等,
同时也包含会话相关的操作，比如创建或获取会话，获取会话列表等*/
TDChatManager.h
// 消息的协议部分，比如监听接收消息的回调方法等
ChatManagerDelegate

构造消息

以下构造消息的示例中，使用到的“初始化消息实例”方法的说明:

/// 初始化消息实例
/// @param body 消息体实例
/// @param fromUid 发送方Uid
/// @param toUid 接收方Uid
/// @param chatType 聊天类型 单聊/群聊
- (id) initMessageWithBody:(TDMessageBody *)body 
                           fromUid:(NSString *)fromUid 
                           toUid:(NSString *)toUid 
                           ChatType:(TDChatType)chatType;

注意: 如果是给群组发消息，那么toUid为群组id

构造文字消息

/// 初始化文本消息体
/// @param aText 文本内容
- (instancetype)initWithText:(NSString *)aText;

// 调用:
TDTextMessageBody *body = [[TDTextMessageBody alloc] initWithText:@"要发送的消息"];
// 获取当前登录的环信id
NSString *from = [[TDWLClient sharedClient] currentUserId];

//生成Message
TDMessage *message = [[TDMessage alloc] initMessageWithBody:body fromUid:from toUid:@"接收者Uid" ChatType:chatType];
// chatType = SingleChat; // 单聊消息
// chatType = GroupChat;// 群聊消息

构造图片消息

/// 初始化文件消息体
/// @param aData 文件data数据
/// @param aDisplayName 文件名
- (instancetype)initWithData:(NSData *)aData
                  displayName:(NSString *)aDisplayName;
                 
// 调用:               
TDImageMessageBody *body = [[TDImageMessageBody alloc] initWithData:aImageData displayName:@"image"];

NSString *from = [[EMClient sharedClient] currentUsername];

//生成Message
TDMessage *message = [[TDMessage alloc] initMessageWithBody:body fromUid:from toUid:@"接收者Uid" ChatType:chatType];
// chatType = SingleChat; // 单聊消息
// chatType = GroupChat;// 群聊消息

构造位置消息

/// 实例化位置消息体
/// @param aLatitude 纬度
/// @param aLongitude 经度
/// @param aAddress 地理位置信息
- (instancetype)initWithLatitude:(double)aLatitude longitude:(double)aLongitude address:(NSString *)aAddress;

//调用:
TDLocationMessageBody *body = [[TDLocationMessageBody alloc] initWithLatitude:39 longitude:116 address:@"地址"]; 

NSString *from = [[EMClient sharedClient] currentUsername];

//生成Message
TDMessage *message = [[TDMessage alloc] initMessageWithBody:body fromUid:from toUid:@"接收者Uid" ChatType:chatType];
// chatType = SingleChat; // 单聊消息
// chatType = GroupChat;// 群聊消息

构造语音消息

/// 初始化文件消息体
/// @param aLocalPath 本地文件路径
/// @param aDisplayName 文件名
- (instancetype)initWithLocalPath:(NSString *)aLocalPath
                       displayName:(NSString *)aDisplayName;

// 调用:
TDVoiceMessageBody *body = [[TDVoiceMessageBody alloc] initWithLocalPath:aPath displayName:@"audio"];
body.duration = duration;

NSString *from = [[EMClient sharedClient] currentUsername];

//生成Message
TDMessage *message = [[TDMessage alloc] initMessageWithBody:body fromUid:from toUid:@"接收者Uid" ChatType:chatType];
// chatType = SingleChat; // 单聊消息
// chatType = GroupChat;// 群聊消息

构造视频消息

/// 初始化文件消息体
/// @param aLocalPath 本地文件路径
/// @param aDisplayName 文件名
- (instancetype)initWithLocalPath:(NSString *)aLocalPath
                       displayName:(NSString *)aDisplayName;

// 调用:
TDVideoMessageBody *body = [[TDVideoMessageBody alloc] initWithLocalPath:[aUrl path] displayName:@"video.mp4"];

NSString *from = [[EMClient sharedClient] currentUsername];

//生成Message
TDMessage *message = [[TDMessage alloc] initMessageWithBody:body fromUid:from toUid:@"接收者Uid" ChatType:chatType];
// chatType = SingleChat; // 单聊消息
// chatType = GroupChat;// 群聊消息

构造文件消息

/// 初始化文件消息体
/// @param aLocalPath 本地文件路径
/// @param aDisplayName 文件名
- (instancetype)initWithLocalPath:(NSString *)aLocalPath
                       displayName:(NSString *)aDisplayName;

// 调用:       
TDFileMessageBody *body = [[TDFileMessageBody alloc] initWithLocalPath:[aUrl path] displayName:@"file"];

NSString *from = [[EMClient sharedClient] currentUsername];

//生成Message
TDMessage *message = [[TDMessage alloc] initMessageWithBody:body fromUid:from toUid:@"接收者Uid" ChatType:chatType];
// chatType = SingleChat; // 单聊消息
// chatType = GroupChat;// 群聊消息

构造透传消息

SDK 提供的一种特殊类型的消息，即 CMD，不会存 db，也不会走 APNS 推送，类似一种指令型的消息。比如您的服务器要通知客户端做某些操作，您可以服务器和客户端提前约定好某个字段，当客户端收到约定好的字段时，执行某种特殊操作。

/// 初始化透传消息
/// @param aText 透传消息text 用户自定义
- (instancetype)initWithCmdText:(NSString *)aText;

// 调用:
TDCmdMessageBody *body = [[TDCmdMessageBody alloc] initWithCmdText:aCMDText];

NSString *from = [[EMClient sharedClient] currentUsername];

//生成Message
TDMessage *message = [[TDMessage alloc] initMessageWithBody:body fromUid:from toUid:@"接收者Uid" ChatType:chatType];
// chatType = SingleChat; // 单聊消息
// chatType = GroupChat;// 群聊消息

会话

// 主要用到的类
// 会话方法调用部分，包含创建或获取会话，获取会话列表等
TDChatManager.h

/**
获取所有会话
@param completion 完成的回调 返回会话数组
 数组中存的为TDSessionModel *类型
*/
- (void) getAllConversations:(LoadAllConversationComplection)completion;

// 调用:
[[TDWLClient sharedClient].chatManager getAllConversations:^(NSArray * _Nonnull contacts, NSError * _Nullable error) {
    if (error) {
        NSLog(@"get AllConversations error = %@",error);
        return;
    }

    // 这里根据你的需要去拿到contacts，进行业务操作
    .......
}];

/**
 删除一个会话
 @param sessionId  会话id  是NSString类型
 */
- (BOOL) deleteConversationWithSessionId:(NSString *)sessionId;

// 调用:
BOOL deleteResult = [[TDWLClient sharedClient].chatManager deleteConversationWithSessionId:@"要删除的会话id"];

if (deleteResult) {
        // 这里已经删除成功，根据开发业务需求去刷新列表或者做其他操作
}

/**
 更新会话内部消息全部已读
 @param sessionId 会话id  NSString类型
 */
- (BOOL) updateRecentSessionReadAllWithSessionId:(NSString *)sessionId;

// 调用:
[[TDWLClient sharedClient].chatManager updateRecentSessionReadAllWithSessionId:@"会话的id"];

聊天

登录成功之后才能进行聊天操作。发消息时，单聊和群聊调用的是统一接口，区别是 chatType不同。

发送消息

/**
 发送消息
 @param message  TDMessage类型
 */
- (void) sendMessage:(TDMessage *)message Completion:(void(^)(BOOL sendSuccess, NSError * _Nullable error))completion;

// 调用:
[[TDWLClient sharedClient].chatManager sendMessage:message Completion:^(BOOL sendSuccess, NSError * _Nullable error) {
        if (error) {
            // 失败
        }else {
            // 成功
        }
}];

接收消息

建议在自己工程的根控制器中注册消息代理，监听接收普通消息的回调方法，用于不在聊天页面时接收消息。

协议 ChatManagerDelegate

代理:
// 设置代理
[TDWLClient sharedClient].chatManager.chatDelegate = self;

// 移除代理
[TDWLClient sharedClient].chatManager.chatDelegate = nil;

接收普通消息会走以下回调：

/// 用于接收消息 传出delegate数据 传出数据为NSArray*类型 数据为TDMessage*类型
- (void) messagesDidReceive:(NSArray *)aMessageArray;

接收透传(cmd)消息会走以下回调:

/// 用于接收CMD消息 传出delegate数据 传出数据为NSArray *类型
- (void) CMDMessageDidReceive:(NSArray *)cmdArray;

接收按键音(KeyBorad)消息会走以下回调:

/// 用于接收按键音消息 传出delegate数据  传出数据为NSArray *类型
- (void) KeyBoradMessageDidReceive:(NSArray *)KeyBoradArray;

接收创建群(CreateGroup)的通知会走以下回调:
ps：此时为收到建群通知，还没加入群聊

/// 用于接收创建群的通知 传出delegate数据 传出数据为NSArray *类型
- (void) CreateGroupMessageDidReceive:(NSArray *)CreateGroupArray;

接收解散群的通知会走以下回调:

/// 用于接收解散群的通知  传出delegate数据 传出数据为NSArray *类型
- (void) DeleteGroupMessageDidReceive:(NSArray *)DeleteGroupArray;

收到消息解析示例：

#pragma mark -----ChatManagerDelegate,CMDMessageDelegate,KeyBoradMessageDelegate,GroupNoticeDelegate-----
// 收到普通消息 看情况做处理
- (void) messagesDidReceive:(NSArray *)aMessageArray {

    NSLog(@"收到普通消息");

    __weak typeof(self) weakself = self;
    dispatch_async(self.msgQueue, ^{
          
        NSMutableArray *receveArray = [[NSMutableArray alloc] init];
        for (int i = 0; i < aMessageArray.count; i++) {
            TDMessage *message = aMessageArray[i];
            if (message.chatType == GroupChat) {
                if ([message.to_uid isEqualToString:self.aSessionModel.sessionId]) {
                    [receveArray addObject:message];
                }
            }else {
                if ([message.from_uid isEqualToString:self.aSessionModel.sessionId]) {
                    [receveArray addObject:message];
                }
            }
        }
        
        NSArray *formated = [weakself _formatMessages:receveArray];
        [weakself.dataArray addObjectsFromArray:formated];
        
        dispatch_async(dispatch_get_main_queue(), ^{
            [weakself.tableView reloadData];
            [weakself _scrollToBottomRow];
        });
    });
}
- (void) CMDMessageDidReceive:(NSArray *)cmdArray {
    NSLog(@"收到了CMD消息:%@",cmdArray);
    //根据业务需求进行解析,做后续操作
    ......
}
- (void) KeyBoradMessageDidReceive:(NSArray *)KeyBoradArray {
    NSLog(@"收到了按键音消息:%@",KeyBoradArray);
    //根据业务需求进行解析,做后续操作
    ......
}
- (void) CreateGroupMessageDidReceive:(NSArray *)CreateGroupArray {
    NSLog(@"收到了建群通知:%@",CreateGroupArray);
    //根据业务需求进行解析,做后续操作
    ......
}
- (void) DeleteGroupMessageDidReceive:(NSArray *)DeleteGroupArray {
    NSLog(@"收到了删除群的通知");
    //根据业务需求进行解析,做后续操作
    ......
}

下载消息中的附件

/**
 * 文件下载方法
 * @param downloadURL 文件链接
 * @param progress 进度
 * @param completion 完成的回调
 */
- (void)downloadFileWithURL:(NSString *) downloadURL progress:(void (^)(NSProgress *downloadProgress))progress Completion:(void(^)(NSString *_Nullable filePath, NSError * _Nullable error))completion;

/// 判断文件是否已经在沙盒中存在
/// @param fileName 文件名
-(BOOL) isFileExist:(NSString *)fileName;

/// 获取文件沙盒路径
/// @param fileName 文件名
- (NSString *) getFileCachesPathWith:(NSString *)fileName;

示例：下载图片消息中的原图:

// 点击图片下载原图
- (void) _imageMessageCellDidSelected:(TDMessageCell *)aCell {
    
    __weak typeof(self) weakself = self;
    
    TDImageMessageBody *body = (TDImageMessageBody*)aCell.model.emModel.body;
    
    // 判断原图是否存在
    BOOL isFileExist = [[TDWLClient sharedClient].chatManager isFileExist:body.imgUrl];
    if (isFileExist) {
        // 获取原图路径
        NSString *imgPath = [[TDWLClient sharedClient].chatManager getFileCachesPathWith:body.imgUrl];
        NSLog(@"imgUrl:%@",body.imgUrl);
        NSLog(@"imgPath:%@",imgPath);
        UIImage *image = [UIImage imageWithContentsOfFile:imgPath];
        if (image) {
            [[TDImageBrowser sharedBrowser] showImages:@[image] fromController:self];
        } else {
            [TDAlertController showErrorAlert:@"获取原图失败T_T"];
        }
    }else {
        // 下载原图
        [self showHudInView:self.view hint:@"下载原图..."];
        [[TDWLClient sharedClient].chatManager downloadFileWithURL:body.imgUrl progress:^(NSProgress * _Nonnull downloadProgress) {
            NSLog(@"进度:%@",downloadProgress);
        } Completion:^(NSString * _Nullable filePath, NSError * _Nullable error) {
            [weakself hideHud];
            if (error) {
                [TDAlertController showErrorAlert:@"下载原图失败T_T"];
            } else {
                NSString *localPath = [[[NSString stringWithFormat:@"%@",filePath] componentsSeparatedByString:@"://"] lastObject];
                UIImage *image = [UIImage imageWithContentsOfFile:localPath];
                if (image) {
                    [[TDImageBrowser sharedBrowser] showImages:@[image] fromController:self];
                } else {
                    [TDAlertController showErrorAlert:@"下载原图失败T_T"];
                }
            }
        }];
    }
}

好友管理

注：通达IM不是好友也可以聊天，不推荐使用通达IM的好友机制。如果你有自己的服务器或好友关系，请自己维护好友关系。

好友管理涉及到的SDK头文件如下:

TDWLUserManager.h

好友管理提供的方法如下：

/**
 添加一个好友
 @param uid 用户uid  NSSting *类型
 */
- (BOOL) addFriendWithUid:(NSString *)uid;

/**
 删除一个好友
 @param uid 用户uid  NSSting *类型
 */
- (BOOL) deleteFriendWithUid:(NSString *)uid;

/**
 获取所有好友列表
 @param completion 完成后的回调
 */
- (void) getAllFriend:(LoadAllFriendCompletion)completion;

/**
 获取所有在黑名单里面的好友
 @param completion 完成后的回调
 */
- (void)getAllBlackListUser:(LoadAllFriendCompletion)completion;

/**
 拉黑某个用户
 @param uid 用户uid
 */
- (BOOL)blackUserWithUid:(NSString *)uid;

/**
 将某个用户从黑名单释放
 @param uid 用户uid
 */
- (BOOL)unBlackUserWithUid:(NSString *)uid;

/**
 判断某个用户是否在黑名单
 @param uid uid 用户uid
 */
- (BOOL)isUserInBlackListWithUid:(NSString *)uid;

注:以上方法调用全部用[TDWLClient sharedClient].contactManager调用
添加好友调用示例:

BOOL addFriendSuccess = [[TDWLClient sharedClient].contactManager addFriendWithUid:@"对方Uid"];

if (addFriendSuccess) {
    // 添加好友成功
}else {
    // 添加好友失败
}

群组管理

群涉及的方法如下:

/**
 建群
 @param uidsArr  uidsArr中为想要添加的群成员uid  注: uidsArr.count >= 2  否则建群失败;
 @param name 群名 NSString *类型
 @param completion 完成的回调
 */
- (void) createGroup:(NSArray *)uidsArr andGroupName:(NSString *)name complet:(void(^)(BOOL isSuccess,NSError *_Nullable error))completion;


/**
 添加群成员
 @param gid 被添加用户的群id;
 @param uids NSArray类型  添加的用户列表
 @param completion 完成的回调
 */
- (void) addGroupMembersWithGId:(NSString *)gid andUidsArray:(NSArray *)uids complet:(void(^)(BOOL isSuccess,NSError *_Nullable error))completion;


/**
 删除群成员
 @param gid 被删除用户的群id;
 @param uids NSArray类型 删除的用户列表。
 返回类型  BOOL
 */
- (void) removeGroupMembersWithGid:(NSString *)gid andUidsArray:(NSArray *)uids complet:(void(^)(BOOL isSuccess,NSError *_Nullable error))completion;


/**
 销毁群
 @param gid 被销毁的群id。
 返回类型  BOOL
 */
- (void) destoryGroup:(NSString *)gid complet:(void(^)(BOOL isSuccess,NSError *_Nullable error))completion;

/**
 退群
 @param gid 群id  NSString类型
 */
- (void) quitGroup:(NSString *)gid complet:(void(^)(BOOL isSuccess,NSError *_Nullable error))completion;

/**
 更换群主
 @param gid 群id NSString类型
 */
- (void) changeGroupOwnerWithGroup:(NSString *)gid targetOwnerId:(NSString *)targetOwnerId complet:(void(^)(BOOL isSuccess,NSError *_Nullable error))completion;


/**
 修改群昵称(本地数据库修改,服务器暂无此功能)
 @param gid 群id NSString类型
 @param newName 新群名 NSString类型
 */
- (BOOL) changeGroupNameWithGroupId:(NSString *)gid newName:(NSString *)newName;


/// 根据群ID查询某条群组的信息
/// @param groupId 群Id NSString类型
- (NSDictionary * _Nullable) getGroupInfoWithGroupId:(NSString *)groupId;

注: 群操作中、建群/添加群成员/删除群成员/解散群/退群/更换群主这几种功能，将会以普通消息的形式插入在聊天消息中。可根据需求选择是否显示此类消息。

音视频通话

适用场景

1对1通话API用于实现1对1语音通话和1对1视频通话，典型场景包括社交交友，远程心理咨询、远程医疗、一对一在线教育、远程视频辅助等。
其API设计思想类似于传统的电话通话，呼叫过程使用了即时通讯的消息机制，所以和即时通讯功能是紧耦合的。

发起实时通话

用户可以调用发起语音或者视频API向在线用户发起实时通话。

主要用到的类:

ITDWLCallManager.h

需要用到的代理方法，建议在开启SDK时，同时添加回调代理

/*!
 *  \~chinese
 *  添加回调代理
 *
 *  @param aDelegate  要添加的代理
 */
- (void)addDelegate:(id<TDWLCallManagerDelegate>)aDelegate;

/*!
 *  \~chinese
 *  移除回调代理
 *
 *  @param aDelegate  要移除的代理
 */
- (void)removeDelegate:(id<TDWLCallManagerDelegate>)aDelegate;

主要方法

/*!
 *  \~chinese
 *  发起实时会话
 *
 *  @param aType                     通话类型
 *  @param aRemoteName      被呼叫用户的IM账号（不能与自己通话）
 *  @param aCompletionBlock 完成的回调
 *
 */
- (void)startCall:(TDWLCallType)aType
       remoteName:(NSString *)aRemoteName
       completion:(void (^)(TDWLCallSession * _Nullable aCallSession,TDWLError * _Nullable error))aCompletionBlock;

注意: TDWLCallType 为枚举类型
TDWLCallTypeAudio = 0,    /*! \~chinese 实时语音 \~english Voice call */
TDWLCallTypeVideo,        /*! \~chinese 实时视频 \~english Video call */

/*!
 *  \~chinese
 *  接收方同意通话请求
 *
 *  @param  aCallId     通话ID
 *
 *  @result 错误信息
 */
- (TDWLError *)answerIncomingCall:(NSString *)aCallId;

/*!
 *  \~chinese
 *  结束通话
 *
 *  @param aCallSession  aCallSession   通话对象
 *  @param aReason       结束原因
 *
 *  @result 错误
 */
- (TDWLError *)endCall:(TDWLCallSession *)aCallSession
                reason:(TDWLCallEndReason)aReason;

扩展

/*!
 *  \~chinese
 *  切换前后摄像头
 *
 */
- (void)updateSipCallWithSwitchCamera;

/*!
 *  \~chinese
 *  设置是否静音
 *
 */
- (void)updateSipCallIsMute:(BOOL)aIsMute;

/*!
 *  \~chinese
 *  设置视频是否可用
 *
 */
- (void)updateSipCallIsEnableVideo:(BOOL)aEnableVideo;

示例:

[[TDWLClient sharedClient].callManager startCall:aType
                                          remoteName:aUsername
                                          completion:^(TDWLCallSession * _Nullable aCallSession, TDWLError * _Nullable error) {
        if (error == nil) {
            // 成功，根据业务需求进行后续处理
        } else {
            // 失败，根据业务需求进行后续处理
        }
}];

外网呼叫

外网呼叫API用于打外网电话使用，场景包括客服、销售等
其API设计思想类似于传统的电话通话。

主要用到的类：

ITDWLSipCallManager.h