Chatroom Attribute Management (KV)

The SDK provides chatroom attribute (KV) management interfaces in the core chatroom business class RCChatRoomClient (or RCIMClient can also be used) to set custom attributes in a specified chatroom.

In voice live chatroom scenarios, this feature can be used to record the attributes of each mic position in the chatroom; or in card games like Werewolf, it can be used to record user roles and game states.

Enabling the Service

Using the chatroom attribute (KV) interfaces requires enabling the Chatroom Custom Attribute Settings service. You can enable this service on the Basic Features page in the Console.

The chatroom business also provides a server-side callback feature, allowing RC's server to synchronize all chatroom attribute changes (such as setting, deleting, or clearing all attributes) to a specified address, making it easier for your app's business server to track chatroom attribute changes. For more details, refer to the server-side documentation Chatroom Attribute Synchronization (KV).

Limitations

tip

When a chatroom is destroyed, all custom attributes within the chatroom are also destroyed.
Each chatroom allows a maximum of 100 attributes to be stored in a Key-Value format.
The client SDK does not limit the frequency of KV operations in chatrooms. It is recommended to keep the frequency of Key-Value operations in each chatroom to 100 times per second or less (one operation on 100 KVs in one second is equivalent to 100 operations).

Listening to Chatroom Attribute Changes

The SDK provides the RCChatRoomKVStatusChangeDelegate protocol in the core chatroom business class RCChatRoomClient to listen for changes in chatroom attributes (KV).

To implement this feature, developers need to adhere to the RCChatRoomKVStatusChangeDelegate protocol.

@protocol RCChatRoomKVStatusChangeDelegate <NSObject>

/**
 Callback when KV synchronization is completed after IMLib joins a chatroom.

 @param roomId The chatroom ID
 */
- (void)chatRoomKVDidSync:(NSString *)roomId;

/**
 Callback when chatroom KV changes.

 @param roomId The chatroom ID
 @param entry The KV dictionary. If KVs exist when joining the chatroom, all KVs will be returned through this callback. Subsequent callbacks will occur when others set or modify KVs.
 */
- (void)chatRoomKVDidUpdate:(NSString *)roomId entry:(NSDictionary<NSString *, NSString *> *)entry;

/**
 Callback when a chatroom KV is deleted.

 @param roomId The chatroom ID
 @param entry The KV dictionary
 */
- (void)chatRoomKVDidRemove:(NSString *)roomId entry:(NSDictionary<NSString *, NSString *> *)entry;

@end

Setting the Chatroom KV Listener

Set the chatroom KV listener delegate. To avoid memory leaks, remove the listener when it is no longer needed.

Use the addChatRoomKVStatusChangeDelegate method, which supports setting multiple listeners:

[[RCChatRoomClient sharedChatRoomClient] addChatRoomKVStatusChangeDelegate:self];

Removing the Chatroom KV Listener

The SDK supports removing listeners. To avoid memory leaks, remove the listener when it is no longer needed.

Use removeChatRoomKVStatusChangeDelegate:

[[RCChatRoomClient sharedChatRoomClient] removeChatRoomKVStatusChangeDelegate:self];

Getting a Single Attribute

Retrieve a single KV pair from a specified chatroom using the attribute's Key.

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

                                        } error:^(RCErrorCode nErrorCode) {

                                        }];

Parameter	Type	Description
chatroomId	NSString	The chatroom ID, with a maximum length of 64 characters.
key	NSString	The chatroom attribute name.
successBlock	Block	The success callback. `entry` returns the attribute content as an `NSDictionary`.
errorBlock	Block	The failure callback. `status` returns the error code RCErrorCode.

Getting All Attributes

Retrieve all KV pairs from a specified chatroom.

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

                                             } error:^(RCErrorCode nErrorCode) {

                                             }];

Parameter	Type	Description
chatroomId	NSString	The chatroom ID, with a maximum length of 64 characters.
successBlock	Block	The success callback. `entry` returns the attribute content as an `NSDictionary`.
errorBlock	Block	The failure callback. `status` returns the error code RCErrorCode.

Setting a Single Attribute

Set a custom chatroom attribute. If the key does not exist, it adds the attribute; if the key already exists, it updates the attribute's value. Only the creator of the key can update its value.

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

                                        } error:^(RCErrorCode nErrorCode) {

                                        }];

When setting a KV, you can specify the SDK to send a chatroom attribute notification message (RCChatroomKVNotificationMessage). For details on the message content structure, refer to Notification Message Format.

Parameter	Type	Description
chatroomId	NSString	The chatroom ID, with a maximum length of 64 characters.
key	NSString	The chatroom attribute name. Key supports uppercase and lowercase letters, numbers, and special symbols + = - _, with a maximum length of 128 characters.
value	NSString	The 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 and Value when the user goes offline or exits; no notification is sent if auto-delete is enabled.
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	The success callback.
errorBlock	Block	The failure callback. `status` returns the error code RCErrorCode.

Forcibly Setting a Single Attribute

Forcibly set a custom chatroom attribute. If the key does not exist, it adds the attribute; if the key already exists, it updates the attribute's value.

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

                                            } error:^(RCErrorCode nErrorCode) {

                                            }];

Parameter	Type	Description
chatroomId	NSString	The chatroom ID, with a maximum length of 64 characters.
key	NSString	The chatroom attribute name. Key supports uppercase and lowercase letters, numbers, and special symbols + = - _, with a maximum length of 128 characters.
value	NSString	The 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 and Value when the user goes offline or exits; no notification is sent if auto-delete is enabled.
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	The success callback.
errorBlock	Block	The failure callback. `status` returns the error code RCErrorCode.

Batch Setting Attributes

tip

IMLib supports this interface starting from version 5.1.4.

Batch set chatroom attributes. The isForce parameter controls whether to forcibly overwrite attributes set by others.

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

                                                    } error:^(RCErrorCode nErrorCode) {

 }];

Parameter	Type	Description
chatroomId	NSString	The chatroom ID, with a maximum length of 64 characters.
entries	NSDictionary	The chatroom attributes. The dictionary key supports uppercase and lowercase letters, numbers, and special symbols + = - _, with a maximum length of 128 characters. The value corresponds to the chatroom attribute, with a maximum length of 4096 characters. A maximum of 10 entries can be set at once.
isForce	BOOL	Whether to forcibly overwrite.
autoDelete	BOOL	Whether to automatically delete the Key and Value when the user goes offline or exits; no notification is sent if auto-delete is enabled.
successBlock	Block	The success callback.
errorBlock	Block	The failure callback. `status` returns the error code RCErrorCode.

Deleting a Single Attribute

Delete a single attribute from a specified chatroom. This interface only supports deleting attributes created by the current user.

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

                                            } error:^(RCErrorCode nErrorCode) {

                                            }];

When deleting a KV, you can specify the SDK to send a chatroom attribute notification message (RCChatroomKVNotificationMessage). For details on the message content structure, refer to Notification Message Format.

Parameter	Type	Description
chatroomId	NSString	The chatroom ID, with a maximum length of 64 characters.
key	NSString	The chatroom attribute name. Key supports uppercase and 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	The success callback.
errorBlock	Block	The failure callback. `status` returns the error code RCErrorCode.

Forcibly Deleting a Single Attribute

Forcibly delete a custom chatroom attribute. This allows deleting attributes created by others.

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

Parameter	Type	Description
chatroomId	NSString	The chatroom ID, with a maximum length of 64 characters.
key	NSString	The chatroom attribute name. Key supports uppercase and 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	The success callback.
errorBlock	Block	The failure callback. `status` returns the error code RCErrorCode.

Batch Deleting Attributes

tip

IMLib supports this interface starting from version 5.1.4.

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.

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.

IMLib

Global Chat UIKit

push notification

IMLib

Global Chat UIKit

Chat Server

Chat Server SDK

Chatroom Attribute Management (KV)

Enabling the Service​

Limitations​

Listening to Chatroom Attribute Changes​

Setting the Chatroom KV Listener​

Removing the Chatroom KV Listener​

Getting a Single Attribute​

Getting All Attributes​

Setting a Single Attribute​

Forcibly Setting a Single Attribute​

Batch Setting Attributes​

Deleting a Single Attribute​

Forcibly Deleting a Single Attribute​

Batch Deleting Attributes​