跳到主要内容

会话置顶

会话置顶功能提供以下能力:

  • 在会话列表中置顶会话:通过会话(Conversation)的置顶(isTop)属性控制。
  • 在携带同一标签的会话中置顶(需配合使用会话标签功能):通过 ConversationTagInfo 类的 isTop 属性控制。

在会话列表中置顶会话

设置指定会话在会话列表中置顶后,SDK 将修改 ConversationisTop 字段,该状态将会被同步到服务端。融云会在为用户自动同步会话置顶的状态数据。客户端可以主动获取或通过监听器获取到最新数据。

设置会话置顶

使用 setConversationToTop 设置会话置顶。

ConversationType conversationType = ConversationType.PRIVATE;
String targetId = " 会话 Id ";
boolean isTop = true;
boolean needCreate = true;

RongIMClient.getInstance().setConversationToTop(conversationType, targetId, isTop, new
ResultCallback<Boolean>() {

@Override
public void onSuccess(Boolean success) {

}

@Override
public void onError(RongIMClient.ErrorCode ErrorCode) {

}
}) ;
参数类型说明
conversationTypeConversationType会话类型,支持单聊、群聊、系统会话。
targetIdString会话 ID
isTopboolean是否置顶。true 为置顶,false 为取消置顶。
callbackResultCallback<Boolean>回调接口

客户端通过本地消息数据自动生成会话与会话列表,并会在用户登录的多个设备之间同步置顶状态。如果在调用该 API 时,会话尚未生成,或者已被移除,SDK 的处理方式如下:

  • 如果 SDK 版本 ≧ 5.6.8,当需要置顶的会话在本地或该用户登录的其他设备上不存在时,SDK 会自动创建会话并置顶。
  • 如果 SDK 版本 < 5.6.8,必须使用支持 needCreate 参数的重载方法,并设置该参数为 true,SDK 才会自动创建会话并置顶。详见 API 参考 setConversationToTop

设置会话置顶可选择是否更新会话时间(SDK 版本 ≧ 5.8.2)

使用 setConversationToTop 设置会话置顶。

ConversationType conversationType = ConversationType.PRIVATE;
String targetId = " 会话 Id ";
boolean isTop = true;
boolean needCreate = true;
boolean needUpdateTime = true;

RongCoreClient.getInstance().setConversationToTop(conversationType, targetId, isTop, needCreate, needUpdateTime, new
IRongCoreCallback.ResultCallback<Boolean>() {

@Override
public void onSuccess(Boolean success) {

}

@Override
public void onError(IRongCoreEnum.CoreErrorCode ErrorCode) {

}
}) ;
参数类型说明
conversationTypeConversationType会话类型,支持单聊、群聊、系统会话。
targetIdString会话 ID
isTopboolean是否置顶。true 为置顶,false 为取消置顶。
needCreateboolean是否创建。true 为创建,false 为不创建。
needUpdateTimeboolean是否更新时间。true 为更新,false 为不更新。
callbackResultCallback<Boolean>回调接口

监听置顶状态同步

SDK 提供了会话状态(置顶状态数据和免打扰状态数据)同步机制。设置会话状态同步监听器后,如果会话状态改变,可在本端收到通知。

会话的置顶和免打扰状态数据同步后,触发 ConversationStatusListeneronStatusChanged 方法。详细说明可参见多端同步免打扰/置顶

public interface ConversationStatusListener {
void onStatusChanged(ConversationStatus[] conversationStatus);
}

获取会话置顶状态

提示

SDK 从 5.1.5 版本开始支持该功能。

主动获取指定会话的置顶状态。

RongCoreClient.getInstance().getConversationTopStatus(targetId, conversationType, callback)
参数类型说明
targetIdString会话 ID
conversationTypeConversationType会话类型
callbackIRongCoreCallback.ResultCallback回调结果

获取置顶会话列表

主动获取指定会话类型的所有置顶会话。

Conversation.ConversationType[] conversationTypes = {Conversation.ConversationType.PRIVATE};

RongIMClient.getInstance().getTopConversationList(new ResultCallback<List<Conversation>>() {
@Override
public void onSuccess(List<Conversation> conversations) {

}

@Override
public void onError(ErrorCode e) {

}
}, conversationTypes);
参数类型说明
callbackResultCallback<List<Conversation>>回调接口
conversationTypesConversation.ConversationType...会话类型数组

在携带标签的所有会话中置顶会话

提示

该功能相关接口仅在 RongCoreClient 中提供。在标签标记的所有会话中置顶是通过修改 ConversationTagInfo.isTop 字段实现的,不影响 ConversationisTop 字段。

如果 App 实现了会话标签功能,App 用户可能会使用同一个标签标记多个会话,并且需要将其中一个会话置顶。SDK 在 ConversationTagInfo 中提供 isTop 属性,用于控制会话是否需要在携带同样标签的会话中置顶。

在标签下置顶会话

在携带指定标签的所有会话中设置指定会话置顶。例如,在所有添加了「培训班」标签的会话中将与「Tom」的私聊会话置顶。

String targetId = "useridoftom";
ConversationIdentifier conversationIdentifier = new ConversationIdentifier(Conversation.ConversationType.PRIVATE, targetId);
String tagId = "peixunban";

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

}

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

}
});
参数类型说明
tagIdString标签 ID
conversationIdentifierConversationIdentifier会话标识,需要指定会话类型(ConversationType)和 Target ID。
isTopboolean是否置顶
callbackOperationCallback操作回调

获取会话在标签下的置顶状态

查询指定会话是否在携带同一标签的所有会话中置顶。获取成功后会返回是否已置顶。

RongCoreClient.getInstance().getConversationTopStatusInTag(conversationIdentifier, tagId,
new IRongCoreCallback.ResultCallback<Boolean>() {
/**
* 获取成功回调
*/
@Override
public void onSuccess(Boolean bool) {

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

}
});

是否开启同步空置顶会话

此功能在 5.10.0 版本起开始支持。

在您卸载并重新安装应用或更换设备登录时,融云允许您决定是否希望保留会话列表中置顶的会话,包括那些尚未包含任何消息的空会话。默认情况下,这些置顶状态将被保留。

您可以在 SDK 初始化过程中选择是否启用同步置顶会话的功能。通过调用 InitOption 类的 enableSyncEmptyTopConversation 方法,并传入 truefalse 作为参数,来启用或禁用此功能。默认情况下,此功能是关闭的。

示例代码

InitOption initOption = new InitOption.Builder()
.enableSyncEmptyTopConversation(true)
.build();
RongCoreClient.init(context, appKey, initOption);