tencent cloud

PrevNext

Feedback

search by keyword

Recent Pages

Documentation
Chat
    Documentation
    Download PDF

    Android&iOS&Windows&Mac

    Last updated: 2023-07-17 15:48:28
    Download PDF

      Overview

      New custom group fields, also called group attributes, are designed based on API 2.0. With group attributes, you can manage the seats of audio chat rooms. When a user mics on, you can set a group attribute to manage the information of the user. When the user mics off, you can delete the group attribute. Other members can get the list of group attributes to display the seat list. Group attributes are represented by key-value pairs, and the methods are in the V2TIMGroupManager(Android) / V2TIMManager(Group)(iOS and macOS) core class.
      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.
      The group attribute has the following features:
      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 ten times every five 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 five 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 five 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.

      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:
      Android
      iOS and macOS
      Windows
      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 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 (Android / iOS and Mac / Windows) to set the group attributes. If a group attribute doesn't exist, it will be automatically added.
      Sample code:
      Android
      iOS and macOS
      Windows
      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 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 (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:
      Android
      iOS and macOS
      Windows
      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 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 (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:
      Android
      iOS and macOS
      Windows
      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 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 (Android / iOS and macOS / Windows) when a group attribute is changed.
      Sample code:
      Android
      iOS and macOS
      Windows
      V2TIMManager.getInstance().addGroupListener(new V2TIMGroupListener() {
        @Override
        public void onGroupAttributeChanged(String groupID, Map<String, String> groupAttributeMap) {
            // A group attribute was changed.
        }
      });
      [[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);
      
      Contact Us

      Contact our sales team or business advisors to help your business.

      Contact Us
      Technical Support

      Open a ticket if you're looking for further assistance. Our Ticket is 7x24 avaliable.

      Submit a Ticket
      7x24 Phone Support
      Copyright © 2013-2024 Tencent Cloud. All Rights Reserved.
      Privacy PolicyLegalCookie Policy