跳到主要内容

设置与使用会话标签

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

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

场景描述​

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

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

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

使用标签标记会话​

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

支持以下操作：

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

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

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

RongCoreClient.getInstance().addConversationsToTag(tagId, conversationIdentifierList,
    new IRongCoreCallback.OperationCallback() {
            /**
             * 成功回调
             */
            @Override
            public void onSuccess() {

            }

            /**
             * 失败回调
             * @param errorCode 错误码
             */
            @Override
            public void onError(IRongCoreEnum.CoreErrorCode coreErrorCode) {

            }
        });
参数类型说明
tagIdString标签 ID
conversationIdentifierListList<ConversationIdentifier>会话标识列表。每个 ConversationIdentifier 中需要指定会话类型（ConversationType）和 Target ID。
callbackOperationCallback回调

从指定标签下移除会话​

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

RongCoreClient.getInstance().removeConversationsFromTag(tagId, conversationIdentifierList, callback);
参数类型说明
tagIdString标签 ID
conversationIdentifierListList<ConversationIdentifier>会话标识列表。每个 ConversationIdentifier 中需要指定会话类型（ConversationType）和 Target ID。
callbackOperationCallback回调

为指定会话中移除标签​

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

RongCoreClient.getInstance(). removeTagsFromConversation(conversationIdentifier, tagIds,
    new IRongCoreCallback.OperationCallback() {
            /**
             * 成功回调
             */
            @Override
            public void onSuccess() {

            }

            /**
             * 失败回调
             * @param errorCode 错误码
             */
            @Override
            public void onError(IRongCoreEnum.CoreErrorCode coreErrorCode) {

            }
        });

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

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

RongCoreClient.getInstance().getTagsFromConversation(conversationIdentifier,
    new IRongCoreCallback.ResultCallback<List<ConversationTagInfo>>() {
            /**
             * 成功回调
             */
            @Override
            public void onSuccess(List<ConversationTagInfo> conversationTagInfos) {

            }

            /**
             * 失败回调
             * @param errorCode 错误码
             */
            @Override
            public void onError(IRongCoreEnum.CoreErrorCode coreErrorCode) {

            }
        });
参数类型说明
conversationIdentifierConversationIdentifier会话标识，需要指定会话类型（ConversationType）和 Target ID。
callbackResultCallback<List<ConversationTagInfo>>结果回调，返回会话携带的所有标签。

多端同步会话标签修改​

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

设置会话标变更监听器 IRongCoreListener.ConversationTagListener 后可在当前设备上接收到来自其他设备的会话标签修改通知。

提示
  • 请在初始化之后，连接之前调用该方法。
  • 在当前设备上修改标签信息不会触发该回调方法。服务端仅会通知 SDK 在同一用户账号登录的其他设备上触发回调。
RongCoreClient.getInstance().setConversationTagListener(new IRongCoreListener.ConversationTagListener{
    @Override
    public void onConversationTagChanged() {
    }
});

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

按标签操作会话数据​

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

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

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

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

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

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

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

RongCoreClient.getInstance().getConversationsFromTagByPage(tagId, ts, count, callback);
参数类型说明
tagIdString标签 ID
tslong会话的时间戳。获取这个时间戳之前的会话列表。首次可传 0，后续可以使用返回的 Conversation 对象的 sentTime 或 operationTime 属性值，作为下一次查询的 startTime。推荐使用 operationTime（该属性仅在 5.6.8 及之后版本提供）。
countint获取数量(20 ≦ count ≦ 100)
callbackResultCallback<List<Conversation>>返回携带指定 tagId 的会话列表。

按标签获取未读消息数​

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

RongCoreClient.getInstance().getUnreadCountByTag(tagId, containBlocked, callback);
参数类型说明
tagIdString标签 ID
containBlockedboolean是否包含免打扰消息
callbackResultCallback<Integer>按标签获取未读消息数回调

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

提示

SDK 从 5.1.5 开始提供该接口。

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

RongCoreClient.getInstance().clearMessagesUnreadStatusByTag(tagId, callback)
参数类型说明
tagIdString标签 ID
callbackIRongCoreCallback.ResultCallback操作结果回调

删除标签对应的会话​

提示

SDK 从 5.1.5 开始提供该接口。

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

RongCoreClient.getInstance().clearConversationsByTag(tagId, deleteMessage, callback)
参数类型说明
tagIdString标签 ID。
deleteMessageboolean是否清除该标签下所有会话的本地历史消息。
callbackIRongCoreCallback.ResultCallback操作结果回调。

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

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