跳到主要内容

聊天室属性管理（KV）

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

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

开通服务​

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

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

功能局限​

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

监听聊天室属性变化​

SDK 在聊天室业务核心类 RCChatRoomClient 中提供了 RCChatRoomKVStatusChangeDelegate 协议，用于监听聊天室属性（KV）变化。

实现此功能需要开发者遵守 RCChatRoomKVStatusChangeDelegate 协议。

@protocol RCChatRoomKVStatusChangeDelegate <NSObject>

/**
 IMLib 刚加入聊天室时 KV 同步完成的回调

 @param roomId 聊天室 Id
 */
- (void)chatRoomKVDidSync:(NSString *)roomId;

/**
 IMLib 聊天室 KV 变化的回调

 @param roomId 聊天室 Id
 @param entry KV 字典，如果刚进入聊天室时存在  KV，会通过此回调将所有 KV 返回，再次回调时为其他人设置或者修改 KV
 */
- (void)chatRoomKVDidUpdate:(NSString *)roomId entry:(NSDictionary<NSString *, NSString *> *)entry;

/**
 IMLib 聊天室 KV 被删除的回调

 @param roomId 聊天室 Id
 @param entry KV 字典
 */
- (void)chatRoomKVDidRemove:(NSString *)roomId entry:(NSDictionary<NSString *, NSString *> *)entry;

@end

设置聊天室 KV 监听器​

设置聊天室 KV 监听器代理。为了避免内存泄露，请在不需要监听时将监听器移除。

使用 addChatRoomKVStatusChangeDelegate 方法，支持设置多个监听器：

[[RCChatRoomClient sharedChatRoomClient] addChatRoomKVStatusChangeDelegate:self];

移除聊天室 KV 监听器​

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

使用 removeChatRoomKVStatusChangeDelegate：

[[RCChatRoomClient sharedChatRoomClient] removeChatRoomKVStatusChangeDelegate:self];

获取单个属性​

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

[[RCChatRoomClient sharedChatRoomClient] getChatRoomEntry:chatroomId
                                            key:key
                                        success:^(NSDictionary *entry) {

                                        } error:^(RCErrorCode nErrorCode) {

                                        }];
参数类型说明
chatroomIdNSString聊天室 ID，最大长度为 64 个字符
keyNSString聊天室属性名称
successBlockBlock成功的回调。entry 中返回 NSDictionary 类型的属性内容。
errorBlockBlock失败的回调。status 中返回错误码 RCErrorCode。

获取所有属性​

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

[[RCChatRoomClient sharedChatRoomClient] getAllChatRoomEntries:self.roomId
                                             success:^(NSDictionary *entry) {

                                             } error:^(RCErrorCode nErrorCode) {

                                             }];
参数类型说明
chatroomIdNSString聊天室 ID，最大长度为 64 个字符。
successBlockBlock成功的回调。entry 中返回 NSDictionary 类型的属性内容。
errorBlockBlock失败的回调。status 中返回错误码 RCErrorCode。

设置单个属性​

设置聊天室自定义属性，当 key 不存在时，代表增加属性； 当 key 已经存在时，代表更新属性的值，且只有 key 的创建者可以更新属性的值。

[[RCChatRoomClient sharedChatRoomClient] setChatRoomEntry:chatroomId
                                            key:key
                                          value:value
                               sendNotification:isNotice
                                     autoDelete:isDelete
                              notificationExtra:extra
                                        success:^{

                                        } error:^(RCErrorCode nErrorCode) {

                                        }];

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

参数类型说明
chatroomIdNSString聊天室 ID，最大长度为 64 个字符。
keyNSString聊天室属性名称，Key 支持大小写英文字母、数字、部分特殊符号 + = - _ 的组合方式，最大长度 128 个字符
valueNSString聊天室属性对应的值，最大长度 4096 个字符
sendNotificationBOOL是否需要发送通知
autoDeleteBOOL用户掉线或退出时，是否自动删除该 Key、Value 值；自动删除时不会发送通知
notificationExtraNSString通知的自定义字段，聊天室属性通知消息 RCChatroomKVNotificationMessage 中会包含此字段，最大长度 2048 个字符
successBlockBlock成功的回调
errorBlockBlock失败的回调。status 中返回错误码 RCErrorCode。

强制设置单个属性​

强制设置聊天室自定义属性，当 key 不存在时，代表增加属性； 当 key 已经存在时，代表更新属性的值。

[[RCChatRoomClient sharedChatRoomClient] forceSetChatRoomEntry:chatroomId
                                                key:key
                                              value:value
                                   sendNotification:isNotice
                                         autoDelete:isDelete
                                  notificationExtra:extra
                                            success:^{

                                            } error:^(RCErrorCode nErrorCode) {

                                            }];

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

参数类型说明
chatroomIdNSString聊天室 ID，最大长度为 64 个字符。
keyNSString聊天室属性名称，Key 支持大小写英文字母、数字、部分特殊符号 + = - _ 的组合方式，最大长度 128 个字符
valueNSString聊天室属性对应的值，最大长度 4096 个字符
sendNotificationBOOL是否需要发送通知
autoDeleteBOOL用户掉线或退出时，是否自动删除该 Key、Value 值；自动删除时不会发送通知
notificationExtraNSString通知的自定义字段，聊天室属性通知消息 RCChatroomKVNotificationMessage 中会包含此字段，最大长度 2048 个字符
successBlockBlock成功的回调
errorBlockBlock失败的回调。status 中返回错误码 RCErrorCode。

批量设置属性​

提示

IMLib 从 5.1.4 版本开始支持该接口。

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

NSDictionary *entries = @{@"key1":@"value1", @"key2":@"value2"};
[[RCChatRoomClient sharedChatRoomClient] setChatRoomEntries:chatroomId
                                                    entries:entries
                                                    isForce:isForce
                                                 autoDelete:isDelete
                                                    success:^{

                                                    } error:^(RCErrorCode nErrorCode) {

 }];
参数类型说明
chatroomIdNSString聊天室 ID，最大长度为 64 个字符。
entriesNSDictionary聊天室属性，字典中 key 支持大小写英文字母、数字、部分特殊符号 + = - _ 的组合方式，最大长度 128 个字符，value 聊天室属性对应的值，最大长度 4096 个字符，最多一次设置 10 条
isForceBOOL是否强制覆盖
autoDeleteBOOL用户掉线或退出时，是否自动删除该 Key、Value 值；自动删除时不会发送通知
successBlockBlock成功的回调
errorBlockBlock失败的回调。status 中返回错误码 RCErrorCode。

删除单个属性​

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

[[RCChatRoomClient sharedChatRoomClient] removeChatRoomEntry:chatroomId
                                                key:key
                                   sendNotification:isNotice
                                  notificationExtra:extra
                                            success:^{

                                            } error:^(RCErrorCode nErrorCode) {

                                            }];

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

参数类型说明
chatroomIdNSString聊天室 ID，最大长度为 64 个字符。
keyNSString聊天室属性名称，Key 支持大小写英文字母、数字、部分特殊符号 + = - _ 的组合方式，最大长度 128 个字符
sendNotificationBOOL是否需要发送通知
notificationExtraNSString通知的自定义字段，聊天室属性通知消息 RCChatroomKVNotificationMessage 中会包含此字段，最大长度 2048 个字符
successBlockBlock成功的回调
errorBlockBlock失败的回调。status 中返回错误码 RCErrorCode。

强制删除单个属性​

强制删除聊天室自定义属性。可删除他人所创建的属性。

[[RCChatRoomClient sharedChatRoomClient] forceRemoveChatRoomEntry:chatroomId
                                                    key:key
                                        sendNotification:isNotice
                                      notificationExtra:extra
                                                success:^{}
                                                  error:^(RCErrorCode nErrorCode) {}];

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

参数类型说明
chatroomIdNSString聊天室 ID，最大长度为 64 个字符。
keyNSString聊天室属性名称，Key 支持大小写英文字母、数字、部分特殊符号 + = - _ 的组合方式，最大长度 128 个字符
sendNotificationBOOL是否需要发送通知
notificationExtraNSString通知的自定义字段，聊天室属性通知消息 RCChatroomKVNotificationMessage 中会包含此字段，最大长度 2048 个字符
successBlockBlock成功的回调
errorBlockBlock失败的回调。status 中返回错误码 RCErrorCode。

批量删除属性​

提示

IMLib 从 5.1.4 版本开始支持该接口。

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

NSArray *keys = @[@"key1", @"key2"];
[[RCChatRoomClient sharedChatRoomClient] removeChatRoomEntries:chatroomId
                                                          keys:keys
                                                       isForce:isForce
                                                       success:^{

                                                       } error:^(RCErrorCode nErrorCode) {

 }];
参数类型说明
chatroomIdNSString聊天室 ID，最大长度为 64 个字符。
keysNSDictionary聊天室属性 keys, 最多一次删除 10 条
isForceBOOL是否强制覆盖
successBlockBlock成功的回调
errorBlockBlock失败的回调。status 中返回错误码 RCErrorCode。
最后于 更新