跳到主要内容

聊天室属性管理（KV）

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

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

开通服务​

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

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

功能局限​

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

监听聊天室属性变化​

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

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

设置聊天室 KV 监听器​

使用 addChatRoomKVStatusChangeDelegate 方法设置聊天室 KV 监听器代理，支持设置多个监听器：

示例代码​

Objective C
[[RCChatRoomClient sharedChatRoomClient] addChatRoomKVStatusChangeDelegate:self];

移除聊天室 KV 监听器​

使用 removeChatRoomKVStatusChangeDelegate 方法移除聊天室 KV 监听器代理。为了避免内存泄露，请在不需要监听时将监听器移除：

示例代码​

Objective C
[[RCChatRoomClient sharedChatRoomClient] removeChatRoomKVStatusChangeDelegate:self];

实现聊天室属性 KV 变化的代理方法​

示例代码​

Objective C
@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;

/**
 聊天室 KV 变化的回调。
 本回调包含 `chatRoomKVDidUpdate:entry:` 和 `chatRoomKVDidRemove:entry:` 的回调数据。

 - Parameter roomId: 聊天室 ID。
 - Parameter changeInfos: 发生变化的 KV，严格按照聊天室属性设置时的顺序。
 */
- (void)chatRoomKVDidChange:(NSString *)roomId
                changeInfos:(NSArray<RCChatroomKVChangeInfo *> *)changeInfos;

@end

获取单个属性​

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

接口原型​

Objective C
- (void)getChatRoomEntry:(NSString *)chatroomId
                     key:(NSString *)key
                 success:(nullable void (^)(NSDictionary<NSString *,NSString *> *entry))successBlock
                   error:(nullable void (^)(RCErrorCode nErrorCode))errorBlock;

参数说明​

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

示例代码​

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

                                        } error:^(RCErrorCode nErrorCode) {

                                        }];

获取所有属性​

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

接口原型​

Objective C
- (void)getAllChatRoomEntries:(NSString *)chatroomId
                      success:(nullable void (^)(NSDictionary<NSString *, NSString *> *entry))successBlock
                        error:(nullable void (^)(RCErrorCode nErrorCode))errorBlock;

参数说明​

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

示例代码​

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

                                             } error:^(RCErrorCode nErrorCode) {

                                             }];

设置单个属性​

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

接口原型​

Objective C
- (void)setChatRoomEntry:(NSString *)chatroomId
                     key:(NSString *)key
                   value:(NSString *)value
        sendNotification:(BOOL)sendNotification
              autoDelete:(BOOL)autoDelete
       notificationExtra:(nullable NSString *)notificationExtra
                 success:(nullable void (^)(void))successBlock
                   error:(nullable void (^)(RCErrorCode nErrorCode))errorBlock;

参数说明​

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

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

示例代码​

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

                                        } error:^(RCErrorCode nErrorCode) {

                                        }];

强制设置单个属性​

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

接口原型​

Objective C
- (void)forceSetChatRoomEntry:(NSString *)chatroomId
                          key:(NSString *)key
                        value:(NSString *)value
             sendNotification:(BOOL)sendNotification
                   autoDelete:(BOOL)autoDelete
            notificationExtra:(nullable NSString *)notificationExtra
                      success:(nullable void (^)(void))successBlock
                        error:(nullable void (^)(RCErrorCode nErrorCode))errorBlock;

参数说明​

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

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

示例代码​

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

                                            } error:^(RCErrorCode nErrorCode) {

                                            }];

批量设置属性​

提示

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

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

接口原型​

Objective C
- (void)setChatRoomEntries:(NSString *)chatroomId
                   entries:(NSDictionary<NSString *, NSString *> *)entries
                   isForce:(BOOL)isForce
                autoDelete:(BOOL)autoDelete
                   success:(nullable void (^)(void))successBlock
                     error:(nullable void (^)(RCErrorCode nErrorCode, NSDictionary<NSString *,NSNumber *> *failureEntries))errorBlock;

参数说明​

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

示例代码​

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

                                                    } error:^(RCErrorCode nErrorCode) {

 }];

删除单个属性​

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

接口原型​

Objective C
- (void)removeChatRoomEntry:(NSString *)chatroomId
                        key:(NSString *)key
           sendNotification:(BOOL)sendNotification
          notificationExtra:(nullable NSString *)notificationExtra
                    success:(nullable void (^)(void))successBlock
                      error:(nullable void (^)(RCErrorCode nErrorCode))errorBlock;

参数说明​

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

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

示例代码​

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

                                            } error:^(RCErrorCode nErrorCode) {

                                            }];

强制删除单个属性​

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

接口原型​

Objective C
- (void)forceRemoveChatRoomEntry:(NSString *)chatroomId
                             key:(NSString *)key
                sendNotification:(BOOL)sendNotification
               notificationExtra:(nullable NSString *)notificationExtra
                         success:(nullable void (^)(void))successBlock
                           error:(nullable void (^)(RCErrorCode nErrorCode))errorBlock;

参数说明​

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

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

示例代码​

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

批量删除属性​

提示

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

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

接口原型​

Objective C
- (void)removeChatRoomEntries:(NSString *)chatroomId
                         keys:(NSArray<NSString *> *)keys
                      isForce:(BOOL)isForce
                      success:(nullable void (^)(void))successBlock
                        error:(nullable void (^)(RCErrorCode nErrorCode, NSDictionary<NSString *, NSNumber *> *failureEntries))errorBlock;

参数说明​

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

示例代码​

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

                                                       } error:^(RCErrorCode nErrorCode) {

 }];
最后于 更新