设置属性
聊天室属性(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 |
代码示例
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 |
代码示例
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 |
代码示例
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);
}
});