跳到主要内容

聊天室属性管理(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:chrmKVNotiMsgChatRoomKVNotiMessage 通知消息中会包含此字段,最大长度 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 会触发 SetChatRoomKVCallbackonError 回调方法:

回调参数回调类型说明
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:chrmKVNotiMsgChatRoomKVNotiMessage 通知消息中会包含此字段,最大长度 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:chrmKVNotiMsgChatRoomKVNotiMessage 通知消息中会包含此字段,最大长度 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 会触发 SetChatRoomKVCallbackonError 回调方法:

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