跳到主要内容

版本:2.X

设置属性

聊天室属性(KV)管理接口用于在指定聊天室中设置自定义属性。

在语音直播聊天室场景中,可利用此功能记录聊天室中各麦位的属性;或在狼人杀等卡牌类游戏场景中记录用户的角色和牌局状态等。

功能局限

  • 聊天室销毁后,聊天室中的自定义属性同时销毁。
  • 每个聊天室中,最多允许设置 100 个属性信息,以 Key-Value 的方式进行存储。
  • 客户端 SDK 未针对聊天室属性 KV 的操作频率进行限制。建议每个聊天室,每秒钟操作 Key-Value 频率保持在 100 次及以下(一秒内单次操作 100 个 KV 等同于操作 100 次)。

开通服务

使用聊天室属性(KV)接口要求开通聊天室属性自定义设置服务。您可以前往控制台的免费基础功能页面开启服务。

如果配置了服务端回调 URL,融云服务端会将应用下的聊天室属性变化(设置,删除,全部删除等操作)同步到指定的回调地址。详见服务端文档聊天室属性同步(KV)

设置属性

仅聊天室中不存在此属性 或 属性设置者为自己时, 可设置成功

API 参考:setChatroomEntry

参数说明

参数类型必填说明最低版本
chatRoomIdString聊天室 ID2.5.3
chatroomEntryObject设置的属性信息2.5.3

chatroomEntry 说明:

参数类型必填说明最低版本
keyString属性名称, 支持英文字母、数字、+、=、-、_ 的组合方式, 最大长度 128 字符2.5.3
valueObject属性对应的值, 最大长度 4096 字符2.5.3
isSendNotificationBoolean设置成功后是否发送通知消息2.5.3
notificationExtraStringRC:chrmKVNotiMsg 消息中携带的附加信息2.5.3
isAutoDeleteBoolean用户退出聊天室时是否清除此属性2.5.3

代码示例

var chatRoomId = 'chatroom1';
var key = 'role';
var value = 'Werewolf';
var chatroomEntry = {
key: key,
value: value,
isAutoDelete: false,
isSendNotification: true,
notificationExtra: 'Change role'
};
RongIMClient.getInstance().setChatroomEntry(chatRoomId, chatroomEntry, {
onSuccess: function() {
console.log('设置聊天室属性成功');
},
onError: function(error) {
// 请检查: 是否开通聊天室属性自定义服务
console.log('设置聊天室属性失败', error);
}
});

批量设置属性

对聊天室属性进行批量设置。注意,仅在以下情况下允许批量设置:

  • 聊天室中不存在任何当前需要设置的属性。
  • 如果当前需要设置的任何属性在聊天室中已存在,仅当这些属性设置者为本人时可修改,否则会设置失败。

如果设置失败,您可以使用下面的方法 forceSetEntry 进行强制设置,但一次仅能强制设置一个属性。

参数说明

参数类型必填说明最低版本
chatRoomIdString聊天室 ID2.10.0
optionsObject设置的属性信息2.10.0

options 说明:

参数类型必填说明最低版本
entriesObject属性集合,属性名称, 支持英文字母、数字、+、=、-、_ 的组合方式, 最大长度 128 字符,属性对应的值, 最大长度 4096 字符2.10.0
isAutoDeleteBoolean用户退出聊天室时是否清除此属性2.10.0

代码示例

var chatRoomId = 'chatroom1';
var options = {
entries: {
name: 'name'
}
isAutoDelete: true
}
RongIMClient.getInstance().setChatRoomEntries(chatRoomId, chatroomEntry, {
onSuccess: function() {
console.log('批量设置聊天室属性成功');
},
onError: function(error) {
// 请检查: 是否开通聊天室属性自定义服务
console.log('批量设置聊天室属性失败', error);
}
});

强制设置属性

强制修改/创建任意聊天室属性

API 参考:forceSetChatroomEntry

参数说明

参数类型必填说明最低版本
chatRoomIdString聊天室 ID2.5.3
chatroomEntryObject设置的属性信息2.5.3

chatroomEntry 说明:

参数类型必填说明最低版本
keyString属性名称, 支持英文字母、数字、+、=、-、_ 的组合方式, 最大长度 128 字符2.5.3
valueObject属性对应的值, 最大长度 4096 字符2.5.3
isSendNotificationBoolean设置成功后是否发送通知消息.2.5.3
notificationExtraStringRC:chrmKVNotiMsg 消息中携带的附加信息2.5.3
isAutoDeleteBoolean用户退出聊天室时是否清除此属性2.5.3

代码示例

var chatRoomId = 'chatroom1';
var key = 'count';
var value = '8';
var chatroomEntry = {
key: key,
value: value,
isAutoDelete: false,
isSendNotification: true,
notificationExtra: 'Change Count'
};
RongIMClient.getInstance().forceSetChatroomEntry(chatRoomId, chatroomEntry, {
onSuccess: function() {
console.log('强制设置聊天室属性成功');
},
onError: function(error) {
// 请检查: 是否开通聊天室属性自定义服务
console.log('强制设置聊天室属性失败', error);
}
});