跳到主要内容

聊天室属性管理（KV）

SDK 在聊天室业务核心类 RongChatRoomClient 中提供了聊天室属性（KV）管理接口（也可以使用 RongIMClient），用于在指定聊天室中设置自定义属性。

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

开通服务​

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

聊天室业务还提供服务端回调功能，支持由融云服务端将应用下的全部聊天室属性变化（设置，删除，全部删除等操作）同步到您指定的地址，方便 App 业务服务端了解聊天室属性变化。详见服务端文档聊天室属性同步（KV）。

功能局限​

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

监听聊天室属性变化​

SDK 在聊天室业务核心类 RongChatRoomClient 中提供了 KVStatusListener，用于监听聊天室属性（KV）变化。您也可以使用 RongIMClient 下的同名接口类。

返回值方法说明
voidonChatRoomKVSync(String roomId)聊天室 KV 列表同步完成时触发。
voidonChatRoomKVUpdate(String roomId, Map<String, String> chatRoomKvMap)聊天室 KV 列表更新完成时触发，首次同步 KV 时返回全量 KV，后续触发时仅返回新增、修改的 KV。
voidonChatRoomKVRemove(String roomId, Map<String, String> chatRoomKvMap)KV 被删除时触发。

  • onChatRoomKVSync(String roomId)

    触发时机：加入聊天室成功后，SDK 默认从服务端同步 KV 列表，同步完成后触发。

    参数类型说明
    roomIdString聊天室 Id

  • onChatRoomKVUpdate(String roomId, Map<String, String> chatRoomKvMap)

    触发时机：聊天室 KV 更新时。

    如果刚进入聊天室时存在 KV，会通过此回调将所有 KV 返回，再次回调时为其他人设置或者修改 KV 的增量数据。

    参数类型说明
    roomIdString聊天室 Id
    chatRoomKvMapMap<String, String>发生变化的聊天室 KV

  • onChatRoomKVRemove(String roomId, Map<String, String> chatRoomKvMap)

    触发时机：KV 被删除时触发。

    参数类型说明
    roomIdString聊天室 Id
    chatRoomKvMapMap<String, String>被删除的聊天室 KV

添加聊天室 KV 监听器​

使用 addKVStatusListener 方法，添加聊天室 KV 监听器 KVStatusListener。支持设置多个监听器。为了避免内存泄露，请在不需要监听时将监听器移除。

RongChatRoomClient.getInstance().addKVStatusListener(listener);

移除聊天室 KV 监听器​

SDK 支持移除监听器。为了避免内存泄露，请在不需要监听时将监听器移除。

RongChatRoomClient.getInstance().removeKVStatusListener(listener);

获取单个属性​

通过属性的 Key 获取指定聊天室中的单个属性 KV。

String chatRoomId = "聊天室 ID";
String key = "name";

RongChatRoomClient.getInstance().getChatRoomEntry(chatRoomId, key, new IRongCoreCallback.ResultCallback<Map<String, String>>() {
        @Override
        public void onSuccess(Map<String, String> stringStringMap) {

            }

        @Override
        public void onError(IRongCoreEnum.CoreErrorCode e) {

           }
 });
参数类型说明
chatRoomIdString聊天室 ID
keyString聊天室属性名称,Key 支持大小写英文字母、数字、部分特殊符号 + = - _ 的组合方式，最大长度 128 个字符
callbackResultCallback<Map<String, String>>回调接口

获取所有属性​

获取指定聊天室中所有属性 KV 对。

String chatRoomId = "聊天室 ID";

RongChatRoomClient.getInstance().getAllChatRoomEntries(chatRoomId, new IRongCoreCallback.ResultCallback<Map<String, String>>() {
         @Override
         public void onSuccess(Map<String, String> stringStringMap) {

            }

          @Override
         public void onError(IRongCoreEnum.CoreErrorCode e) {

            }
        });
参数类型说明
chatRoomIdString聊天室 ID
callbackResultCallback<Map<String, String>>回调接口

设置单个属性​

在指定单个聊天室中设置单个属性 KV 对。注意，该接口不支持更新已存在的属性。

String chatRoomId = "聊天室 ID";
String key = "name";
String value = "融融";
boolean sendNotification = true;
boolean isAutoDel = false;
String notificationExtra = "通知消息扩展";

RongChatRoomClient.getInstance().setChatRoomEntry(chatRoomId, key, value, sendNotification, isAutoDel, notificationExtra, new IRongCoreCallback.OperationCallback() {

    @Override
    public void onSuccess() {

    }

    @Override
    public void onError(IRongCoreEnum.CoreErrorCode coreErrorCode) {

    }
});

在设置 KV 时，可指定 SDK 发送一条聊天室属性通知消息（ChatRoomKVNotiMessage）。消息内容结构说明可参见通知类消息格式。

参数类型说明
chatRoomIdString聊天室 ID
keyString聊天室属性名称，Key 支持大小写英文字母、数字、部分特殊符号 + = - _ 的组合方式，最大长度 128 个字符
valueString聊天室属性对应的值，最大长度 4096 个字符
sendNotificationbooleantrue 发送通知; false 不发送。如果发送通知，SDK 会接收到类型标识为 RC:chrmKVNotiMsg 的聊天室属性通知消息（ChatRoomKVNotiMessage），并且消息内容中包含 K，V
autoDeleteboolean退出后是否删除
notificationExtraString通知的自定义字段，RC:chrmKVNotiMsg(ChatRoomKVNotiMessage), 通知消息中会包含此字段，最大长度 2048 个字符
callbackOperationCallback回调接口

强制设置单个属性​

强制设置聊天室属性。以 key = value 的形式存储。当 key 不存在时，代表增加属性。当 key 已经存在时，代表更新属性的值。使用强制设置可修改他人创建的属性值。

String chatRoomId = "聊天室 ID";
String key = "name";
String value = "融融";
boolean sendNotification = true;
boolean isAutoDel = false;
String notificationExtra = "通知消息扩展";

RongChatRoomClient.getInstance().forceSetChatRoomEntry(chatRoomId, key, value, sendNotification, isAutoDel, notificationExtra, new IRongCoreCallback.OperationCallback() {

    @Override
    public void onSuccess() {

    }


    @Override
    public void onError(IRongCoreEnum.CoreErrorCode coreErrorCode) {

    }
});

在设置 KV 时，可指定 SDK 发送一条聊天室属性通知消息（ChatRoomKVNotiMessage）。消息内容结构说明可参见通知类消息格式。

参数类型说明
chatRoomIdString聊天室 ID
keyString聊天室属性名称,Key 支持大小写英文字母、数字、部分特殊符号 + = - _ 的组合方式，最大长度 128 个字符
valueString聊天室属性对应的值，最大长度 4096 个字符
sendNotificationbooleantrue 发送通知; false 不发送. 如果发送通知，SDK 会接收到 RC:chrmKVNotiMsg 通知消息 ChatRoomKVNotiMessage，并且消息内容中包含 K，V
autoDeleteboolean退出后是否删除
notificationExtraString通知的自定义字段，类型标识为 RC:chrmKVNotiMsg 的 ChatRoomKVNotiMessage 通知消息中会包含此字段，最大长度 2048 个字符
callbackOperationCallback回调接口

批量设置属性​

批量设置聊天室属性。通过 isForce 参数可控制是否强制覆盖他人设置的属性。

RongChatRoomClient.getInstance().setChatRoomEntries(chatRoomId, chatRoomEntryMap, isAutoDel, isForce, new IRongCoreCallback.SetChatRoomKVCallback() {
    /**
     * 成功回调
     */
    @Override
    public void onSuccess() {

    }

    /**
     * 失败回调
     * @param errorCode
     * @param map
     */
    @Override
    public void onError(IRongCoreEnum.CoreErrorCode errorCode, Map<String, IRongCoreEnum.CoreErrorCode> map) {

    }
});
参数类型说明
chatRoomIdString聊天室 ID
chatRoomEntryMapMapchatRoomEntryMap集合size最大限制为10,超过限制返回错误码 KV_STORE_OUT_OF_LIMIT (23429)
isAutoDelboolean用户掉线或退出时，是否自动删除该 Key、Value 值
isForceboolean是否强制覆盖
callbackSetChatRoomKVCallback回调接口

如果部分失败，SDK 会触发 SetChatRoomKVCallback 的 onError 回调方法：

回调参数回调类型说明
errorCodeCoreErrorCode错误码
mapMap当 errorCode 为 KV_STORE_NOT_ALL_SUCCESS（23428）时,map 才会有值（key 为设置失败的 key，value 为该 key 对应的错误码）

删除单个属性​

删除指定单个聊天室的单个属性。该接口仅支持删除当前用户所创建的属性。

String chatRoomId = "聊天室 ID";
String key = "name";
boolean sendNotification = true;
String notificationExtra = "通知消息扩展";

RongChatRoomClient.getInstance().removeChatRoomEntry(chatRoomId, key, sendNotification, notificationExtra, new IRongCoreCallback.OperationCallback() {

    @Override
    public void onSuccess() {

    }


    @Override
   public void onError(IRongCoreEnum.CoreErrorCode coreErrorCode) {

    }
});

在删除 KV 时，可指定 SDK 发送一条聊天室属性通知消息（ChatRoomKVNotiMessage）。消息内容结构说明可参见通知类消息格式。

参数类型说明
chatRoomIdString聊天室 ID
keyString聊天室属性名称,Key 支持大小写英文字母、数字、部分特殊符号 + = - _ 的组合方式，最大长度 128 个字符
sendNotificationbooleantrue 发送通知; false 不发送. 如果发送通知，SDK 会接收到 RC:chrmKVNotiMsg 通知消息 ChatRoomKVNotiMessage，并且消息内容中包含 K，V
notificationExtraString通知的自定义字段，类型标识为 RC:chrmKVNotiMsg 的 ChatRoomKVNotiMessage 通知消息中会包含此字段，最大长度 2048 个字符
callbackOperationCallback回调接口

强制删除单个属性​

强制删除指定单个聊天室的单个属性。可删除他人所创建的属性。

String chatRoomId = "聊天室 ID";
String key = "name";
boolean sendNotification = true;
String notificationExtra = "通知消息扩展";

RongChatRoomClient.getInstance().forceRemoveChatRoomEntry(chatRoomId, key, sendNotification, notificationExtra, new IRongCoreCallback.OperationCallback() {

    @Override
    public void onSuccess() {

    }

    @Override
    public void onError(IRongCoreEnum.CoreErrorCode coreErrorCode) {

    }
});

在强制删除 KV 时，可指定 SDK 发送一条聊天室属性通知消息（ChatRoomKVNotiMessage）。消息内容结构说明可参见通知类消息格式。

参数类型说明
chatRoomIdString聊天室 ID
keyString聊天室属性名称，Key 支持大小写英文字母、数字、部分特殊符号 + = - _ 的组合方式，最大长度 128 个字符。
sendNotificationbooleantrue 发送通知; false 不发送. 如果发送通知，SDK 会接收到 RC:chrmKVNotiMsg 通知消息 ChatRoomKVNotiMessage，并且消息内容中包含 KV。
notificationExtraString通知的自定义字段，类型标识为 RC:chrmKVNotiMsg 的 ChatRoomKVNotiMessage 通知消息中会包含此字段，最大长度 2048 个字符。
callbackOperationCallback回调接口

批量删除属性​

从指定单个聊天室中批量删除属性。单次最多删除 10 个属性。通过 isForce 参数可控制是否强制删除他人设置的属性。

RongChatRoomClient.getInstance().deleteChatRoomEntries(chatRoomId, keys, isForce, new IRongCoreCallback.SetChatRoomKVCallback() {
    /**
     * 成功回调
     */
    @Override
    public void onSuccess() {

    }

    /**
     * 失败回调
     * @param errorCode 错误码
     */
    @Override
    public void onError(IRongCoreEnum.CoreErrorCode errorCode, Map<String, IRongCoreEnum.CoreErrorCode> map) {

    }
});
参数类型必填说明
chatRoomIdString是聊天室 ID
keysList是聊天室属性名称集合，集合 size 最大限制 10
isForceboolean是是否强制覆盖
callbackSetChatRoomKVCallback是回调接口

如果部分失败，SDK 会触发 SetChatRoomKVCallback 的 onError 回调方法：

回调参数回调类型说明
errorCodeCoreErrorCode错误码
mapMap<String, IRongCoreEnum.CoreErrorCode>当 errorCode 为 KV_STORE_NOT_ALL_SUCCESS（23428）时,map 才会有值（key 为设置失败的 key，value 为该 key 对应的错误码）
最后于 更新