聊天室属性管理(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) {
}];
参数 | 类型 | 说明 |
---|---|---|
chatroomId | NSString | 聊天室 ID,最大长度为 64 个字符 |
key | NSString | 聊天室属性名称 |
successBlock | Block | 成功的回调。entry 中返回 NSDictionary 类型的属性内容。 |
errorBlock | Block | 失败的回调。status 中返回错误码 RCErrorCode。 |
获取所有属性
获取指定聊天室中所有属性 KV 对。
[[RCChatRoomClient sharedChatRoomClient] getAllChatRoomEntries:self.roomId
success:^(NSDictionary *entry) {
} error:^(RCErrorCode nErrorCode) {
}];
参数 | 类型 | 说明 |
---|---|---|
chatroomId | NSString | 聊天室 ID,最大长 度为 64 个字符。 |
successBlock | Block | 成功的回调。entry 中返回 NSDictionary 类型的属性内容。 |
errorBlock | Block | 失败的回调。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)。消息内容结构说明可参见通知类消息格式。
参数 | 类型 | 说明 |
---|---|---|
chatroomId | NSString | 聊天室 ID,最大长度为 64 个字符。 |
key | NSString | 聊天室属性名称,Key 支持大小写英文字母、数字、部分特殊符号 + = - _ 的组合方式,最大长度 128 个字符 |
value | NSString | 聊天室属性对应的值,最大长度 4096 个字符 |
sendNotification | BOOL | 是否需要发送通知 |
autoDelete | BOOL | 用户掉线或退出时,是否自动删除该 Key、Value 值;自动删除时不会发送通知 |
notificationExtra | NSString | 通知的自定义字段,聊天室属性通知消息 RCChatroomKVNotificationMessage 中会包含此字段,最大长度 2048 个字符 |
successBlock | Block | 成功的回调 |
errorBlock | Block | 失败的回调。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)。消息内容结构说明可参见通知类消息格式。
参数 | 类型 | 说明 |
---|---|---|
chatroomId | NSString | 聊天室 ID,最大长度为 64 个字符。 |
key | NSString | 聊天室属性名称,Key 支持大小写英文字母、数字、部分特殊符号 + = - _ 的组合方式,最大长度 128 个字符 |
value | NSString | 聊天室属性对应的值,最大长度 4096 个字符 |
sendNotification | BOOL | 是否需要发送通知 |
autoDelete | BOOL | 用户掉线或退出时,是否自动删除该 Key、Value 值;自动删除时不会发送通知 |
notificationExtra | NSString | 通知的自定义字段,聊天室属性通知消息 RCChatroomKVNotificationMessage 中会包含此字段,最大长度 2048 个字符 |
successBlock | Block | 成功的回调 |
errorBlock | Block | 失败的回调。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) {
}];
参数 | 类型 | 说明 |
---|---|---|
chatroomId | NSString | 聊天室 ID,最大长度为 64 个字符。 |
entries | NSDictionary | 聊天室属性,字典中 key 支持大小写英文字母、数字、部分特殊符号 + = - _ 的组合方式,最大长度 128 个字符,value 聊天室属性对应的值,最大长度 4096 个字符,最多一次设置 10 条 |
isForce | BOOL | 是否强制覆盖 |
autoDelete | BOOL | 用户掉线或退出时,是否自动删除该 Key、Value 值;自动删除时不会发送通知 |
successBlock | Block | 成功的回调 |
errorBlock | Block | 失败的回调。status 中返回错误码 RCErrorCode。 |
删除单个属性
删除指定单个聊天室的单个属性。该接口仅支持删除当前用户所创建的属性。
[[RCChatRoomClient sharedChatRoomClient] removeChatRoomEntry:chatroomId
key:key
sendNotification:isNotice
notificationExtra:extra
success:^{
} error:^(RCErrorCode nErrorCode) {
}];
在删除 KV 时,可指定 SDK 发送一条聊天室属性通知消息(RCChatroomKVNotificationMessage)。消息内容结构说明可参见通知类消息格式。
参数 | 类型 | 说明 |
---|---|---|
chatroomId | NSString | 聊天室 ID,最大长度为 64 个字符。 |
key | NSString | 聊天室属性名称,Key 支持大小写英文字母、数字、部分特殊符号 + = - _ 的组合方式,最大长度 128 个字符 |
sendNotification | BOOL | 是否需要发送通知 |
notificationExtra | NSString | 通知的自定义字段,聊天室属性通知消息 RCChatroomKVNotificationMessage 中会包含此字段,最大长度 2048 个字符 |
successBlock | Block | 成功的回调 |
errorBlock | Block | 失败的回调。status 中返回错误码 RCErrorCode。 |
强制删除单个属性
强制删除聊天室自定义属性。可删除他人所创建的属性。
[[RCChatRoomClient sharedChatRoomClient] forceRemoveChatRoomEntry:chatroomId
key:key
sendNotification:isNotice
notificationExtra:extra
success:^{}
error:^(RCErrorCode nErrorCode) {}];
在删除 KV 时,可指定 SDK 发送一条聊天室属性通知消息(RCChatroomKVNotificationMessage)。消息内容结构说明可参见通知类消息格式。
参数 | 类型 | 说明 |
---|---|---|
chatroomId | NSString | 聊天室 ID,最大长度为 64 个字符。 |
key | NSString | 聊天室属性名称,Key 支持大小写英文字母、数字、部分特殊符号 + = - _ 的组合方式,最大长度 128 个字符 |
sendNotification | BOOL | 是否需要发送通知 |
notificationExtra | NSString | 通知的自定义字段,聊天室属性通知消息 RCChatroomKVNotificationMessage 中会包含此字段,最大长度 2048 个字符 |
successBlock | Block | 成功的回调 |
errorBlock | Block | 失败的回调。status 中返回错误码 RCErrorCode。 |
批量删除属性
IMLib 从 5.1.4 版本开始支持该接口。
从指定单个聊天室中批量删除属性。单次最多删除 10 个属性。通过 isForce
参数可控制是否强制删除他人设置的属性。
NSArray *keys = @[@"key1", @"key2"];
[[RCChatRoomClient sharedChatRoomClient] removeChatRoomEntries:chatroomId
keys:keys
isForce:isForce
success:^{
} error:^(RCErrorCode nErrorCode) {
}];
参数 | 类型 | 说明 |
---|---|---|
chatroomId | NSString | 聊天室 ID,最大长度为 64 个字符。 |
keys | NSDictionary | 聊天室属性 keys, 最多一次删除 10 条 |
isForce | BOOL | 是否强制覆盖 |
successBlock | Block | 成功的回调 |
errorBlock | Block | 失败的回调。status 中返回错误码 RCErrorCode。 |