跳到主要内容

会话置顶

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

  • 在会话列表中置顶会话：通过会话（RCConversation）的置顶（isTop）属性控制。
  • 在携带同一标签的会话中置顶（需配合使用会话标签功能）：通过 RCConversationTagInfo 类的 isTop 属性控制。
  • 从 5.20.0 版本开始，支持超级群类型会话置顶，该功能需提交工单申请开通。

监听置顶状态同步​

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

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

在会话列表中置顶会话​

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

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

设置会话置顶​

使用 setConversationToTop:targetId:isTop:completion: 设置会话置顶。

接口原型​

Objective C
- (void)setConversationToTop:(RCConversationType)conversationType
                    targetId:(NSString *)targetId
                       isTop:(BOOL)isTop
                  completion:(nullable void(^)(BOOL ret))completion;

参数说明​

参数类型说明
conversationTypeRCConversationType会话类型，支持单聊、群聊、系统会话。
targetIdNSString会话 id
isTopBOOL是否置顶
completionBlock设置置顶结果回调

示例代码​

Objective C
// Set the conversation type and target ID
RCConversationType conversationType = ConversationType_PRIVATE;
NSString *targetId = @"your_target_id";

// Set the conversation to top or not
BOOL isTop = YES;

[[RCCoreClient sharedCoreClient] setConversationToTop:conversationType
                                             targetId:targetId
                                                isTop:isTop
                                           completion:^(BOOL success) {}];

客户端通过本地消息数据自动生成会话与会话列表，并会在用户登录的多个设备之间同步置顶状态。如果在调用该 API 时，要置顶的会话在本地或该用户登录的其他设备上不存在（会话尚未生成，或者已被移除），SDK 将直接创建会话并置顶。

设置会话置顶可选择是否更新会话时间​

您可以使用 [setConversationToTop:targetId:isTop:needUpdateTime:completion:] 设置会话置顶控制是否更新会话时间。

接口原型​

Objective C
- (void)setConversationToTop:(RCConversationType)conversationType
                    targetId:(NSString *)targetId
                       isTop:(BOOL)isTop
              needUpdateTime:(BOOL)needUpdateTime
                  completion:(nullable void(^)(BOOL result))completion;

参数说明​

参数类型说明
conversationTypeRCConversationType会话类型，支持单聊、群聊、系统、超级群会话。
targetIdNSString会话 id
isTopBOOL是否置顶
needUpdateTimeBOOL是否会话更新时间
completionBlock设置置顶结果回调

示例代码​

Objective C
// Set the conversation type and target ID
RCConversationType conversationType = ConversationType_PRIVATE;
NSString *targetId = @"your_target_id";

// Set the conversation to top or not
BOOL isTop = YES;

[[RCCoreClient sharedCoreClient] setConversationToTop:conversationType
                                             targetId:targetId
                                                isTop:isTop
                                       needUpdateTime:YES
                                           completion:^(BOOL success) {}];
参数类型说明
conversationTypeRCConversationType会话类型，支持单聊、群聊、系统、超级群会话。
targetIdNSString会话 id
isTopBOOL是否置顶
needUpdateTimeBOOL是否更新时间
completionBlock设置置顶结果回调

客户端通过本地消息数据自动生成会话与会话列表，并会在用户登录的多个设备之间同步置顶状态。如果在调用该 API 时，要置顶的会话在本地或该用户登录的其他设备上不存在（会话尚未生成，或者已被移除），SDK 将直接创建会话并置顶。

批量设置会话置顶​

使用 setConversationsToTop:isTop:option:completion: 接口，批量设置会话置顶。

Objective C
    RCConversationIdentifier *identifier = [[RCConversationIdentifier alloc] init];
    identifier.type = ConversationType_GROUP;
    identifier.targetId = @"tId";
    RCConversationTopOption *option = [[RCConversationTopOption alloc] init];
    option.needCreateConversation = YES;
    option.needUpdateTime = YES;
    [[RCCoreClient sharedCoreClient] setConversationsToTop:@[identifier]
                                                     isTop:YES
                                                    option:option
                                                completion:^(RCErrorCode code) {
        // set conversation top
    }];
参数类型说明
conversationIdentifiersRCConversationIdentifier会话标识列表。
isTopBOOL是否置顶
optionRCConversationTopOption配置信息，支持设置是否更新时间和是否创建会话
completionBlock设置置顶结果回调

获取是否置顶​

提示
  • 从 5.1.5 版本开始支持该功能。

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

接口原型​

Objective C
- (void)getConversationTopStatus:(RCConversationIdentifier *)conversationIdentifier
                      completion:(nullable void(^)(BOOL ret))completion;

参数说明​

参数类型说明
conversationIdentifierRCConversationIdentifier会话标识，需要指定会话类型（RCConversationType）和 Target ID。
completionBlock返回是否设置成功。

示例代码​

Objective C
RCConversationIdentifier *iden = [[RCConversationIdentifier alloc] initWithConversationIdentifier:ConversationType_PRIVATE targetId:@"targetId"];
[[RCCoreClient sharedCoreClient] getConversationTopStatus:iden completion:^(BOOL){
    //异步回调，是否获取成功
}];
### 获取置顶会话列表

您可以主动获取指定会话类型的所有置顶会话。
#### 接口原型
```objectivec
- (void)getTopConversationList:(NSArray<NSNumber *> *)conversationTypeList
                    completion:(nullable void(^)(NSArray<RCConversation *>  *_Nullable conversationList))completion;

参数说明​

参数类型说明
conversationTypesNSArray会话类型的数组，需要将 RCConversationType 转为 NSNumber 构建 Array
completionBlock获取成功后，返回会话 RCConversation 的列表。

示例代码​

Objective C
[[RCCoreClient sharedCoreClient] getTopConversationList:@[@(ConversationType_PRIVATE)]
                                                 completion:^(NSArray<RCConversation *> *conversationList) {
}];

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

提示

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

如果 App 实现了会话标签功能，App 用户可能会使用同一个标签标记多个会话，并且需要将其中一个会话置顶。SDK 在 RCConversationTagInfo 中提供 isTop 字段，用于控制会话在携带同样标签的会话中的置顶状态。

在标签下置顶会话​

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

接口原型​

Objective C
- (void)setConversationToTopInTag:(NSString *)tagId
           conversationIdentifier:(RCConversationIdentifier *)conversationIdentifier
                            isTop:(BOOL)top
                          success:(nullable void (^)(void))successBlock
                            error:(nullable void (^)(RCErrorCode errorCode))errorBlock;

参数说明​

参数类型说明
tagIdString标签 ID
conversationIdentifierRCConversationIdentifier会话标识，需要指定会话类型（RCConversationType）和 Target ID。
isTopBOOL是否置顶
successBlockBlock成功回调
errorBlockBlock失败回调。errorCode 参数返回 RCErrorCode。

示例代码​

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

[[RCCoreClient sharedCoreClient] setConversationToTopInTag:tagId conversationIdentifier:iden isTop:isTop success:^{

        } error:^(RCErrorCode errorCode) {

        }];

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

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

接口原型​

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

参数说明​

参数类型说明
tagIdNSString标签 ID
conversationIdentifierRCConversationIdentifier会话标识，需要指定会话类型（RCConversationType）和 Target ID。
completionBlock异步回调，返回是否置顶

示例代码​

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

[[RCCoreClient sharedCoreClient] getConversationTopStatusInTag:iden tagId:@"tagId" completion:^(BOOL){
        // 异步回调，返回置顶状态
}];

## 是否开启同步空置顶会话（SDK 版本 ≧ 5.10.0）

当用户卸载后重装或更换设备登录时，置顶状态的会话可能会在会话列表中显示，包括已置顶的空会话。

从 5.10.1 版本开始，支持是否开启同步空置顶会话功能。
您可在 SDK 初始化时通过 `RCInitOption` 的 `enableSyncEmptyTopConversation` 属性设置是否开启。如不设置，SDK 默认不自动同步空置顶会话。
:::tip
如果开启同步空置顶会话功能，那么分页获取会话数据时，第一页 startTime 传 0，后续传会话对象 `operationTime` 的值。
:::
#### 示例代码
```objectivec
RCInitOption *initOption = [[RCInitOption alloc] init];
// 打开同步空置顶会话
initOption.enableSyncEmptyTopConversation = YES;
// 初始化 SDK
[[RCCoreClient sharedCoreClient] initWithAppKey:@"your_appkey" option:initOption];
最后于 更新