跳到主要内容
版本：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
notificationExtraString否RC: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
notificationExtraString否RC: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);
  }
});
最后于 更新