Manage room properties

ZEGOCLOUD's In-app Chat (the ZIM SDK) provides the capability of room property management, allowing you to customize the properties of a specified room.

With this feature, you can build your app to meet different requirements of various scenarios: customize the in-room properties in a live audio streaming or live chatroom, manage your speaker seats in a live audio room, mark player role and the latest facts and figures in an online Werewolf and other online board games.

Set room properties

To set room properties, set them when you call the createRoom method to create a room.

Warning

Up to 20 room properties can be set in a room. The room property is stored in the format of Key-Value. The maximum length of Key is 16 bytes, the maximum length of Value is 1024 bytes, and the total length of all properties must not exceed 5120 bytes. For more customizable room properties, contact ZEGOCLOUD Technical Support.
The customized room properties you set will be cleared after the room is destroyed.

Sample code

ZIMRoomInfo *zimRoomInfo = [[ZIMRoomInfo alloc] init];        
//Create a ZIMRoomInfo object.
ZIMRoomAdvancedConfig *config = [[ZIMRoomAdvancedConfig alloc] init];
NSMutableDictionary *roomAttributes = [[NSMutableDictionary alloc] init];
NSString *myValue = @"room_info_value"
NSString *myKey = @"room_info";
       
[roomAttributes setObject:myValue forKey:myKey];
        
config.roomAttributes = roomAttributes;
        
[zim createRoom:zimRoomInfo config:config callback:^(ZIMRoomFullInfo * _Nonnull roomInfo, ZIMError * _Nonnull errorInfo) {}];

Copied!

Modify room properties

The room properties you set are stored as key-value.

When Key does not exist: Setting room property means adding room property.
When the Key already exists: Setting the room property means updating the value of the existing room property.

Sample code

NSString *key = @"room_info";
NSString *value = @"room_info_value";
NSMutableDictionary *roomAttributes = [[NSMutableDictionary alloc] init];
[roomAttributes setObject:value forKey:key];
ZIMRoomAttributesSetConfig *setConfig = [[ZIMRoomAttributesSetConfig alloc] init];
setConfig.isDeleteAfterOwnerLeft = true;
setConfig.isForce = false;
[zim setRoomAttributes:roomAttributes roomID:roomID config:setConfig callback:^(NSString * _Nonnull roomID, NSArray<NSString *> * _Nonnull errorKeys, ZIMError * _Nonnull errorInfo) {}];

Copied!

Delete room properties

Generally, you can only delete the room properties that you own. You can also delete the room properties created by others by setting the isForce value in config.

Sample code

NSString *key = [NSString stringWithFormat:@"seat_%d",targetIndex];
NSMutableArray *keys = [[NSMutableArray alloc] init];
[keys addObject:key];
ZIMRoomAttributesDeleteConfig *config = [[ZIMRoomAttributesDeleteConfig alloc] init];
config.isForce = true;
[zim deleteRoomAttributesByKeys:keys roomID:roomID config:config callback:^(NSString * _Nonnull roomID, NSArray<NSString *> * _Nonnull errorKeys, ZIMError * _Nonnull errorInfo) {}];

Copied!

Get room properties

Sample code

[zim queryRoomAllAttributesByRoomID:roomID callback:^(NSString * _Nonnull roomID, NSDictionary<NSString *,NSString *> * _Nonnull roomAttributes, ZIMError * _Nonnull errorInfo) {}];

Copied!

Combined room properties operation

The merge operation means that you can combine multiple operations within the same room into one operation using the beginRoomAttributesBatchOperationWithRoomID and endRoomAttributesBatchOperationWithRoomID methods. This is typically used when you want to perform consecutive operations without being interrupted by other users' operations.

Sample code

//Combined operation 
NSMutableDictionary *roomAttributes = [[NSMutableDictionary alloc] init];
NSString *key = @"key";
NSString *value = @"value";
[roomAttributes setObject:value forKey:key];
//Set the configurations for adding a new room property.
ZIMRoomAttributesSetConfig *config = [[ZIMRoomAttributesSetConfig alloc] init];
config.isForce = false;
config.isDeleteAfterOwnerLeft = true;
//Delete related configurations of room properties.
NSString *deleteKey = @"key";
NSMutableArray *keys = [[NSMutableArray alloc] init];
[keys addObject:deleteKey];
ZIMRoomAttributesDeleteConfig *deleteConfig = [[ZIMRoomAttributesDeleteConfig alloc] init];
//Set a combined room properties operation.
ZIMRoomAttributesBatchOperationConfig *setConfig = [[ZIMRoomAttributesBatchOperationConfig alloc] init];
setConfig.isDeleteAfterOwnerLeft = true;
setConfig.isForce = false;
setConfig.isUpdateOwner = true;
[zim beginRoomAttributesBatchOperationWithRoomID:roomID config:setConfig];

//Modify room properties
   
//Add a room property first.
[zim setRoomAttributes:roomAttributes roomID:roomID config:config callback:^(NSString * _Nonnull roomID, NSArray<NSString *> * _Nonnull errorKeys, ZIMError * _Nonnull errorInfo) {}];
    
//Then delete a room property.
[zim deleteRoomAttributesByKeys:keys roomID:roomID config:config callback:^(NSString * _Nonnull roomID, NSArray<NSString *> * _Nonnull errorKeys, ZIMError * _Nonnull errorInfo) {}];
    
//Combine the two operations.
[zim endRoomAttributesBatchOperationWithRoomID:roomID callback:^(NSString * _Nonnull roomID, ZIMError * _Nonnull errorInfo) {}];

Copied!