logo
当前页

房间用户管理


功能简介

ZIM SDK 支持设置房间内的用户属性,即在房间内,自定义房间内的用户属性。

可应用的场景:

  • 设置成员角色,如设置房主、管理员、观众、观众等级。
  • 开/关摄像头、开/关麦克风、是否能发言、是否共享白板等。

实现流程

注意
  • 每个房间中,最多允许设置 500 个用户的用户属性,以 Key-Value 的方式进行存储。开发者如果需要提高属性上限,请联系 ZEGO 技术支持。
  • 房间内的每个用户,所拥有的用户属性 Key-Value 的总长度不超过 144 字节,且 Key-Value 的个数不超过 30 对。单个 Key-Value 的长度,Key 不超过 8 字节、Value 不超过 64 字节。开发者如果需要提高上限,请联系 ZEGO 技术支持。
  • 房间销毁后,设置的自定义用户属性也会同时销毁。

设置用户属性

注意

操作者和被设置/修改属性的用户,都必须是该房间内的用户。

开发者可以通过 setRoomMembersAttributes 接口,设置房间内用户的用户属性。设置的房间用户属性以 Key-Value 的形式存储:

  • 当 Key 不存在时,设置用户属性表示增加属性。
  • 当 key 已经存在时,设置用户属性表示更新已有属性的取值。
示例代码
std::unordered_map<std::string, std::string> attributes;
attributes.emplace(std::string("key1"),std::string("value1"));
std::vector<std::string> userIDs;
userIDs.push_back(std::string("userID1"));
ZIMRoomMemberAttributesSetConfig setConfig;
setConfig.isDeleteAfterOwnerLeft = true;
ZIM::getInstance()->setRoomMembersAttributes(attributes, userIDs, std::string("roomID"), setConfig, [=](const std::string &roomID, const std::vector<ZIMRoomMemberAttributesOperatedInfo> &infos,                                                                                                           const std::vector<std::string> &errorUsers, const ZIMError &errorInfo){
        //这里填写操作结果返回的逻辑
    });
1
Copied!

查询用户属性

房间内的用户,可以通过 queryRoomMembersAttributes 接口,查询房间内某些用户的用户属性。

示例代码
std::vector<std::string> userIDs;
userIDs.push_back(std::string("userID1"));
ZIM::getInstance()->queryRoomMembersAttributes(userIDs,  std::string("roomID"), [=](const std::string &roomID, const std::vector<ZIMRoomMemberAttributesInfo> &infos,const ZIMError &errorInfo){
        //这里填写查询结果返回的逻辑
});
1
Copied!

查询所有用户属性

房间内的用户,可以通过 queryRoomMemberAttributesList 接口,查询该房间内的所有用户的用户属性。

示例代码
ZIMRoomMemberAttributesQueryConfig queryConfig = ZIMRoomMemberAttributesQueryConfig(std::string(""), 100);
ZIM::getInstance()->queryRoomMemberAttributesList(std::string("roomID"), queryConfig, [=](const std::string &roomID, const std::vector<ZIMRoomMemberAttributesInfo> &infos,const std::string &nextFlag, const ZIMError &errorInfo){
    if (nextFlag == "") {
        //所有用户的房间用户属性均已查完
    }else{
        //继续查询下一分页
    }
});
1
Copied!

用户属性变更通知

当房间内成员的房间用户属性发生变更时,开发者可以通过注册 setEventHandler 的回调接口 onRoomMemberAttributesUpdated 方法,监听房间内成员的用户属性变更通知。

Untitled
void onRoomMemberAttributesUpdated(ZIM * /*zim*/, const std::vector<ZIMRoomMemberAttributesUpdateInfo> & /*infos*/,ZIMRoomOperatedInfo /*operatedInfo*/, const std::string & /*roomID*/) override{
     //这里写房间用户属性发生变更后的业务逻辑       
}
1
Copied!
说明

在房间内,如果有用户调用了 setRoomMembersAttributes 接口时:

  • 当房间内人数在 500 人以内时,所有房间内的用户,均可以收到房用户属性变更的通知。
  • 当房间内人数超过 500 人时,仅操作者和被设置/修改属性的用户,可以收到房用户属性变更的通知。

开发者如果需要提高上限,请联系 ZEGO 技术支持。

批量查询房间用户信息

开发者可以通过调用 queryRoomMembers 接口,传入 roomID 、 userID 数组,批量查询房间中用户的信息。接口调用成功后, ZIMRoomMembersQueriedCallback 会返回查询成功的 userList(可用于确认目标用户在房间中),以及查询失败的 errorUserList(可用于确认目标用户不在房间中)。

说明

批量查询用户数量的默认上限为 10 名。

示例代码如下所示:

Untitled
std::vector<std::string> targetUserIDs;

ZIM::getInstance().queryRoomMembers(targetUserIDs, roomID, [targetRoomMemberMap](const std::string &roomID, const std::vector<ZIMRoomMemberInfo> &memberList,const std::vector<ZIMErrorUserInfo> &errorUserList, const ZIMError &errorInfo) {
    if (errorInfo.code != ZIMErrorCodeSuccess) {
        std::cout << "Query room members failed! error code: " << errorInfo.code << ", error message: " << errorInfo.message << std::endl;
        return;
    }

// userID 映射 ZIMRoomMemberInfo 的 map, 可以缓存起来用于后续 UI 展示,目前 ZIMRoomMemberInfo 暴露了 userID , userName。
    std::map<std::string, ZIMRoomMemberInfo> targetRoomMemberMap;

 // userID 映射 ZIMErrorUserInfo 的 map, 如果有需要关注失败原因可以读取此数据结构
    std::map<std::string, ZIMErrorUserInfo> targetErrorUserInfoMap;

    for (auto const& currentMemberInfo : memberList) {
        targetRoomMemberMap[currentMemberInfo.userID] = currentMemberInfo;
    }
    for (auto const& currentErrorUserInfo : errorUserList) {
        targetErrorUserInfoMap[currentErrorUserInfo.userID] = currentErrorUserInfo;
    }

// 判断是否目标成员是否在房间内
    bool isTargetUserIdAInTheRoom = std::find(targetRoomMemberMap.begin(), targetRoomMemberMap.end(), userIdA) != targetRoomMemberMap.end();
});
1
Copied!

Previous

房间属性管理

Next

群组管理