标记会话
功能简介
当您遇到需要关注某会话或暂时无法处理某条会话等场景时,您可以标记会话并稍后处理,例如 "会话标星"、"会话折叠"、"会话隐藏"、“会话标记未读”等。为会话设置标记后,即可以标记为过滤项获取会话列表和未读消息总数。
- 每名用户最多可标记 1000 个会话。
- 当用户标记了会话,ZIM SDK 只会简单记录会话的标记值,并不会改变会话的底层逻辑。
设置会话标记
ZIM 支持开发者使用客户端 API 或 服务端 API 实现对会话的标记操作。
客户端 API
1 监听 onConversationChanged
用户登录 ZIM SDK 后,需监听注册 setEventHandler 监听的 onConversationChanged 回调接口,接收会话标记变化通知。
当会话标记变更后,用户的所有在线设备会收到 onConversationChanged 事件通知,从其中 conversation.marks 字段可以获取到该会话当前的所有标记。
// 注册 SDK 事件通知回调
zim.setEventHandler(this);
...
public void onConversationChanged(ZIM zim, ArrayList<ZIMConversationChangeInfo> conversationChangeInfoList) {
super.onConversationChanged(zim, conversationChangeInfoList);
for (ZIMConversationChangeInfo conversationChangeInfo : conversationChangeInfoList) {
// 从 conversationChangeInfo.conversation.marks 中可以获取到该会话的全量标记
}
}
1
// 注册 SDK 事件通知回调
[self.zim setEventHandler:self];
...
// 注册 SDK 事件通知回调
- (void)zim:(ZIM *)zim
conversationChanged:(NSArray<ZIMConversationChangeInfo *> *)conversationChangeInfoList{
for(ZIMConversationChangeInfo *changeInfo in conversationChangeInfoList){
// 从 conversationChangeInfo.conversation.marks 中可以获取到该会话的全量标记
}
}
1
// 注册 SDK 事件通知回调
class zim_event_handler : public zim::ZIMEventHandler {
//
virtual void onConversationChanged(
zim::ZIM *zim,
const std::vector<zim::ZIMConversationChangeInfo> &conversationChangeInfoList) override;
}
1
// 注册 SDK 事件通知回调
zim.on('conversationChanged', function (zim, { infoList }) {
infoList.forEach((info) => {
console.log(info.conversation.marks);
});
});
1
// 注册 SDK 事件通知回调
ZIMEventHandler.onConversationChanged = (ZIM zim, List<ZIMConversationChangeInfo> conversationChangeInfoList){
for (ZIMConversationChangeInfo conversationChangeInfo in conversationChangeInfoList) {
// 从 conversationChangeInfo.conversation.marks 中可以获取到该会话的全量标记
}
};
1
2 设置或取消标记
您只需调用 setConversationMark 接口,即可对至多 100 个会话(仅支持单聊或群聊)设置或取消标记。每个会话至多可以拥有 20 个标记。
// 以对一个群聊会话设置标签为 1 为例
Integer markType = 1;
boolean enable = true;
ArrayList<ZIMConversationBaseInfo> convList = new ArrayList<>();
ZIMConversationBaseInfo conversation = new ZIMConversationBaseInfo();
conversation.conversationID = "GroupConv";
conversation.conversationType = ZIMConversationType.GROUP;
convList.add(conversation);
zim.setConversationMark(markType, enable, convList, new ZIMConversationMarkSetCallback() {
@Override
public void onConversationMarkSet(ArrayList<ZIMConversationBaseInfo> failedConversationInfos, ZIMError errorInfo) {
if(errorInfo.code == ZIMErrorCode.SUCCESS) {
// 操作成功的处理。
// 注意:即便部分操作成功,部分操作失败,errorCode 仍会为 SUCCESS,且会在 failedConversationInfos 返回操作失败的会话
} else {
// 对所有会话的操作都失败时的处理
}
}
});
1
// 以对一个群聊会话设置标签为 1 为例
NSNumber *markType = @(1);
BOOL enable = YES;
ZIMConversationBaseInfo *conversationInfo = [[ZIMConversationBaseInfo alloc] init];
conversationInfo.conversationID = @"GroupConv";
conversationInfo.conversationType = ZIMConversationTypeGroup;
[[ZIM getInstance] setConversationMark:markType enable:enable conversationInfos:@[conversationInfo] callback:^(NSArray<ZIMConversationBaseInfo *> * _Nonnull failedConversationInfos, ZIMError * _Nonnull errorInfo) {
if (errorInfo.code == ZIMErrorCodeSuccess) {
// 操作成功的处理
// 注意:即便部分操作成功,部分操作失败,errorCode 仍会为 SUCCESS,且会在 failedConversationInfos 返回操作失败的会话
} else {
// 对所有会话的操作都失败时的处理
}
}];
1
// 以对一个群聊会话设置标签为 1 为例
int markType = 1;
bool enable = true;
auto infos = std::vector<ZIMConversationBaseInfo>({ZIMConversationBaseInfo("conv_id", ZIMConversationType::ZIM_CONVERSATION_TYPE_GROUP)});
zim_->setConversationMark(
markType, enable, infos,
[=](const std::vector<zim::ZIMConversationBaseInfo> &failedConversationList,
const zim::ZIMError &errorInfo) {
// 业务逻辑
});
1
// 以对一个单聊会话和一个群聊会话设置标签为 1 为例
var markType = 1;
var enable = true;
var convList = [
{ conversationID: '单聊', conversationType: 0 },
{ conversationID: '群聊', conversationType: 2 },
];
zim.setConversationMark(markType, enable, convList)
.then((res) => {
// 操作成功,部分失败的会话通过 res.failedConversationInfos 返回
})
.catch((err) => {
// 操作失败
});
1
// 以对一个群聊会话设置标签为 1 为例
int markType = 1;
bool enable = true;
List<ZIMConversationBaseInfo> convList = [];
ZIMConversationBaseInfo conversationBaseInfo = ZIMConversationBaseInfo();
conversationBaseInfo.conversationID = "GroupConv";
conversationBaseInfo.conversationType = ZIMConversationType.group;
convList.add(conversationBaseInfo);
ZIM.getInstance()?.setConversationMark(markType, enable, convList).then((value) {
// 操作成功的处理。
// 注意:即便部分操作成功,部分操作失败,errorCode 仍会为 SUCCESS,且会在 failedConversationInfos 返回操作失败的会话
}).catchError((onError){
if(onError is PlatformException){
// 对所有会话的操作都失败时的处理
}
});
1
服务端 API
开发者可以通过调用服务端 API 批量对多名用户设置或取消会话标记,详情请参考服务端 API 文档 设置会话标记。
按标记查询会话列表
调用 queryConversationList 接口,通过 ZIMConversationFilterOption.marks 传入会话标记列表,即可将标记作为过滤项查询会话列表。
此外,如果查询时需要考虑会话是否存在未读数,在调用 queryConversationList 接口时,传入 isOnlyUnreadConversation
为 true 即可。
// 以查询拥有标记为 1 且包含存在未读数的群聊会话列表为例
ZIMConversationQueryConfig config = new ZIMConversationQueryConfig();
config.count = 100;
config.nextConversation = null; // 首次查询填 null,多次分页查询则传入返回结果中的会话列表中的最后一个
ZIMConversationFilterOption option = new ZIMConversationFilterOption();
option.marks.add(1); // 这里填入需要查询的标记
option.conversationTypes.add(ZIMConversationType.GROUP); // 这里填入需要查询的会话类型,若该列表为空,则同时查询单聊和群聊会话。
option.isOnlyUnreadConversation = true; // 这里填入是否仅查询存在未读数的会话,默认为 false,查询时不考虑会话是否存在未读数
zim.queryConversationList(config, option, new ZIMConversationListQueriedCallback() {
@Override
public void onConversationListQueried(ArrayList<ZIMConversation> conversationList, ZIMError errorInfo) {
if(errorInfo.code == ZIMErrorCode.SUCCESS) {
// 查询成功的处理
} else {
// 查询失败的处理
}
}
});
1
// 以查询拥有标记为 1 且包含存在未读数的群聊会话列表为例
ZIMConversationQueryConfig *config = [[ZIMConversationQueryConfig alloc] init];
config.count = 100;
config.nextConversation = nil; // 首次查询填 nil,多次分页查询则传入返回结果中的会话列表中的最后一个
ZIMConversationFilterOption *option = [[ZIMConversationFilterOption alloc] init];
option.marks = @[@(1)];
option.conversationTypes = @[@(ZIMConversationTypeGroup)];
option.isOnlyUnreadConversation = YES; // 这里填入是否仅查询存在未读数的会话,默认为 NO,查询时不考虑会话是否存在未读数
[zim queryConversationListWithConfig:config
option:option
callback:^(NSArray<ZIMConversation *> *conversationList, ZIMError *errorInfo) {
if (errorInfo.code == ZIMErrorCodeSuccess) {
// 查询成功的处理
} else {
// 查询失败的处理
}
}];
1
// 以查询拥有标记为 1 且包含存在未读数的群聊会话列表为例
zim::ZIMConversationQueryConfig queryConfig;
queryConfig.nextConversation = nullptr; // 首次查询填 nullptr,多次分页查询则传入返回结果中的会话列表中的最后一个
queryConfig.count = 100;
zim::ZIMConversationFilterOption option;
option.marks.push_back(1); // 这里填入需要查询的标记
option.conversationTypes.push_back(ZIMConversationType::ZIM_CONVERSATION_TYPE_GROUP); // 这里填入需要查询的会话类型。若该列表为空,则同时查询单聊和群聊会话。
option.isOnlyUnreadConversation = true; // 这里填入是否仅查询存在未读数的会话,默认为 false,查询时不考虑会话是否存在未读数
zim_sdk_->GetInstance()->queryConversationList(
queryConfig, option,
[=](const std::vector<std::shared_ptr<zim::ZIMConversation>> &conversationList,
const zim::ZIMError &errorInfo) {
// 业务逻辑
});
1
// 以查询拥有标记为 1 且包含存在未读数的会话列表(包含单聊和群聊)为例
var config = { count: 10 };
var option = {
marks: [1],
conversationTypes: [],
isOnlyUnreadConversation: true,
};
zim.queryConversationList(config, option)
.then((res) => {
// 操作成功
})
.catch((err) => {
// 操作失败
});
1
// 以查询拥有标记为 1 且包含存在未读数的群聊会话列表为例
ZIMConversationQueryConfig config = ZIMConversationQueryConfig();
config.count = 100;
config.nextConversation = null; // 首次查询填 null,多次分页查询则传入返回结果中的会话列表中的最后一个
ZIMConversationFilterOption option = ZIMConversationFilterOption();
option.marks.add(1); // 这里填入需要查询的标记
option.conversationTypes.add(ZIMConversationType.group); // 这里填入需要查询的会话类型,若该列表为空,则同时查询单聊和群聊会话。
option.isOnlyUnreadConversation = true; // 这里填入是否仅查询存在未读数的会话,默认为 false,查询时不考虑会话是否存在未读数
ZIM.getInstance()?.queryConversationList(config,option).then((value) {
// 查询成功的处理
}).catchError((onError){
if(onError is PlatformException){
// 查询失败的处理
onError.code;
onError.message;
}
});
1
按标记查询消息未读总数
调用 queryConversationTotalUnreadMessageCount 接口,通过 ZIMConversationTotalUnreadMessageCountQueryConfig.marks 传入会话标记列表,即可按标记查询相关会话的消息未读总数。
// 以查询包含标记为 1 的群聊会话总未读数为例
ZIMConversationTotalUnreadMessageCountQueryConfig config = new ZIMConversationTotalUnreadMessageCountQueryConfig();
config.marks.add(1); // 这里填入需要查询的标记
config.conversationTypes.add(ZIMConversationType.GROUP); // 这里填入需要查询的会话类型。若该列表为空,则同时查询单聊和群聊会话。
zim.queryConversationTotalUnreadMessageCount(config, new ZIMConversationTotalUnreadMessageCountQueriedCallback() {
@Override
public void onConversationTotalUnreadMessageCountQueried(int unreadMessageCount, ZIMError errorInfo) {
if(errorInfo.code == ZIMErrorCode.SUCCESS) {
// 查询成功的处理
} else {
// 查询失败的处理
}
}
});
1
// 以查询包含标记为 1 的群聊会话总未读数为例
ZIMConversationTotalUnreadMessageCountQueryConfig *config = [[ZIMConversationTotalUnreadMessageCountQueryConfig alloc] init];
config.marks =@[@(1)]; // 这里填入需要查询的标记
config.conversationTypes = @[@(ZIMConversationTypeGroup)]; // 这里填入需要查询的会话类型。若该列表为空,则同时查询单聊和群聊会话。
[[ZIM getInstance] queryConversationTotalUnreadMessageCountWithConfig:config callback:^(unsigned int unreadMessageCount, ZIMError * _Nonnull errorInfo) {
if (errorInfo.code == ZIMErrorCodeSUCCESS) {
// 查询成功的处理
} else {
// 查询失败的处理
}
}];
1
// 以查询包含标记为 1 的群聊会话总未读数为例
zim::ZIMConversationTotalUnreadMessageCountQueryConfig queryConfig;
queryConfig.marks.push_back(1); // 这里填入需要查询的标记
queryConfig.conversationTypes.push_back(ZIMConversationType::ZIM_CONVERSATION_TYPE_GROUP); // 这里填入需要查询的会话类型。若该列表为空,则同时查询单聊和群聊会话。
zim_sdk_->GetInstance()->queryConversationTotalUnreadMessageCount(
queryConfig, [=](unsigned int totalUnreadCount, const zim::ZIMError &errorInfo) {
// 业务逻辑
});
1
// 以查询包含标记为 1 的会话总未读数(包含单聊和群聊)为例
var config = {
marks: [1],
conversationTypes: [],
};
zim.queryConversationTotalUnreadMessageCount(config)
.then((res) => {
// 操作成功
})
.catch((err) => {
// 操作失败
});
1
// 以查询包含标记为 1 的群聊会话总未读数为例
ZIMConversationTotalUnreadMessageCountQueryConfig config = ZIMConversationTotalUnreadMessageCountQueryConfig();
config.marks.add(1); // 这里填入需要查询的标记
config.conversationTypes.add(ZIMConversationType.group); // 这里填入需要查询的会话类型。若该列表为空,则同时查询单聊和群聊会话。
ZIM.getInstance()?.queryConversationTotalUnreadMessageCount(config).then((value) {
// 查询成功的处理
}).catchError((onError){
if(onError is PlatformException){
// 查询失败的处理
}
});
1