跳到主要内容

设置与使用会话标签

  • SDK 从 5.1.1 版本开始支持会话标签功能，相关接口仅在 RCCoreClient 中提供。
  • 在为会话设置标签前，请确保已创建标签信息。详见管理标签信息数据。
  • 本功能不适用于聊天室、超级群。

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

场景描述​

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

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

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

使用标签标记会话​

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

支持以下操作：

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

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

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

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

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

        } error:^(RCErrorCode errorCode) {

        }];
参数类型说明
tagIdNSString标签 ID。
conversationIdentifiersNSArray会话列表，数组元素是 RCConversationIdentifier。
successBlockBlock成功回调。
errorBlockBlock失败回调。errorCode 参数返回 RCErrorCode。

从指定标签下移除会话​

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

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

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

        } error:^(RCErrorCode errorCode) {

        }];
参数类型说明
tagIdNSString标签 id
conversationIdentifiersNSArray会话列表，数组元素是 RCConversationIdentifier。
successBlockBlock成功回调。
errorBlockBlock失败回调。errorCode 参数返回 RCErrorCode。

为指定会话中移除标签​

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

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

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

        } error:^(RCErrorCode errorCode) {

        }];
参数类型说明
tagIdsNSArray标签 ID 列表。
conversationIdentifiersNSArray会话列表，数组元素是 RCConversationIdentifier。
successBlockBlock成功回调。
errorBlockBlock失败回调。errorCode 参数返回 RCErrorCode。

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

提示

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

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

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

[[RCCoreClient sharedCoreClient] getTagsFromConversation:iden completion:^(NSArray<RCConversationTagInfo *> *){
        //异步回调，返回标签列表
        }];
参数类型说明
conversationIdentifierRCConversationIdentifier会话标识，需要指定会话类型（RCConversationType）和 Target ID。
completionBlock异步回调，返回标签信息（RCConversationTagInfo）列表。

RCConversationTagInfo 说明：

参数类型说明
tagInfoRCTagInfo标签信息。
isTopBOOL会话是否置顶。

多端同步会话标签修改​

即时通讯支持同一用户账号在多端登录。如果您的 App 用户在当前设备上修改了会话标签，SDK 会负责通知该用户的其他设备。其他设备收到通知后，可以调用 getTagsFromConversation 从融云服务端获取指定会话的最新标签数据。

设置代理委托后后可在当前设备上接收到来自其他设备的会话标签修改通知。

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

设置代理委托​

//RCCoreClient.h
@property (nonatomic, weak) id<RCConversationTagDelegate> conversationTagDelegate;

代理方法​

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

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

当 App 用户在其它端添加、移除、编辑会话上的标签时，SDK 会触发 onConversationTagChanged 回调。请在收到通知后调用 getTagsFromConversation 从融云服务端获取指定会话的最新标签数据。

按标签操作会话数据​

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

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

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

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

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

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

提示

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

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

[[RCCoreClient sharedCoreClient] getConversationsFromTagByPage:texts[0] timestamp:0 count:20 completion:^(NSArray<RCConversation *> *){
      //异步回调，返回会话列表
}];
参数类型说明
tagIdNSString标签 ID。
timestamplong long会话的时间戳。获取这个时间戳之前的会话列表。首次可传 0，后续可以使用返回的 RCConversation 对象的 sentTime 或 operationTime 属性值，作为下一次查询的 startTime。推荐使用 operationTime（该属性仅在 5.6.8 及之后版本提供）。
countint获取的数量。当实际取回的会话数量小于 count 值时，表明已取完数据。
completionBlock异步回调，返回会话（RCConversation）列表。

按标签获取未读消息数​

提示

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

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

[[RCCoreClient sharedCoreClient] getUnreadCountByTag:@"tagId" containBlocked:isBlocked completion:^(int count){
        //异步回调
}];
参数类型说明
tagIdNSString标签 ID。
isContainBOOL是否包含免打扰会话。
completionBlock异步回调，返回会话消息未读数。

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

提示
  • 从 5.1.5 版本开始支持该功能。
  • 从 5.3.0 版本 RCCoreClient 开始，建议使用下方异步返回结果的接口，原同步接口同时废弃。

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

[[RCCoreClient sharedCoreClient] clearMessagesUnreadStatusByTag:@"tagId" completion:^(BOOL){
        //异步回调
}];
参数类型说明
tagIdNSString标签 ID。
completionBlock异步回调，返回是否清除成功。

删除标签对应的会话​

提示
  • 从 5.1.5 版本开始支持该功能。
  • 从 5.3.0 版本 RCCoreClient 开始，建议使用下方异步返回结果的接口，原同步接口同时废弃。

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

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

} error:^(RCErrorCode errorCode) {

}];
参数类型说明
tagIdNSString标签 ID。
optionRCClearConversationOption清除会话的相关配置。
successBlockBlock成功回调。
errorBlockBlock失败回调。errorCode 参数返回 RCErrorCode。

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

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