淘宝开放平台

登录
文档中心 > 客户端(iOS)集成 1.7.0 Beta2

更多功能

更新时间：2016/06/14 访问次数：42784

好友功能

好友功能在1.9.1版本中被添加，接口在IYWContactService协议中，您可以通过[self.imkit.IMCore getContactService]来获得具体对象。

获取好友列表

同步好友列表

SDK内部默认会在每次登陆成功后与服务端同步好友列表，开发者可以通过设置disableAutoRequestAllContacts来禁用这个特性，也可以通过

- (void)requestAllContactsFromServerWithResultBlock:(YWContactsOperationResultBlock)resultBlock;

来主动发起同步请求。

获取本地好友

开发者可以通过

/// 获取不同排序和分组模式的FRC对象
- (YWFetchedResultsController *)fetchedResultsControllerWithListMode:(YWContactListMode)aMode imCore:(YWIMCore *)imCore;

/// 使用关键字搜索用户，使用用户名
// 如果希望搜索好友，needIsFriend置为YES，否则可以置为NO
- (YWFetchedResultsController *)fetchedResultsControllerWithSearchKeyword:(NSString *)aKeyword needIsFriend:(BOOL)needIsFriend imCore:(YWIMCore *)imCore;

来获取本地好友。

好友操作

好友添加

可以通过以下方式来发起添加好友请求：

[[self.imkit.IMCore getContactService] addContact:person withIntroduction:@"" withResultBlock:^(NSError *error, YWAddContactRequestResult result) {
        NSString *title = nil;
        if(result == YWAddContactRequestResultError) {
            title = @"请求发送失败";
        } else if (result == YWAddContactRequestResultSuccess) {
            title = @"好友添加成功";
        } else {
            title = @"请求发送成功，等待对方验证";
        }
        [YWIndicator showTopToastTitle:title content:[NSString stringWithFormat:@"添加%@", person.personId] userInfo:nil withTimeToDisplay:1.5 andClickBlock:nil];
    }];

被添加方可以使用：

- (void)addAddContactRequestBlockV2:(void (^)(YWPerson *person, YWContactAddRequestType type, BOOL isOffline, NSString *message))block
                             forKey:(NSString *)key ofPriority:(YWBlockPriority)priority;

来监听被添加的请求，也可以通过

- (YWConversation *)fetchContactSystemConversation;

来获取好友请求列表。

对于被添加的请求，可以使用：

- (void)responseToAddContact:(BOOL)accept fromPerson:(YWPerson *)person
                 withMessage:(NSString*)message
              andResultBlock:(YWAddContactResultBlock)resultBlock;

这个接口接受或者拒绝。
当被添加方处理后，添加发起方可以通过：

- (void)addAddContactResponseBlockV2:(void (^)(YWPerson *person, YWContactAddResponseType type, BOOL isOffline, NSString *message))block
                              forKey:(NSString *)key ofPriority:(YWBlockPriority)priority;

来获得对方处理的结果。

注：以上add开头添加的block均需要在不使用的时候调用对应的remove方法。

删除好友

开发者可以通过

- (void)removeContact:(YWPerson *)persons withResultBlock:(YWRemoveContactResultBlock)resultBlock;

来删除好友，通过

- (void)addFriendBeRemovedBlock:(void (^)(YWPerson *person, BOOL isOffline))block
                         forKey:(NSString *)key ofPriority:(YWBlockPriority)priority;

来接收被删除的回调。

修改好友的备注名

开发者可以通过

- (void)modifyContact:(YWPerson *)person WithNewNick:(NSString *)nickName andResultBlock:(YWContactOperationResultBlock)resultBlock;

来修改好友的备注名，通过

- (NSString *)contactNickOfPerson:(YWPerson *)aPerson;

来获取好友的备注名。

查询person是否为好友

- (BOOL)ifPersonIsFriend:(YWPerson *)person;

黑名单

  • 开发者可以把一个IM用户拉入黑名单，不再接收该IM用户的消息
  • 黑名单的接口都位于IYWContactService.h，开发者可以从YWIMCore对象中获取该Service

获取黑名单列表

__weak typeof(self) weakSelf = self;
[[self.imkit.IMCore getContactService] fetchBlackListWithCompletionBlock:^(NSError *error, NSArray *blackList) {
    if (error == nil || error.code == 0) {
        weakSelf.blackList = [blackList mutableCopy];
        [weakSelf.tableView reloadData];
    }
}];

判断是否在黑名单

/// 判断某个person是否在黑名单中
- (BOOL)isPersonInBlackList:(YWPerson *)person;

拉入黑名单

YWPerson *person = [[YWPerson alloc] initWithPersonId:personId appKey:[YWAPI sharedInstance].appKey];
[[weakSelf.imkit.IMCore getContactService] addPersonToBlackList:person withResultBlock:^(NSError *error, YWPerson *person) {
    if (error == nil || error.code == 0) {
        [weakSelf updateBlackList];
    }
}];

移出黑名单

__weak typeof(self) weakSelf = self;
[[_imkit.IMCore getContactService] removePersonFromBlackList:person withResultBlock:^(NSError *error, YWPerson *person) {
    BOOL isSuccess = (error == nil || error.code == 0);
	 // 提示结果
    if(isSuccess) {
        [weakSelf updateBlackList];
    }
}];

在线状态

在线状态相关接口位于IYWContactService.h

启用在线状态功能

默认不启用在线状态功能，即IM将所有的用户都显示为在线。

如果开发者需要启用在线状态，请使用如下接口：

/// 是否启用在线状态功能
/// 默认为NO，即所有用户均显示为在线
@property (nonatomic, assign) BOOL enableContactOnlineStatus;

异步更新在线状态

开发者可以通过如下接口异步更新在线状态：

/// 获取缓存中的在线状态，如果有缓存过期，则会发起网络请求，请求返回后回调block，且只回调一次
//  @param persons 需要获取在线状态的person数组
//  @param expire  过期时间，距离上次更新时间超过此参数的缓存将被认为是过期，从而触发网络请求
//  @param block   回调
- (void)updateOnlineStatusForPersons:(NSArray *)persons withExpire:(NSTimeInterval)expire andOnlineStatusUpdateBlock:(YWOnlineStatusDidUpdateBlock)block;

获取本地在线状态

当开发者异步更新在线状态后，开发者可以通过如下接口获取本地保存的在线状态：

/// 获取缓存中的在线状态，不会发起网络请求,
- (NSDictionary *)getOnlineStatusForPersons:(NSArray *)persons;

监听在线状态变更

注意：目前移动端IMSDK不支持实时从服务器同步在线状态，这里的监听在线状态变更是指监听本地在线状态变更，以保持本地显示的一致性。

/// 添加对某个person在线状态改变的监听
- (void)addPersonOnlineStatusChanged:(NSArray *)persons withBlock:(YWOnlineStatusChangeBlock)block forKey:(NSString *)aKey ofPriority:(YWBlockPriority)aPriority;
/// 移除对某个person在线状态改变的监听
- (void)removePersonOnlineStatusChanged:(YWPerson *)person forKey:(NSString *)aKey;
/// 移除某个key对应的所有block
- (void)removePersonOnlineStatusChangedBlockForKey:(NSString *)aKey;

输入状态

输入状态开关

如果开发者集成的是YWIMKit层，那么聊天页面标题栏默认开启输入状态显示，开发者可以通过IYWConversationService中的

- (void)setDisableInputStatus:(BOOL)disableInputStatus;

来关闭这一功能，注意，当YWConversationViewController的disableTitleAutoConfig为YES时，不会自动显示输入状态。

发送输入状态

在该功能未被关闭的情况下，聊天界面会自动发送输入状态，如果需要开发者可以通过YWIMCore层中的IYWConversationService中

/**
 *  发送输入状态，该状态只起到通知的作用，不做存储
 *  @param inputStatu 输入状态
 *  注意，当 disableContactInputStatus 为 YES 时无效
 */
- (void)sendUserInputStatus:(YWConversationInputStatus)inputStatus forConversation:(YWConversation *)conversation;

来发送输入状态。

监听输入状态

开发者可以通过IYWConversationService中的

/// 设置收到输入状态变化的回调
- (void)addConversationInputStatusChangeBlock:(YWConversationInputStatusChangeBlock)inputStatusChangeBlock forPerson:(YWPerson *)person ofPriority:(YWBlockPriority)aPriority;

来监听输入状态的变化，下面是一个简单的示例：

__weak typeof(self) weakSelf = self;
YWPerson *personRequest = ((YWP2PConversation *)self.conversation).person;

[[self.coreRef getConversationService] addConversationInputStatusChangeBlock:^(YWPerson *person, YWConversationInputStatus status) {
        if ([person isEqual:personRequest]) {
            weakSelf.inputStatus = status;
            [weakSelf configTitleItems:status onlineStatus:weakSelf.onlineStatus];
        }
        
} forPerson:personRequest ofPriority:YWBlockPriorityDeveloper];

消息已读未读

已读未读开关

云旺的单聊消息支持显示对方已读未读状态，但此功能默认关闭，开发者可以通过IYWConversationService中的

- (void)setEnableMessageReadFlag:(BOOL)enableMessageReadFlag;

方法启用该功能，在未启用的情况下，当用户阅读消息时仍将发送已读消息，但不会显示，这样为了方便开发者进行兼容。

发送已读消息

当开发者需要将消息置为已读时，开发者可以通过YWIMCore层中YWP2PConversation中的

/**
 *  @virtual
 *  标识某消息为已读
 */
- (void)markMessageAsReadWithMessageIds:(NSArray *)messageIds

来实现。

获取消息的已读未读状态

开发者可以通过YWIMCore层中id<IYWMessage>对象的receiverHasReaded还获取本地已读未读状态，开发者也可以通过YWIMCore层中YWP2PConversation中的

/**
 *  获取消息接收者的已读未读标记
 *  @param messageIds,需要获取的 id<IYWMessage> 数组
 *  @param completion,回调
 *  注意，启用已读未读功能需要将 IYWConversationService 中 enableMessageReadFlag 置为 YES
 */
- (void)roamingReceiverReadFlagForMessages:(NSArray *)messages withCompletionBlock:(YWCompletionBlock)completion;

从服务端更新已读未读状态，如果状态发生变化将通过YWConversation的objectDidChangeBlock回调。

清空聊天记录

开发者可以通过YWIMCore层中YWConversation对象的

/**
 *  清空该会话已有的本地消息，被清空的消息不会再被漫游下来。
 *  @note 还没有被漫游下来的云端消息，仍然会被漫游下来
 *  @note 云端消息不会受影响，即如果在其他设备登录，这些消息仍会漫游
 */
- (void)removeAllLocalMessages;

来删除该会话的聊天记录

缓存

为了更快的加载资源以及节省网络流量，SDK内部会缓存一些资源，尤其是一些多媒体文件，在某些情况下，可能需要清除这些缓存。开发者可以通过

[[[YWAPI sharedInstance] getGlobalUtilService4Cache] removeAllDatas];

来清除缓存，并通过

long long size = [[[YWAPI sharedInstance] getGlobalUtilService4Cache] cacheSize];

来获取缓存所占的空间。由于存在一些索引文件，缓存所占的大小不会严格为零，如果需要显示给用户，可以参考这样的逻辑：

NSString *sizeStr = nil;
if (size > 1024 * 1024 * 1024) {
    sizeStr = [NSString stringWithFormat:@"%.1fG", (1.f * size)/(1024 * 1024 * 1024)];
} else if (size > 1024 * 1024) {
    sizeStr = [NSString stringWithFormat:@"%.1fM", (1.f * size)/(1024 * 1024)];
} else if (size > 1024) {
    sizeStr = [NSString stringWithFormat:@"%.1fK", (1.f * size)/1024];
} else {
    sizeStr = @"0K";
}

相关逻辑可以参考官方Demo中的SPSettingController。

获取最近联系的客服

开发者可以通过

/**
 *  获取最近联系的客服
 */
- (YWPerson *)getLastEHelper:(YWPerson *)eHelper;

来获取最近联系的客服，这个接口会返回本地接收到最新一条消息的客服发送者。

草稿

当接入Core层时需要关注这一小节，如果接入的是Kit层，SDK内部已经做了完整的逻辑。
开发者可以通过YWConversation的属性来访问和设置草稿:

/**
 *  会话未发送的草稿
 */
@property (nonatomic, copy) NSString *conversationDraft;

/**
 *  会话未发送的草稿更新时间
 */
@property (nonatomic, readonly) NSDate *conversationDraftUpdateTime;

短视频

只需要三步即可集成短视频功能：

step 1 开通多媒体服务

OpenIM提供了在聊天中发送短视频的功能。短视频存储要使用百川多媒体（顽兔）服务，开通流程及收费策略请点击百川云旺官网，侧边栏依次选择基础技术开放管理－>即时通讯服务->视频功能设置，如下图所示。

开通多媒体

step 2 链接SDK

如果开发者使用Kit层接入，还需要需要链接YWExtensionForShortVideoFMWK.framework、
TBAVSDK.framework、VSVideoCore.framework、ALBBMediaService.framework和系统的GLKit.framework用于短视频录制和上传，前面四个SDK可以在官方Demo中找到，注意将YWExtensionForShortVideoFMWK.framework中的YWShortVideo.bundle单独添加到工程中。

step3 短视频发送与展示

如果开发者使用Kit层接入，SDK默认支持短视频播放，可以在聊天界面添加聊天插件方式支持发送，

#define SPExtensionServiceFromProtocol(service) \
(id<service>)[[[YWAPI sharedInstance] getGlobalExtensionService] getExtensionByServiceName:NSStringFromProtocol(@protocol(service))]

if ([conversationController.messageInputView isKindOfClass:[YWMessageInputView class]]) {
    __weak typeof(conversationController) weakController = conversationController;
    YWInputViewPlugin *shortVideoPlugin = [SPExtensionServiceFromProtocol(IYWExtensionForShortVideoService) getShortVideoPluginWithPickerOverBlock:^(id<YWInputViewPluginProtocol> plugin, NSURL *fileUrl, UIImage *frontImage, NSUInteger width, NSUInteger height, NSUInteger duration) {
        [weakController sendVideoMessage:fileUrl videoSize:0 frontImage:frontImage width:width height:height duration:duration];
    }];
    [(YWMessageInputView *)conversationController.messageInputView addPlugin:shortVideoPlugin];
}

具体可以参考官方Demo SPKitExample中的逻辑。

如果开发者使用Core层接入，开发者负责短视频录制和展示，只需要链接ALBBMediaService.framework用于短视频上传。开发者可以通过YWMessageBodyShortVideo发送短视频，使用方式可以参考发送图片消息。

其他说明

较早版本的iOS SDK收到短视频消息会在聊天界面提示升级，会话列表界面最新消息显示内容为一段json。

短视频最长时间以及UI颜色，暂时不支持自定义。

使用OpenAccount免登OpenIM

请参考：使用OpenAccount免登OpenIM

其他

客服轨迹扩展

FAQ

关于此文档暂时还没有FAQ
有用(1) 我要提问
返回
顶部