Overview
Group Custom Attributes enable each group to have its own set of custom key-value pairs. You can use this feature to store additional information specific to the group, such as managing seats in a voice chat room, organizing group activities, setting group tags, and implementing a group points system.
Taking the management of seats in a voice chat room as an example:
When someone takes the seat, set a group attribute to manage the user's information.
When someone leaves the seat, delete the corresponding group attribute.
Other group members can display and refresh the list of seats by retrieving the group attributes list and listening for updates on group attributes.
Note:
On versions 6.7 and earlier, only the audio-video group (AVChatRoom) is supported.
Starting from version 6.8, the audio-video group (AVChatRoom), public group (Public), meeting group (Meeting), and work group (Work) are supported.
Starting from version 7.0, group attributes support all group types except topics.
API Description
Initializing Group Attributes
Call the initGroupAttributes
API (Android / iOS and Mac / Windows) to initialize the group attributes, and the original group attributes, if any, will be cleared first. Sample code:
V2TIMManager.getGroupManager().initGroupAttributes("groupA", attributeMap, new V2TIMCallback() {
@Override
public void onSuccess() {
}
@Override
public void onError(int code, String desc) {
}
});
[[V2TIMManager sharedInstance] initGroupAttributes:@"groupA" attributes:@{@"key1" : @"value1"} succ:^{
} fail:^(int code, NSString *desc) {
}];
class Callback final : public V2TIMCallback {
public:
using SuccessCallback = std::function<void()>;
using ErrorCallback = std::function<void(int, const V2TIMString&)>;
Callback() = default;
~Callback() override = default;
void SetCallback(SuccessCallback success_callback, ErrorCallback error_callback) {
success_callback_ = std::move(success_callback);
error_callback_ = std::move(error_callback);
}
void OnSuccess() override {
if (success_callback_) {
success_callback_();
}
}
void OnError(int error_code, const V2TIMString& error_message) override {
if (error_callback_) {
error_callback_(error_code, error_message);
}
}
private:
SuccessCallback success_callback_;
ErrorCallback error_callback_;
};
V2TIMString groupID = "groupA";
V2TIMGroupAttributeMap attributes;
attributes.Insert("key1", "value1");
attributes.Insert("key2'", "value2");
auto callback = new Callback;
callback->SetCallback(
[=]() {
delete callback;
},
[=](int error_code, const V2TIMString& error_message) {
delete callback;
});
V2TIMManager::GetInstance()->GetGroupManager()->InitGroupAttributes(groupID, attributes, callback);
Setting Group Attributes
Call the setGroupAttributes
API (Android / iOS and Mac / Windows) to set the group attributes. If a group attribute doesn't exist, it will be automatically added. Sample code:
HashMap<String, String> attributeMap = new HashMap<>();
attributeMap.put("key1", "value1");
attributeMap.put("key2", "value2");
V2TIMManager.getGroupManager().setGroupAttributes("groupA", attributeMap, new V2TIMCallback() {
@Override
public void onSuccess() {
}
@Override
public void onError(int code, String desc) {
}
});
[[V2TIMManager sharedInstance] setGroupAttributes:@"groupA" attributes:@{@"key1" : @"value1"} succ:^{
} fail:^(int code, NSString *desc) {
}];
class Callback final : public V2TIMCallback {
public:
using SuccessCallback = std::function<void()>;
using ErrorCallback = std::function<void(int, const V2TIMString&)>;
Callback() = default;
~Callback() override = default;
void SetCallback(SuccessCallback success_callback, ErrorCallback error_callback) {
success_callback_ = std::move(success_callback);
error_callback_ = std::move(error_callback);
}
void OnSuccess() override {
if (success_callback_) {
success_callback_();
}
}
void OnError(int error_code, const V2TIMString& error_message) override {
if (error_callback_) {
error_callback_(error_code, error_message);
}
}
private:
SuccessCallback success_callback_;
ErrorCallback error_callback_;
};
V2TIMString groupID = "groupA";
V2TIMGroupAttributeMap attributes;
attributes.Insert("key1", "value1");
attributes.Insert("key2'", "value2");
auto callback = new Callback;
callback->SetCallback(
[=]() {
delete callback;
},
[=](int error_code, const V2TIMString& error_message) {
delete callback;
});
V2TIMManager::GetInstance()->GetGroupManager()->SetGroupAttributes(groupID, attributes, callback);
Deleting Group Attributes
Call the deleteGroupAttributes
API (Android / iOS and macOS / Windows) to delete a specified group attribute. If keys
is set to null
/nil
, all the group attributes will be cleared. Sample code:
List<String> keyList = new ArrayList<>();
keyList.add("key1");
V2TIMManager.getGroupManager().deleteGroupAttributes("groupA", keyList, new V2TIMCallback() {
@Override
public void onSuccess() {
}
@Override
public void onError(int code, String desc) {
}
});
[[V2TIMManager sharedInstance] deleteGroupAttributes:@"groupA" keys:@[@"key1"] succ:^{
} fail:^(int code, NSString *desc) {
}];
class Callback final : public V2TIMCallback {
public:
using SuccessCallback = std::function<void()>;
using ErrorCallback = std::function<void(int, const V2TIMString&)>;
Callback() = default;
~Callback() override = default;
void SetCallback(SuccessCallback success_callback, ErrorCallback error_callback) {
success_callback_ = std::move(success_callback);
error_callback_ = std::move(error_callback);
}
void OnSuccess() override {
if (success_callback_) {
success_callback_();
}
}
void OnError(int error_code, const V2TIMString& error_message) override {
if (error_callback_) {
error_callback_(error_code, error_message);
}
}
private:
SuccessCallback success_callback_;
ErrorCallback error_callback_;
};
V2TIMString groupID = "groupA";
V2TIMStringVector keys;
keys.PushBack("key1");
keys.PushBack("key2");
auto callback = new Callback;
callback->SetCallback(
[=]() {
delete callback;
},
[=](int error_code, const V2TIMString& error_message) {
delete callback;
});
V2TIMManager::GetInstance()->GetGroupManager()->DeleteGroupAttributes(groupID, keys, callback);
Getting Group Attributes
Call the getGroupAttributes
API (Android / iOS and macOS / Windows) to get a specified group attribute. If keys
is set to null
/nil
, all the group attributes will be obtained. Note
The getGroupAttributes
API can be called by a logged-in user 20 times every five seconds in the SDK.
Sample code:
V2TIMManager.getGroupManager().getGroupAttributes("groupA", null, new V2TIMValueCallback<Map<String, String>>() {
@Override
public void onSuccess(Map<String, String> stringStringMap) {
}
@Override
public void onError(int code, String desc) {
}
});
[[V2TIMManager sharedInstance] getGroupAttributes:@"groupA" keys:nil succ:^(NSMutableDictionary<NSString *,NSString *> *groupAttributeList) {
} fail:^(int code, NSString *desc) {
}];
template <class T>
class ValueCallback final : public V2TIMValueCallback<T> {
public:
using SuccessCallback = std::function<void(const T&)>;
using ErrorCallback = std::function<void(int, const V2TIMString&)>;
ValueCallback() = default;
~ValueCallback() override = default;
void SetCallback(SuccessCallback success_callback, ErrorCallback error_callback) {
success_callback_ = std::move(success_callback);
error_callback_ = std::move(error_callback);
}
void OnSuccess(const T& value) override {
if (success_callback_) {
success_callback_(value);
}
}
void OnError(int error_code, const V2TIMString& error_message) override {
if (error_callback_) {
error_callback_(error_code, error_message);
}
}
private:
SuccessCallback success_callback_;
ErrorCallback error_callback_;
};
auto callback = new ValueCallback<V2TIMGroupAttributeMap>{};
callback->SetCallback(
[=](const V2TIMGroupAttributeMap& groupAttributeMap) {
delete callback;
},
[=](int error_code, const V2TIMString& error_message) {
delete callback;
});
V2TIMManager::GetInstance()->GetGroupManager()->GetGroupAttributes("groupID", {}, callback);
Updating Group Attributes
If you have called addGroupListener
to add a group event listener, all the group attributes will be called back through onGroupAttributeChanged
(Android / iOS and macOS / Windows) when a group attribute is changed. Sample code:
V2TIMManager.getInstance().addGroupListener(new V2TIMGroupListener() {
@Override
public void onGroupAttributeChanged(String groupID, Map<String, String> groupAttributeMap) {
}
});
[[V2TIMManager sharedInstance] addGroupListener:self];
- (void)onGroupAttributeChanged:(NSString *)groupID attributes:(NSMutableDictionary<NSString *,NSString *> *)attributes {
}
class GroupListener final : public V2TIMGroupListener {
public:
GroupListener() = default;
~GroupListener() override = default;
void OnGroupAttributeChanged(const V2TIMString& groupID,
const V2TIMGroupAttributeMap& groupAttributeMap) override {
}
};
GroupListener groupListener;
V2TIMManager::GetInstance()->AddGroupListener(&groupListener);
API Limitations
1. You can configure up to 16 group attributes. The size of each group attribute can be up to 4 KB, and the total size of all group attributes can be up to 16 KB.
2. The initGroupAttributes
, setGroupAttributes
, and deleteGroupAttributes
APIs each can be called by a logged-in user up to 10 times every 5 seconds in the SDK, and the 8511 error code will be called back if the limit is exceeded. The APIs each can be called by a logged-in user up to 5 times every second in the backend, and the 10049 error code will be called back if the limit is exceeded.
3. The getGroupAttributes
API can be called by a logged-in user 20 times every 5 seconds in the SDK.
4. Starting from version 5.6, when you modify group attributes for the first time after the app is started, call getGroupAttributes
to pull the latest group attributes before you initiate the modification operation.
5. Starting from version 5.6, when multiple users modify the same group attributes at the same time, only the first user can execute successfully, and other users will receive the 10056 error code. After receiving this error code, call getGroupAttributes
to update the locally stored group attributes to the latest before you initiate the modification operation.
Was this page helpful?