tencent cloud

Android&iOS&Windows&Mac
Download PDF
Last updated:2025-01-06 17:46:31
Android&iOS&Windows&Mac
Last updated: 2025-01-06 17:46:31
Download PDF

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 (Java / Swift / Objective-C / C++) to initialize the group attributes, and the original group attributes, if any, will be cleared first.
Sample code:
Java
Swift
Objective-C
C++
V2TIMManager.getGroupManager().initGroupAttributes("groupA", attributeMap, new V2TIMCallback() {
  @Override
  public void onSuccess() {
        // Initialized the group attributes successfully
  }

  @Override
  public void onError(int code, String desc) {
        // Failed to initialized the group attributes
  }
});
V2TIMManager.shared.initGroupAttributes(groupID: "groupID", attributes: ["key1":"value1", "key2":"value2"]) {
    print( "initGroupAttributes succ")
} fail: { code, desc in
    print( "initGroupAttributes fail, \\(code), \\(desc)")
}
[[V2TIMManager sharedInstance] initGroupAttributes:@"groupA" attributes:@{@"key1" : @"value1"} succ:^{
    // Initialized the group attributes successfully
} fail:^(int code, NSString *desc) {
    // Failed to initialized the group attributes
}];

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(
    [=]() {
        // Initialized the group attributes successfully
        delete callback;
    },
    [=](int error_code, const V2TIMString& error_message) {
        // Failed to initialized the group attributes
        delete callback;
    });

V2TIMManager::GetInstance()->GetGroupManager()->InitGroupAttributes(groupID, attributes, callback);

Setting Group Attributes

Call the setGroupAttributes API (Java / Swift / Objective-C / C++) to set the group attributes. If a group attribute doesn't exist, it will be automatically added.
Sample code:
Java
Swift
Objective-C
C++
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() {
        // Set the group attributes successfully
  }

  @Override
  public void onError(int code, String desc) {
        // Failed to set the group attributes
  }
});
V2TIMManager.shared.setGroupAttributes(groupID: "groupID", attributes: ["key1": "modify value1"]) {
    print( "setGroupAttributes succ")
} fail: { code, desc in
    print( "setGroupAttributes fail, \\(code), \\(desc)")
}
[[V2TIMManager sharedInstance] setGroupAttributes:@"groupA" attributes:@{@"key1" : @"value1"} succ:^{
    // Set the group attributes successfully
} fail:^(int code, NSString *desc) {
    // Failed to set the group attributes
}];
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(
    [=]() {
        // Set the group attributes successfully
        delete callback;
    },
    [=](int error_code, const V2TIMString& error_message) {
        // Failed to set the group attributes
        delete callback;
    });

V2TIMManager::GetInstance()->GetGroupManager()->SetGroupAttributes(groupID, attributes, callback);

Deleting Group Attributes

Call the deleteGroupAttributes API (Java / Swift / Objective-C / C++) to delete a specified group attribute. If keys is set to null/nil, all the group attributes will be cleared.
Sample code:
Java
Swift
Objective-C
C++
List<String> keyList = new ArrayList<>();
keyList.add("key1");
V2TIMManager.getGroupManager().deleteGroupAttributes("groupA", keyList, new V2TIMCallback() {
  @Override
  public void onSuccess() {
      // Deleted successfully
  }

  @Override
  public void onError(int code, String desc) {
      // Failed to delete
  }
});
V2TIMManager.shared.deleteGroupAttributes(groupID: "groupID", keys: ["key1"]) {
    print( "deleteGroupAttributes succ")
} fail: { code, desc in
    print( "deleteGroupAttributes fail, \\(code), \\(desc)")
}
[[V2TIMManager sharedInstance] deleteGroupAttributes:@"groupA" keys:@[@"key1"] succ:^{
    // Deleted successfully
} fail:^(int code, NSString *desc) {
    // Failed to delete
}];
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(
    [=]() {
        // The group attributes deleted successfully
        delete callback;
    },
    [=](int error_code, const V2TIMString& error_message) {
        // Failed to delete the group attributes
        delete callback;
    });

V2TIMManager::GetInstance()->GetGroupManager()->DeleteGroupAttributes(groupID, keys, callback);

Getting Group Attributes

Call the getGroupAttributes API (Java / Swift / Objective-C / C++) 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:
Java
Swift
Objective-C
C++
V2TIMManager.getGroupManager().getGroupAttributes("groupA", null, new V2TIMValueCallback<Map<String, String>>() {
  @Override
  public void onSuccess(Map<String, String> stringStringMap) {
      // Obtained successfully
  }

  @Override
  public void onError(int code, String desc) {
      // Failed to obtain
  }
});
V2TIMManager.shared.getGroupAttributes(groupID: "groupID", keys: nil) { map in
    map.forEach { (key: String, value: String) in
        print( "\\(key): \\(value)")
    }
} fail: { code, desc in
    print( "getGroupAttributes fail, \\(code), \\(desc)")
}
[[V2TIMManager sharedInstance] getGroupAttributes:@"groupA" keys:nil succ:^(NSMutableDictionary<NSString *,NSString *> *groupAttributeList) {
    // Obtained successfully
} fail:^(int code, NSString *desc) {
    // Failed to obtain
}];
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) {
        // The group attributes obtained successfully
        delete callback;
    },
    [=](int error_code, const V2TIMString& error_message) {
        // Failed to obtain the group attributes
        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 (Java / Swift / Objective-C / C++) when a group attribute is changed.
Sample code:
Java
Swift
Objective-C
C++
V2TIMManager.getInstance().addGroupListener(new V2TIMGroupListener() {
  @Override
  public void onGroupAttributeChanged(String groupID, Map<String, String> groupAttributeMap) {
      // A group attribute was changed.
  }
});
V2TIMManager.shared.addGroupListener(listener: self)
func onGroupAttributeChanged(groupID: String, attributes: Dictionary<String, String>) {
  print( "groupID:\\(groupID), attributes:\\(attributes)")
}
[[V2TIMManager sharedInstance] addGroupListener:self];
- (void)onGroupAttributeChanged:(NSString *)groupID attributes:(NSMutableDictionary<NSString *,NSString *> *)attributes {
    // A group attribute was changed.
}
class GroupListener final : public V2TIMGroupListener {
public:
    GroupListener() = default;
    ~GroupListener() override = default;

    void OnGroupAttributeChanged(const V2TIMString& groupID,
                                 const V2TIMGroupAttributeMap& groupAttributeMap) override {
        // A group attribute was changed.
    }
    // Other members …
};
// Add a group event listener. Keep `groupListener` valid before the listener is removed to ensure event callbacks are received.
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?
You can also Contact Sales or Submit a Ticket for help.
Yes
No

Feedback