会话标签
SDK 2.X 版本从 2.8.0 开始支持会话标签功能。
会话标签用于对会话进行分组。用户可设置会话标签,用于会话的分组显示。
每个用户最多可以创建 20 个标签,每个标签下最多可以添加 1000 个会话。同一个会话可以设置多个不同的标签。
管理标签
SDK 支持创建标签、编辑标签,获取标签列表,以及移除标签。SDK 创建的标 签可用于对会话进行管理。
SDK 创建的标签会被同步到服务端。
关于如何使用标签管理会话,详见使用标签管理会话。
创建标签
每个用户最多可以创建 20 个标签。
API 参考:createTag
参数说明
参数 | 类型 | 必填 | 说明 |
---|---|---|---|
tag | Object | 是 | 标签信息 |
tag.tagId | String | 是 | 标签 Id,标签唯一标识,长度不超过 10 个字 |
tag.tagName | String | 是 | 标签名称,长度不超过 15 个字 |
callback | Object | 是 | 回调对象 |
callback.onSuccess | Function | 是 | 成功回调 |
callback.onError | Function | 是 | 失败回调 |
代码示例
var tag = {
tagId: '<标签Id>',
tagName: '<新的标签名字>'
}
var callback = {
onSuccess: function() {
console.log('创建标签成功')
},
onError: function(error) {
console.log('创建标签失败', error)
}
}
RongIMClient.getInstance().createTag(tag,callback)
移除标签
API 参考:removeTag
参数说明
参数 | 类型 | 必填 | 说明 |
---|---|---|---|
tagId | String | 是 | 标签 Id |
callback | Object | 是 | 回调对象 |
callback.onSuccess | Function | 是 | 成功回调 |
callback.onError | Function | 是 | 失败回调 |
代码示例
var tagId = '<标签Id>'
var callback = {
onSuccess: function() {
console.log('删除标签成功')
},
onError: function(error) {
console.log('删除标签失败', error)
}
}
RongIMClient.getInstance().removeTag(tagId,callback)
编辑标签
参数说明
参数 | 类型 | 必填 | 说明 |
---|---|---|---|
tag | Object | 是 | 标签信息 |
tag.tagId | String | 是 | 标签 Id,标签唯一标识,长度不超过 10 个字 |
tag.tagName | String | 是 | 标签名称,长度不超过 15 个字 |
callback | Object | 是 | 回调对象 |
callback.onSuccess | Function | 是 | 成功回调 |
callback.onError | Function | 是 | 失败回调 |
代码示例
var tag = {
tagId: '<标签Id>',
tagName: '<新的标签名字>'
}
var callback = {
onSuccess: function() {
console.log('编辑标签成功')
},
onError: function(error) {
console.log('编辑标签失败', error)
}
}
RongIMClient.getInstance().updateTag(tag,callback)
获取标签列表
API 参考:getTagList
参数说明
参数 | 类型 | 必填 | 说明 |
---|---|---|---|
callback | Object | 是 | 回调对象 |
callback.onSuccess | Function | 是 | 成功回调 |
callback.onError | Function | 是 | 失败回调 |
成功回调
成功回调 ITagInfo[]
的参数说明:
参数 | 返回类型 | 说明 |
---|---|---|
tagInfo | ITagInfo[] | 标签列表信息,详见下方 ITagInfo 属性说明 |
-
ITagInfo
属性说明参数 类型 说明 tagId String 标签 Id tagName String 标签名称 conversationCount Number 标签下的会话数量 createdTime Number 标签创建的时间戳
代码示例
var callback = {
onSuccess: function(tagInfo) {
console.log(tagInfo)
console.log('获取标签列表成功')
},
onError: function(error) {
console.log('获取标签列表失败', error)
}
}
RongIMClient.getInstance().getTagList(callback)
用户标签多端同步
该回调不会给当前操作设备回调,只会给其他的多端设备回调。
代码示例
/**
* 设置会话标签更改时的回调
* 当用户在其它端添加移除更新标签时会触发此监听器,用于多端之间的信息同步。
* 收到此回调,可调用 getTagList 获取最新标签信息
* 请在初始化之后,连接之前调用该方法
*/
var tagListener = {
onChanged:function(){
return
}
}
RongIMClient.setTagListener(tagListener)
使用标签管理会话
SDK 支持使用一个或多个标签标记会话,可用于会话的分组显示、获取会话列表等操作,并提供了多个接口用于移除会话上的标签。
会话标签还支持一系列高级功能,包括按照标签获取会话列表、按照标签获取标签下所有会话的消息未读数,以及在特定标签下设置某个会话置顶。
添加会话到一个标签
每个标签下最多可以添加 1000 个会话。
API 参考:addTagForConversations
参数说明
参数 | 类型 | 必填 | 说明 |
---|---|---|---|
tagId | String | 是 | 标签信息 |
conversations | IConversationOption [] | 是 | 要添加的会话列表。详见下方 IConversationOption 属性说明。 |
callback | Object | 是 | 回调对象 |
callback.onSuccess | Function | 是 | 成功回调 |
callback.onError | Function | 是 | 失败回调 |
-
IConversationOption
属性说明参数 类型 必填 说明 type Number 是 会话类型 targetId String 是 目标 ID
代码示例
var tag = {
tagId: '<标签Id>',
tagName: '<新的标签名字>'
}
var callback = {
onSuccess: function() {
console.log('添加成功')
},
onError: function(error) {
console.log('添加失败', error)
}
}
var conversations =[{
type:1,//会话类型
targetId:'<目标Id>'
}
]
RongIMClient.getInstance().addTagForConversations(tagId,conversations,callback)
删除指定标签中某些会话
removeTagForConversations
接口可从特定标签下移除指定多个会话,也可以理解为“为多个会话移除单个标签”。
API 参考:removeTagForConversations
参数说明
参数 | 类型 | 必填 | 说明 |
---|---|---|---|
tagId | String | 是 | 标签 Id |
conversations | IConversationOption [] | 是 | 要从指定标签下删除的会话列表。详见下方 IConversationOption 属性说明。 |
callback | Object | 是 | 回调对象 |
callback.onSuccess | Function | 是 | 成功回调 |
callback.onError | Function | 是 | 失败回调 |
-
IConversationOption
属性说明参数 类型 必填 说明 type Number 是 会话类型 targetId String 是 目标 ID
代码示例
var tagId = '<标签Id>'
var callback = {
onSuccess: function() {
console.log('删除成功')
},
onError: function(error) {
console.log('删除失败', error)
}
}
var conversations =[{
type:1,//会话类型
targetId:'<目标Id>'
}]
RongIMClient.getInstance().removeTagForConversations(tagId,conversations,callback)
删除指定会话中的某些标签
removeTagsForConversation
接口可为特定会话移除指定的一个或多个标签。
API 参考:removeTagsForConversation
参数说明
参数 | 类型 | 必填 | 说明 |
---|---|---|---|
conversation | IConversationOption | 是 | 会话。详见下方 IConversationOption 属性说明。 |
tagIds | Array | 是 | 所有标签 |
callback | Object | 是 | 回调对象 |
callback.onSuccess | Function | 是 | 成功回调 |
callback.onError | Function | 是 | 失败回调 |
-
IConversationOption
属性说明。参数 类型 必填 说明 type Number 是 会话类型 targetId String 是 目标 ID
代码示例
var tagIds = ['<标签Id>']
var callback = {
onSuccess: function() {
console.log('删除成功')
},
onError: function(error) {
console.log('删除失败', error)
}
}
var conversation ={
type:1,//会话类型
targetId:'<目标Id>'
}
RongIMClient.getInstance().removeTagsForConversation(conversation,tagIds,callback)
获取指定会话下的所有标签
API 参考:getTagsForConversation
参数说明
参数 | 类型 | 必 填 | 说明 |
---|---|---|---|
conversation | IConversationOption | 是 | 会话。详见下方 IConversationOption 属性说明。 |
callback | Object | 是 | 回调对象 |
callback.onSuccess | Function | 是 | 成功回调 |
callback.onError | Function | 是 | 失败回调 |
-
IConversationOption
属性说明。参数 类型 必填 说明 type Number 是 会话类型 targetId String 是 目标 ID
成功回调
成功回调 IConversationTag
的参数说明:
参数 | 返回类型 | 说明 |
---|---|---|
tagId | String | 标签 Id |
tagName | String | 标签名称 |
createdTime | Number | 标签创建的时间戳 |
isTop | Boolean | 是否置顶 |
代码示例
var conversation ={
type:1,//会话类型
targetId:'<目标Id>'
}
var callback = {
onSuccess: function(IConversationTag) {
console.log('获取成功',IConversationTag)
},
onError: function(error) {
console.log('获取失败', error)
}
}
RongIMClient.getInstance().getTagsForConversation(conversation,callback)
分页获取指定标签下的会话列表
getConversationListByTag
可从服务端分页获取会话列表,并返回分页查询结果中带有指定标签的会话。
API 参考:getConversationListByTag
参数说明
参数 | 类型 | 必填 | 说明 |
---|---|---|---|
tagId | String | 是 | 标签 Id |
count | Number | 是 | 单次分页查询时需要从服务端获取的会话数量 |
startTime | Number | 是 | 会话中最后一条消息时间戳 |
callback | Object | 是 | 回调对象 |
callback.onSuccess | Function | 是 | 成功回调 |
callback.onError | Function | 是 | 失败回调 |
代码示例
var tagId = '<标签Id>'
var count = 10
var startTime = 1649404018538
var callback = {
onSuccess: function(IV2ConversationContainTag) {
console.log('获取成功后会话列表',IV2ConversationContainTag)
},
onError: function(error) {
console.log('获取失败', error)
}
}
RongIMClient.getInstance().getConversationListByTag(tagId,count,startTime,callback)
按标签获取未读消息数
API 参考:getUnreadCountByTag
参数说明
参数 | 类型 | 必填 | 说明 |
---|---|---|---|
tagId | String | 是 | 标签 Id |
containMuted | Number | 是 | 是否包含已设置为免打扰状态的会话 |
callback | Object | 是 | 回调对象 |
callback.onSuccess | Function | 是 | 成功回调 |
callback.onError | Function | 是 | 失败回调 |
成功回调
成功回调参数说明:
参数 | 返回类型 | 说明 |
---|---|---|
count | Number | 获取未读消息数 |
代码示例
var tagId = '<标签Id>'
var containMuted = true
var callback = {
onSuccess: function(count) {
console.log('成功获取未读消息数',count)
},
onError: function(error) {
console.log('获取失败', error)
}
}
RongIMClient.getInstance().getUnreadCountByTag(tagId,containMuted,callback)
设置标签中会话置顶
setConversationStatusInTag
可设置会话在标签下为置顶状态。
设置成功后,可在分页获取指定标签下会话列表(getConversationListByTag
)返回的结果中查看相关属性。
- 注意,
setConversationStatusInTag
接口仅用于在特定标签下会话是否置顶。- 如需设置会话在会话列表中置顶,请使用
setConversationStatus
接口(SDK ≧ 2.5.8)。
API 参考:setConversationStatusInTag
参数说明
参数 | 类型 | 必填 | 说明 |
---|---|---|---|
tagId | String | 是 | 标签 Id |
conversation | IConversationOption | 是 | 会话。详见下方 IConversationOption 属性说明。 |
status | Object | 是 | 置顶状态 |
status.isTop | Boolean | 是 | 是否置顶 |
callback | Object | 是 | 回调对象 |
callback.onSuccess | Function | 是 | 成功回调 |
callback.onError | Function | 是 | 失败回调 |
-
IConversationOption
属性说明参数 类型 必填 说明 type Number 是 会话类型 targetId String 是 目标 ID
代码示例
var tagId = '<标签Id>'
var conversation ={
type:1,//会话类型
targetId:'<目标Id>'
}
let status = {
isTop:true
}
var callback = {
onSuccess: function() {
console.log('设置成功')
},
onError: function(error) {
console.log('设置失败', error)
}
}
RongIMClient.getInstance().setConversationStatusInTag(tagId,conversation,status,callback)
用户会话标签多端同步
该回调不会给当前操作设备回调,只会给其他的多端设备回调。
代码示例
var tagListener = {
onChanged:function(){
return
}
}
RongIMClient.setConversationTagListener(tagListener)