设置属性

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

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

功能局限

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

开通服务

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

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

设置属性

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

API 参考：setChatroomEntry

参数说明

参数	类型	必填	说明	最低版本
chatRoomId	String	是	聊天室 ID	2.5.3
chatroomEntry	Object	是	设置的属性信息	2.5.3

chatroomEntry 说明：

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

代码示例

JavaScript

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 进行强制设置，但一次仅能强制设置一个属性。

参数说明

参数	类型	必填	说明	最低版本
chatRoomId	String	是	聊天室 ID	2.10.0
options	Object	是	设置的属性信息	2.10.0

options 说明：

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

代码示例

JavaScript

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

参数说明

参数	类型	必填	说明	最低版本
chatRoomId	String	是	聊天室 ID	2.5.3
chatroomEntry	Object	是	设置的属性信息	2.5.3

chatroomEntry 说明：

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

代码示例

JavaScript

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);
  }
});