logo
In-app Chat
SDK Error Codes
Powered Byspreading
On this page

Manage room user attributes


Overview

The In-app Chat SDK provides the feature of configuring user attributes of users in a room, that is, customizing user attributes of users in a room. This feature applies to the following scenarios:

  • Configure roles of room members, such as setting the room owner, administrator, participant, and participant level.
  • Turn on/off the camera, turn on/off the microphone, mute/unmute a user, and enable/disable whiteboard sharing.

Implementation process

Warning
  • User attributes of up to 500 users can be configured in each room, and the user attributes are stored in Key-Value format. To increase the maximum number of user attributes that can be configured in each room, developers can contact ZEGOCLOUD technical support.

  • The total length of user attribute Key-Value pairs of each user in a room cannot exceed 144 bytes, and the number of Key-Value pairs cannot exceed 30. In a single Key-Value pair, the key cannot exceed 8 bytes, and the value cannot exceed 64 bytes. To increase the maximum length of a Key-Value pair, developers can contact ZEGOCLOUD technical support.

  • After a room is destroyed, the configured customized user attributes are also deleted.

Configure user attributes

Warning

The operator and the user whose attributes are configured or modified must be users in the room.

Developers can call the setRoomMembersAttributes API to configure user attributes of users in a room. Configured user attributes are stored in Key-Value format.

  • When a key does not exist, configuring user attributes indicates adding a user attribute.
  • When a key already exists, configuring user attributes indicates updating the value of an existing attribute.
Sample code
ZIMRoomMemberAttributesSetConfig *setConfig = [[ZIMRoomMemberAttributesSetConfig alloc] init];
[[ZIM getInstance] setRoomMembersAttributes:@{@"key1":@"value1"} userIDs:@[@"user1",@"user2"] roomID:@"roomID" config:setConfig callback:^(NSString * _Nonnull roomID, NSArray<ZIMRoomMemberAttributesOperatedInfo *> * _Nonnull operatedInfos, NSArray<NSString *> * _Nonnull errorUserList, ZIMError * _Nonnull errorInfo) {
        // The service logic after the configuration result is returned. 
}];
1
Copied!

Query user attributes of some users

Users in a room can call the queryRoomMembersAttributesByUserIDs API to query the user attributes of some users in the room.

Sample code
[[ZIM getInstance] queryRoomMembersAttributesByUserIDs:@[@"userID1",@"userID2"] roomID:@"roomID" callback:^(NSString * _Nonnull roomID, NSArray<ZIMRoomMemberAttributesInfo *> * _Nonnull infos, ZIMError * _Nonnull errorInfo) {
        // The service logic after the query result is returned. 
}];
1
Copied!

Query user attributes of all users

Users in a room can call the queryRoomMemberAttributesListByRoomID API to query the user attributes of all users in the room.

Sample code
ZIMRoomMemberAttributesQueryConfig *queryConfig = [[ZIMRoomMemberAttributesQueryConfig alloc] init];
queryConfig.count = 100;
[[ZIM getInstance] queryRoomMemberAttributesListByRoomID:@"roomID" config:queryConfig callback:^(NSString * _Nonnull roomID, NSArray<ZIMRoomMemberAttributesInfo *> * _Nonnull infos, NSString * _Nonnull nextFlag, ZIMError * _Nonnull errorInfo) {
      // The service logic after the query result is returned.  
 }];
1
Copied!

User attribute change notification

When user attributes of members in a room are changed, developers can register the onRoomMemberAttributesUpdated method of the setEventHandler callback API to listen for user attribute change notifications of members in the room.

Untitled
- (void)zim:(ZIM *)zim
    roomMemberAttributesUpdated:(NSArray<ZIMRoomMemberAttributesUpdateInfo *> *)updateInfo
               operatedUserInfo:(ZIMRoomOperatedInfo *)operatedInfo
                         roomID:(NSString *)roomID{
    //The service logic after user attributes of members in a room are changed.
}
1
Copied!
Note

When a user in a room calls the setRoomMembersAttributes API:

  • If the number of users in the room is less than or equal to 500, all users in the room will receive the user attribute change notification.

  • If the number of users in the room exceeds 500, only the operator and the user whose attribute is configured or modified will receive the user attribute change notification.

To increase the maximum number of users in the room who can receive the user attribute change notification, developers can contact ZEGOCLOUD technical support.

Batch query room user information

Developers can use the queryRoomMembersByUserIDs interface to query the information of users in a room in bulk by passing the roomID and an array of userIDs. After a successful API call, the ZIMRoomMembersQueriedCallback will return the userList of successfully queried users (which can be used to confirm if the target users are in the room), as well as the errorUserList of failed queries (which can be used to confirm if the target users are not in the room).

Note

The default limit for the number of users that can be queried in bulk is 10.

The sample code is as follows:

Untitled
NSString *userIdA = @"targetUserIdA";
NSString *userIdB = @"targetUserIdB";
NSArray<NSString *> *targetUserIDs = @[userIdA,userIdB];

// A map that maps userID to ZIMRoomMemberInfo, which can be cached for subsequent UI display. Currently, ZIMRoomMemberInfo exposes userID and userName.
NSMutableDictionary *targetRoomMemberMap = [[NSMutableDictionary alloc] init];

[[ZIM getInstance] queryRoomMembersByUserIDs:targetUserIDs roomID:@"targetRoomID" callback:^(NSString * _Nonnull roomID, NSArray<ZIMRoomMemberInfo *> * _Nonnull memberList, NSArray<ZIMErrorUserInfo *> * _Nonnull errorUserList, ZIMError * _Nonnull errorInfo) {
    if(errorInfo.code != ZIMErrorCodeSuccess){
        NSLog(@"query room members failed! error code:%ld, error message: %@",errorInfo.code, errorInfo.message);
        return;
    }
    // A map that maps userID to ZIMErrorUserInfo, if there is a need to pay attention to the failure reason, you can read this data structure
    NSMutableDictionary *targetErrorUserInfoMap = [[NSMutableDictionary alloc] init];


    for (ZIMRoomMemberInfo *currentMemberInfo in memberList) {
        [targetRoomMemberMap setObject:currentMemberInfo forKey:currentMemberInfo.userID];
    }
    for (ZIMErrorUserInfo *currentErrorUserInfo in errorUserList){
        [targetErrorUserInfoMap setObject:currentErrorUserInfo forKey:currentErrorUserInfo.userID];
    }

    // Check if the target member is in the room
    bool isTargetUserIdAInTheRoom = [[targetRoomMemberMap allKeys] containsObject:userIdA];

}];
1
Copied!

Previous

Manage room properties

Next

Manage groups