设置与使用会话标签

SDK 从 5.1.1 版本开始支持会话标签功能，相关接口仅在 RCCoreClient 类中提供。

SDK 从 5.3.0 版本开始，建议使用异步返回结果的接口，原同步接口同时废弃。

在为会话设置标签前，请确保已创建标签信息。详见管理标签信息数据。

本功能不适用于聊天室、超级群。

每个用户最多可以创建 20 个标签，每个标签下最多可以添加 1000 个会话。如果标签下已添加 1000 个会话，继续在该标签下添加会话仍会成功，但会导致最早添加标签的会话被移除标签。

场景描述

会话标签常实现 App 用户对会话进行分组的需求。创建标签信息（RCTagInfo）后，App 用户可以为会话设置一个或多个标签。

设置标签后，可以利用会话的标签数据实现会话的分组获取、展示、删除等特性。还可以获取指定标签下所有会话的消息未读数，或在特定标签下设置某个会话置顶。

场景 1：对会话列表中的每个会话打 tag，类似企业微信会话列表中的外部群，部门群，个人群等 tag。
场景 2：通讯录根据 tag 来分组，类似 QQ 好友列表中的家人，朋友，同事分组等。
场景 3：前两个场景的结合，按照 tag 来进行会话列表分组，类似 Telegram 的会话列表分组。

使用标签标记会话

在创建标签信息（RCTagInfo）后，App 用户可以使用标签标记会话。SDK 将用标签标记会话的操作视为将会话添加到标签中。

支持以下操作：

标记会话，即将一个或多个会话添加到指定标签
从标签中移除一个或多个会话
为指定会话移除一个或多个标签

将一个或多个会话添加到指定标签

IMlib SDK 将用标签标记会话的操作视为将会话添加到标签中。您可以将多个会话添加到一个标签。指定标签时只需要传入 RCTagInfo 中的 tagId。

方法原型

Objective C
- (void)addConversationsToTag:(NSString *)tagId
      conversationIdentifiers:(NSArray<RCConversationIdentifier *> *)conversationIdentifiers
                      success:(nullable void (^)(void))successBlock
                        error:(nullable void (^)(RCErrorCode errorCode))errorBlock;

参数说明

参数	类型	说明
`tagId`	`NSString`	标签 ID。
`conversationIdentifiers`	`NSArray`	会话列表，数组元素是 `RCConversationIdentifier`。
`successBlock`	`Block`	成功回调。
`errorBlock`	`Block`	失败回调。`errorCode` 参数返回 `RCErrorCode`。

示例代码

Objective C
RCConversationIdentifier *iden = [[RCConversationIdentifier alloc] initWithConversationIdentifier:ConversationType_PRIVATE targetId:@"targetId"];

[[RCCoreClient sharedCoreClient] addConversationsToTag:@"tagId" conversationIdentifiers:@[iden] success:^{

        } error:^(RCErrorCode errorCode) {

        }];

从指定标签下移除会话

您可能需要在携带指定标签的会话中移除一个或多个会话。例如，在所有添加了培训班标签的会话中移除与Tom的私聊会话。IMLib SDK 将该操作视为从指定标签中移除会话。移除成功后，会话仍然存在，但不再携带该标签。

接口原型

Objective C
- (void)removeConversationsFromTag:(NSString *)tagId
           conversationIdentifiers:(NSArray<RCConversationIdentifier *> *)conversationIdentifiers
                           success:(nullable void (^)(void))successBlock
                             error:(nullable void (^)(RCErrorCode errorCode))errorBlock;

参数说明

参数	类型	说明
`tagId`	`NSString`	标签 id
`conversationIdentifiers`	`NSArray`	会话列表，数组元素是 `RCConversationIdentifier`。
`successBlock`	`Block`	成功回调。
`errorBlock`	`Block`	失败回调。`errorCode` 参数返回 `RCErrorCode`。

示例代码

Objective C
RCConversationIdentifier *iden = [[RCConversationIdentifier alloc] initWithConversationIdentifier:ConversationType_PRIVATE targetId:@"targetId"];

[[RCCoreClient sharedCoreClient] removeConversationsFromTag:@"tagId" conversationIdentifiers:@[iden] success:^{

} error:^(RCErrorCode errorCode) {

}];

为指定会话中移除标签

您可以为指定会话中添加了多个标签。IMLib SDK 支持一次移除单个或多个标签。移除时需要传入所有待移除 RCTagInfo 的 tagId 列表。

接口原型

Objective C
- (void)removeTagsFromConversation:(RCConversationIdentifier *)conversationIdentifier
                            tagIds:(NSArray<NSString *> *)tagIds
                           success:(nullable void (^)(void))successBlock
                             error:(nullable void (^)(RCErrorCode errorCode))errorBlock;

参数说明

参数	类型	说明
`tagIds`	`NSArray`	标签 ID 列表。
`conversationIdentifiers`	`NSArray`	会话列表，数组元素是 `RCConversationIdentifier`。
`successBlock`	`Block`	成功回调。
`errorBlock`	`Block`	失败回调。`errorCode` 参数返回 `RCErrorCode`。

示例代码

Objective C
RCConversationIdentifier *iden = [[RCConversationIdentifier alloc] initWithConversationIdentifier:ConversationType_PRIVATE targetId:@"targetId"];

[[RCCoreClient sharedCoreClient] removeTagsFromConversation:iden tagIds:@[@"tagId1",@"tagId2"] success:^{

        } error:^(RCErrorCode errorCode) {

        }];

获取指定会话的所有标签

您可以获取指定会话携带的所有标签。获取成功后，回调中返回 RCConversationTagInfo 的列表。每个 RCConversationTagInfo 中包含对应的标签信息 RCTagInfo 和置顶状态信息（会话是否在携带该标签信息的所有会话中置顶）。

接口原型

Objective C
- (void)getTagsFromConversation:(RCConversationIdentifier *)conversationIdentifier
                     completion:(nullable void(^)(NSArray<RCConversationTagInfo *> *_Nullable results))completion;

参数说明

参数	类型	说明
`conversationIdentifier`	`RCConversationIdentifier`	会话标识，需要指定会话类型（`RCConversationType`）和 Target ID。
`completion`	`Block`	异步回调，返回标签信息（`RCConversationTagInfo`）列表。

RCConversationTagInfo 说明：

参数	类型	说明
`tagInfo`	`RCTagInfo`	标签信息。
`isTop`	`BOOL`	会话是否置顶。

示例代码

Objective C
RCConversationIdentifier *iden = [[RCConversationIdentifier alloc] initWithConversationIdentifier:ConversationType_PRIVATE targetId:@"targetId"];

[[RCCoreClient sharedCoreClient] getTagsFromConversation:iden completion:^(NSArray<RCConversationTagInfo *> *){
        //异步回调，返回标签列表
        }];

多端同步会话标签修改

融云支持同一用户账号在多端登录。设置会话标签变更监听器 conversationTagDelegate 后，当用户在其它端添加、移除、编辑会话上的标签时，都会触发 onConversationTagChanged 回调，可在当前设备上接收到来自其他设备的会话标签修改通知。收到通知后需调用 getTagsFromConversation 方法从融云服务端获取指定会话的最新标签数据。

提示

请在初始化之后，连接之前调用该方法。
在当前设备上修改标签信息不会触发该回调方法。服务端仅会通知 SDK 在同一用户账号登录的其他设备上触发回调。

设置代理委托

Objective C
//RCCoreClient.h
@property (nonatomic, weak) id<RCConversationTagDelegate> conversationTagDelegate;
[RCCoreClient sharedCoreClient].conversationTagDelegate = self;

代理方法

Objective C
@protocol RCConversationTagDelegate <NSObject>
/*!
 会话标签变化

 @discussion 本端添加删除更新会话标签，不会触发此回调方法，在相关调用方法的 block 块直接回调
 */
- (void)onConversationTagChanged;
@end

按标签操作会话数据

IMLib SDK 支持对携带指定标签的会话进行操作。App 用户为会话添加标签后，可以实现以下操作：

配合使用会话置顶功能，可以实现在携带指定标签的会话中置顶会话
按标签获取会话列表，即获取携带指定标签的所有会话
按标签获取未读消息数
清除标签对应会话的未读消息数
删除标签对应的会话

在携带指定标签的会话中置顶

您可以使用会话标签按照业务需求对会话进行分类和展示。如果需要在同一类会话（携带同一标签的所有会话）中置顶显示会话，可以使用会话置顶功能。

详细实现方式请参见会话置顶的**在标签下置顶会话。

分页获取本地指定标签下会话列表

您可以以会话中 operationTime 为界，分页获取本地指定标签下会话列表。该方法仅从本地数据库中获取数据。从 5.6.4 版本开始，该接口返回的 RCConversation 对象新增 isTopForTag 属性，如果为 YES，表示该会话在当前 tagId 下为置顶会话。

接口原型

Objective C
- (void)getConversationsFromTagByPage:(NSString *)tagId
                            timestamp:(long long)timestamp
                                count:(int)count
                           completion:(nullable void(^)(NSArray<RCConversation *> *_Nullable results))completion;

参数说明

参数	类型	说明
`tagId`	`NSString`	标签 ID。
`timestamp`	long long	会话的时间戳。获取这个时间戳之前的会话列表。首次可传 `0`，后续可以使用返回的 `RCConversation` 对象的 `sentTime` 或 `operationTime` 属性值，作为下一次查询的 `startTime`。推荐使用 `operationTime`（该属性仅在 5.6.8 及之后版本提供）。
`count`	`int`	获取的数量。当实际取回的会话数量小于 count 值时，表明已取完数据。
`completion`	`Block`	异步回调，返回会话（`RCConversation`）列表。

示例代码

Objective C
[[RCCoreClient sharedCoreClient] getConversationsFromTagByPage:texts[0] timestamp:0 count:20 completion:^(NSArray<RCConversation *> *){
      //异步回调，返回会话列表
}];

分页获取本地没有标签的会话列表

提示

从 5.24.0 版本开始，在 RCCoreClient 中支持。

您可使用 getUntaggedConversationListByPage:count:topPriority:completionHandler: 接口获取未标记的会话列表。

参数说明

参数	类型	说明
`timestamp`	long long	会话的时间戳（获取这个时间戳之前的会话列表，0表示从最新开始获取，单位：毫秒）
`count`	`NSInteger`	获取的数量，有效值 [1, 100]。（当实际取回的会话数量小于 count 值时，表明已取完数据）。
`topPriority`	`BOOL`	查询结果的排序方式，是否置顶优先，传 YES 表示置顶会话优先返回，否则结果只以会话时间排序。
`completionHandler`	`block`	结果回调，会话列表和错误码。

示例代码

Objective C
[[RCCoreClient sharedCoreClient] getUntaggedConversationListByPage:0 count:10 topPriority:YES completionHandler:^(NSArray<RCConversation *> * _Nonnull conversations, RCErrorCode code) {
    // TODO 业务处理
}];

按标签获取未读消息数

您可以获取携带指定标签的所有会话的未读消息数。

接口原型

Objective C
- (void)getUnreadCountByTag:(NSString *)tagId
             containBlocked:(BOOL)isContain
                 completion:(nullable void(^)(int count))completion;

参数说明

参数	类型	说明
`tagId`	`NSString`	标签 ID。
`isContain`	`BOOL`	是否包含免打扰会话。
`completion`	`Block`	异步回调，返回会话消息未读数。

示例代码

Objective C
[[RCCoreClient sharedCoreClient] getUnreadCountByTag:@"tagId" containBlocked:isBlocked completion:^(int count){
        //异步回调
}];

清除标签对应会话的未读消息数

您可以清除携带指定标签的所有会话的未读消息数。

接口原型

Objective C
- (void)clearMessagesUnreadStatusByTag:(NSString *)tagId
                            completion:(nullable void(^)(BOOL ret))completion;

参数说明

参数	类型	说明
`tagId`	`NSString`	标签 ID。
`completion`	`Block`	异步回调，返回是否清除成功。

示例代码

Objective C
[[RCCoreClient sharedCoreClient] clearMessagesUnreadStatusByTag:@"tagId" completion:^(BOOL){
        //异步回调
}];

删除标签对应的会话

您可以删除指定标签下的全部会话，同时解除这些会话和标签的绑定关系。删除成功后，会话不再携带指定的标签。这些会话收到新消息时，会产生新的会话。

接口原型

Objective C
- (void)clearConversationsByTag:(NSString *)tagId
                         option:(RCClearConversationOption *)option
                        success:(nullable void (^)(void))successBlock
                          error:(nullable void (^)(RCErrorCode errorCode))errorBlock;

参数说明

参数	类型	说明
`tagId`	`NSString`	标签 ID。
`option`	`RCClearConversationOption`	清除会话的相关配置。
`successBlock`	`Block`	成功回调。
`errorBlock`	`Block`	失败回调。`errorCode` 参数返回 `RCErrorCode`。

示例代码

Objective C
RCClearConversationOption *option = [[RCClearConversationOption alloc] init];
option.isDeleteMessage = YES;
[[RCCoreClient sharedCoreClient] clearConversationsByTag:@"tagId" option:option success:^{

} error:^(RCErrorCode errorCode) {

}];

您可以通过 option 参数的 isDeleteMessage 属性配置是否同时清除这些会话对应的本地消息。

如果不删除会话对应的本地消息，再接收到新消息时，可以看到历史聊天记录。
如果删除会话对应的本地消息，再接收到新消息时，无法看到历史聊天记录。如果开通了单群聊消息云端存储服务，服务端仍保存有消息历史。如需删除，请使用删除服务端历史消息接口。

IMLib

IMKit

Global IM UIKit

推送服务

IMLib

IMKit

CallLib

CallKit

CallPlus

RTCLib

CallLib

CallPlus

RTCLib

IM 服务端

IM Server SDK

RTC 服务端

北极星数据查询

设置与使用会话标签

场景描述​

使用标签标记会话​

将一个或多个会话添加到指定标签​

方法原型​

参数说明​

示例代码​

从指定标签下移除会话​

接口原型​

参数说明​

示例代码​

为指定会话中移除标签​

接口原型​

参数说明​

示例代码​

获取指定会话的所有标签​

接口原型​

参数说明​

示例代码​

多端同步会话标签修改​

设置代理委托​

代理方法​

按标签操作会话数据​

在携带指定标签的会话中置顶​

分页获取本地指定标签下会话列表​

接口原型​

参数说明​

示例代码​

分页获取本地没有标签的会话列表​

参数说明​

示例代码​

按标签获取未读消息数​

接口原型​

参数说明​

示例代码​

清除标签对应会话的未读消息数​

接口原型​

参数说明​

示例代码​

删除标签对应的会话​

接口原型​

参数说明​

示例代码​

场景描述

使用标签标记会话

将一个或多个会话添加到指定标签

方法原型

参数说明

示例代码

从指定标签下移除会话

接口原型

参数说明

示例代码

为指定会话中移除标签

接口原型

参数说明

示例代码

获取指定会话的所有标签

接口原型

参数说明

示例代码

多端同步会话标签修改

设置代理委托

代理方法

按标签操作会话数据

在携带指定标签的会话中置顶

分页获取本地指定标签下会话列表

接口原型

参数说明

示例代码

分页获取本地没有标签的会话列表

参数说明

示例代码

按标签获取未读消息数

接口原型

参数说明

示例代码

清除标签对应会话的未读消息数

接口原型

参数说明

示例代码

删除标签对应的会话

接口原型

参数说明

示例代码