Chatroom Attribute Management (KV)
The IMLib SDK provides chatroom attribute (KV) management interfaces in the core chatroom business class RCChatRoomClient, allowing custom attributes to be set in specified chatrooms.
In voice live streaming chatroom scenarios, this feature can be used to record attributes of each microphone position; or in card games like Werewolf, it can record user roles and game states.
Enabling the Service
Using chatroom attribute (KV) interfaces requires enabling the Chatroom Custom Attributes service. You can enable this service in the RC Console at Chat > Chat settings > Chatroom.
The chatroom service also provides server-side callback functionality, supporting synchronization of all chatroom attribute changes (set, delete, bulk delete operations) in your application to a specified address, allowing your app's backend to track chatroom attribute changes. For details, see the server-side documentation Chatroom Attribute Synchronization (KV).
Limitations
tip
- When a chatroom is destroyed, all custom attributes within it are also destroyed.
- Each chatroom allows a maximum of 100 attribute entries, stored as
Key-Valuepairs. - The IMLib SDK imposes no rate limits on chatroom attribute KV operations. However, it is recommended to keep the operation frequency at 100 times or fewer per second per chatroom (a single operation affecting 100 KVs counts as 100 operations).
Monitoring Chatroom Attribute Changes
The IMLib SDK provides the RCChatRoomKVStatusChangeDelegate protocol in the core chatroom business class RCChatRoomClient for monitoring chatroom attribute (KV) changes.
To implement this functionality, developers must conform to the RCChatRoomKVStatusChangeDelegate protocol.
Setting Up Chatroom KV Listeners
Use the addChatRoomKVStatusChangeDelegate method to set up chatroom KV listener delegates, supporting multiple listeners:
Sample Code
[[RCChatRoomClient sharedChatRoomClient] addChatRoomKVStatusChangeDelegate:self];
Removing Chatroom KV Listeners
Use the removeChatRoomKVStatusChangeDelegate method to remove chatroom KV listener delegates. To prevent memory leaks, remove listeners when they are no longer needed:
Sample Code
[[RCChatRoomClient sharedChatRoomClient] removeChatRoomKVStatusChangeDelegate:self];
Implementing Chatroom KV Change Delegate Methods
Sample Code
@protocol RCChatRoomKVStatusChangeDelegate <NSObject>
/**
Callback when KV synchronization completes after IMLib joins a chatroom
@param roomId Chatroom ID
*/
- (void)chatRoomKVDidSync:(NSString *)roomId;
/**
Callback for chatroom KV changes in IMLib
@param roomId Chatroom ID
@param entry KV dictionary. If KVs exist when first joining the chatroom, all KVs are returned via this callback. Subsequent callbacks occur when others set or modify KVs.
*/
- (void)chatRoomKVDidUpdate:(NSString *)roomId entry:(NSDictionary<NSString *, NSString *> *)entry;
/**
Callback when a chatroom KV is deleted in IMLib
@param roomId Chatroom ID
@param entry KV dictionary
*/
- (void)chatRoomKVDidRemove:(NSString *)roomId entry:(NSDictionary<NSString *, NSString *> *)entry;
/**
Callback for chatroom KV changes.
This callback includes data from both `chatRoomKVDidUpdate:entry:` and `chatRoomKVDidRemove:entry:`.
- Parameter roomId: Chatroom ID.
- Parameter changeInfos: Changed KVs, strictly following the order in which chatroom attributes were set.
*/
- (void)chatRoomKVDidChange:(NSString *)roomId
changeInfos:(NSArray<RCChatroomKVChangeInfo *> *)changeInfos;
@end
Retrieving a Single Attribute
You can retrieve a single KV pair from a specified chatroom using the attribute's Key.
Interface Prototype
- (void)getChatRoomEntry:(NSString *)chatroomId
key:(NSString *)key
success:(nullable void (^)(NSDictionary<NSString *,NSString *> *entry))successBlock
error:(nullable void (^)(RCErrorCode nErrorCode))errorBlock;
Parameter Description
| Parameter | Type | Description |
|---|---|---|
| chatroomId | NSString | Chatroom ID, maximum length of 64 characters |
| key | NSString | Chatroom attribute name |
| successBlock | Block | Success callback. Returns attribute content as NSDictionary in entry. |
| errorBlock | Block | Failure callback. Returns error code RCErrorCode in status. |
Sample Code
[[RCChatRoomClient sharedChatRoomClient] getChatRoomEntry:chatroomId
key:key
success:^(NSDictionary *entry) {
} error:^(RCErrorCode nErrorCode) {
}];
Retrieving All Attributes
You can retrieve all KV pairs from a specified chatroom.
Interface Prototype
- (void)getAllChatRoomEntries:(NSString *)chatroomId
success:(nullable void (^)(NSDictionary<NSString *, NSString *> *entry))successBlock
error:(nullable void (^)(RCErrorCode nErrorCode))errorBlock;
Parameter Description
| Parameter | Type | Description |
|---|---|---|
| chatroomId | NSString | Chatroom ID, maximum length of 64 characters. |
| successBlock | Block | Success callback. Returns attribute content as NSDictionary in entry. |
| errorBlock | Block | Failure callback. Returns error code RCErrorCode in status. |
Sample Code
[[RCChatRoomClient sharedChatRoomClient] getAllChatRoomEntries:self.roomId
success:^(NSDictionary *entry) {
} error:^(RCErrorCode nErrorCode) {
}];
Setting a Single Attribute
You can set custom chatroom attributes. When key does not exist, it adds an attribute; when key exists, it updates the attribute's value, and only the creator of the key can update its value.
Interface Prototype
- (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;
Parameter Description
When setting KVs, you can specify that the IMlib SDK sends a chatroom attribute notification message (RCChatroomKVNotificationMessage). For message content structure, see Notification Message Format.
| Parameter | Type | Description |
|---|---|---|
| chatroomId | NSString | Chatroom ID, with a maximum length of 64 characters. |
| key | NSString | Chatroom attribute name. Keys support uppercase/lowercase letters, numbers, and special symbols + = - _. Maximum length: 128 characters. |
| value | NSString | Value corresponding to the chatroom attribute, with a maximum length of 4096 characters. |
| sendNotification | BOOL | Whether to send a notification. |
| autoDelete | BOOL | Whether to automatically delete the Key-Value pair when the user goes offline or exits. No notification is sent for auto-deletion. |
| notificationExtra | NSString | Custom field for notifications. This field is included in the chatroom attribute notification message RCChatroomKVNotificationMessage. Maximum length: 2048 characters. |
| successBlock | Block | Success callback. |
| errorBlock | Block | Failure callback. Returns an error code RCErrorCode in status. |
Sample Code
[[RCChatRoomClient sharedChatRoomClient] setChatRoomEntry:chatroomId
key:key
value:value
sendNotification:isNotice
autoDelete:isDelete
notificationExtra:extra
success:^{
} error:^(RCErrorCode nErrorCode) {
}];
## Force-Setting a Single Attribute
You can forcibly set a chatroom custom attribute. If the key does not exist, it adds the attribute; if the key already exists, it updates the attribute value. Non-creators of the key can update the attribute value.
#### Method Signature
```objectivec
- (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;
#### Parameter Description
When setting KVs, you can specify that the IMLib SDK sends a chatroom attribute notification message ([RCChatroomKVNotificationMessage]). For message content structure, see [Notification Message Format].
| Parameter | Type | Description |
|:---------------------|:----------|:--------------------------------------------------------------------------------------------------------|
| chatroomId | NSString | Chatroom ID, with a maximum length of 64 characters. |
| key | NSString | Chatroom attribute name. Keys support uppercase/lowercase letters, numbers, and special symbols + = - _. Maximum length: 128 characters. |
| value | NSString | Value corresponding to the chatroom attribute, with a maximum length of 4096 characters. |
| sendNotification | BOOL | Whether to send a notification. |
| autoDelete | BOOL | Whether to automatically delete the Key-Value pair when the user goes offline or exits. No notification is sent for auto-deletion. |
| notificationExtra | NSString | Custom field for notifications. This field is included in the chatroom attribute notification message [RCChatroomKVNotificationMessage]. Maximum length: 2048 characters. |
| successBlock | Block | Success callback. |
| errorBlock | Block | Failure callback. Returns an error code [RCErrorCode] in `status`. |
#### Sample Code
```objectivec
[[RCChatRoomClient sharedChatRoomClient] forceSetChatRoomEntry:chatroomId
key:key
value:value
sendNotification:isNotice
autoDelete:isDelete
notificationExtra:extra
success:^{
} error:^(RCErrorCode nErrorCode) {
}];
## Batch Setting Attributes
:::tip
The IMLib SDK supports this method starting from version 5.1.4.
:::
You can batch set chatroom attributes. The `isForce` parameter controls whether to forcibly overwrite attributes set by others.
#### Method Signature
```objectivec
- (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;
#### Parameter Description
| Parameter | Type | Description |
|:---------------|:-------------|:-------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| chatroomId | NSString | Chatroom ID with a maximum length of 64 characters. |
| entries | NSDictionary | Chatroom attributes. Dictionary keys support combinations of uppercase/lowercase letters, numbers, and special symbols (+ = - _), with a maximum length of 128 characters. Values support a maximum length of 4096 characters. Up to 10 entries can be set at once. |
| isForce | BOOL | Whether to force overwrite |
| autoDelete | BOOL | Whether to automatically delete the Key-Value pair when the user disconnects or exits; no notification will be sent for automatic deletions |
| successBlock | Block | Success callback |
| errorBlock | Block | Failure callback. Returns error codes in `status` [RCErrorCode]. |
#### Sample Code
```objectivec
NSDictionary *entries = @{@"key1":@"value1", @"key2":@"value2"};
[[RCChatRoomClient sharedChatRoomClient] setChatRoomEntries:chatroomId
entries:entries
isForce:isForce
autoDelete:isDelete
success:^{
} error:^(RCErrorCode nErrorCode) {
}];
## Delete Single Attribute
You can delete a single attribute from a specified chatroom. This interface only supports deleting attributes created by the current user.
#### Interface Prototype
```objectivec
- (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;
#### Parameter Description
When deleting KV pairs, you can specify the SDK to send a chatroom attribute notification message ([RCChatroomKVNotificationMessage]). For message content structure, refer to [Notification Message Format].
| Parameter | Type | Description |
|:--------------------|:---------|:----------------------------------------------------------------------------------------------------------------|
| chatroomId | NSString | Chatroom ID with a maximum length of 64 characters. |
| key | NSString | Chatroom attribute name. Keys support combinations of uppercase/lowercase letters, numbers, and special symbols (+ = - _), with a maximum length of 128 characters. |
| sendNotification | BOOL | Whether to send a notification |
| notificationExtra | NSString | Custom field for notifications. This field will be included in the chatroom attribute notification message [RCChatroomKVNotificationMessage], with a maximum length of 2048 characters. |
| successBlock | Block | Success callback |
| errorBlock | Block | Failure callback. Returns error codes in `status` [RCErrorCode]. |
#### Sample Code
```objectivec
[[RCChatRoomClient sharedChatRoomClient] removeChatRoomEntry:chatroomId
key:key
sendNotification:isNotice
notificationExtra:extra
success:^{
} error:^(RCErrorCode nErrorCode) {
}];
## Force Delete Single Attribute
You can forcibly delete chatroom custom attributes, including those created by others.
#### Interface Prototype
```objectivec
- (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;
#### Parameter Description
When deleting KV pairs, you can specify the SDK to send a chatroom attribute notification message ([RCChatroomKVNotificationMessage]). For message content structure, refer to [Notification Message Format].
| Parameter | Type | Description |
|:-------------------|:----------|:------------------------------------------------------------------------------------------------------------|
| chatroomId | NSString | Chatroom ID, with a maximum length of 64 characters. |
| key | NSString | Chatroom attribute name. Key supports uppercase/lowercase letters, numbers, and special symbols + = - _, with a maximum length of 128 characters. |
| sendNotification | BOOL | Whether to send a notification. |
| notificationExtra | NSString | Custom field for the notification. The chatroom attribute notification message [RCChatroomKVNotificationMessage] will include this field, with a maximum length of 2048 characters. |
| successBlock | Block | Success callback. |
| errorBlock | Block | Failure callback. Returns error code [RCErrorCode] in `status`. |
#### Sample Code
```objectivec
[[RCChatRoomClient sharedChatRoomClient] forceRemoveChatRoomEntry:chatroomId
key:key
sendNotification:isNotice
notificationExtra:extra
success:^{}
error:^(RCErrorCode nErrorCode) {}];
## Batch Delete Attributes
:::tip
IMLib SDK supports this interface starting from version 5.1.4.
:::
You can batch delete attributes from a specified chatroom. A maximum of 10 attributes can be deleted at once. The `isForce` parameter controls whether to forcibly delete attributes set by others.
#### Interface Prototype
```objectivec
- (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;
#### Parameter Description
| Parameter | Type | Description |
|:--------------|:-------------|:------------------------------------------------------|
| chatroomId | NSString | Chatroom ID, with a maximum length of 64 characters. |
| keys | NSDictionary | Chatroom attribute keys. A maximum of 10 can be deleted at once. |
| isForce | BOOL | Whether to forcibly overwrite. |
| successBlock | Block | Success callback. |
| errorBlock | Block | Failure callback. Returns error code [RCErrorCode] in `status`. |
#### Sample Code
```objectivec
NSArray *keys = @[@"key1", @"key2"];
[[RCChatRoomClient sharedChatRoomClient] removeChatRoomEntries:chatroomId
keys:keys
isForce:isForce
success:^{
} error:^(RCErrorCode nErrorCode) {
}];
| Parameter | Type | Description |
|---|---|---|
| chatroomId | NSString | The chatroom ID, with a maximum length of 64 characters. |
| keys | NSDictionary | The chatroom attribute keys, with a maximum of 10 entries that can be deleted at once. |
| isForce | BOOL | Whether to forcibly overwrite. |
| successBlock | Block | The success callback. |
| errorBlock | Block | The failure callback. status returns the error code RCErrorCode. |