tencent cloud

PrevNext

文档反馈

请输入关键字

Recent Pages

文档
即时通信 IM
    文档
    Download PDF

    Android&iOS&Windows&Mac

    最后更新时间：2024-08-09 11:51:54
    下载PDF

      功能描述

      群自定义属性是给每个群组开放了自定义键值对的能力。您可以用它存储一些群组纬度、键值对类型的附加信息，例如语聊房的麦位管理、群组活动、群组标签、群组积分系统等自定义信息。
      以语聊房麦位管理为例：
      有人上麦时，设置一个群属性管理上麦人信息。
      有人下麦时，删除对应群属性。
      其他群成员可以通过获取群属性列表来展示麦位列表，监听群属性更新刷新麦位列表。
      说明
      6.7 及其以前版本，只支持 AVChatRoom 直播群；
      从 6.8 版本开始，同时支持 AVChatRoom、Public、Meeting、Work 四种群类型；
      从 7.0 版本开始，除了话题外，群属性支持所有的群类型。

      接口说明

      初始化群属性

      调用 initGroupAttributes (Android / iOS & Mac / Windows) 接口可以初始化群属性。如果该群之前有群属性，会先清空原来的群属性。
      示例代码如下：
      Android
      iOS & Mac
      Windows
      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);

      设置群属性

      调用 setGroupAttributes (Android / iOS & Mac / Windows) 接口可以设置群属性。如果设置的群属性不存在，会自动添加该群属性。
      示例代码如下：
      Android
      iOS & Mac
      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() {
              // 设置群属性成功
        }
      
        @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);

      删除群属性

      调用 deleteGroupAttributes (Android / iOS & Mac / Windows) 接口可以删除指定群属性，如果 keys 字段填 null/nil ，则会清空所有的群属性。
      示例代码如下：
      Android
      iOS & Mac
      Windows
      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);

      获取群属性

      调用 getGroupAttributes (Android / iOS & Mac / Windows) 接口可以获取指定群属性，如果 keys 字段填 null/nil ，则会获取所有的群属性。
      说明
      getGroupAttributes 接口 SDK 限制为单个登录用户 5 秒 20 次。
      示例代码如下：
      Android
      iOS & Mac
      Windows
      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);

      群属性更新

      如果您事先调用 addGroupListener 添加了群组事件监听器，群属性有任何的更新变化，都会通过 onGroupAttributeChanged (Android / iOS & Mac / Windows) 回调出来所有的群属性字段。
      示例代码如下：
      Android
      iOS & Mac
      Windows
      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 groupListener;
      V2TIMManager::GetInstance()->AddGroupListener(&groupListener);

      接口限制

      1. 最多支持 16 个群属性，每个群属性的大小最大支持 4k，所有群属性的大小最大支持 16k。
      2. initGroupAttributes、setGroupAttributes、deleteGroupAttributes 接口合并计算，SDK 限制为单个登录用户 5 秒 10 次，超过后回调 8511 错误码；后台限制单个登录用户 1 秒 5 次，超过后返回 10049 错误码。
      3. getGroupAttributes 接口 SDK 限制为单个登录用户 5 秒 20 次。
      4. 从 5.6 版本开始，当每次APP启动后初次修改群属性时，请您先调用 getGroupAttributes 拉取到最新的群属性之后，再发起修改操作。
      5. 从 5.6 版本开始，当多个用户同时修改同一个群属性时，只有第一个用户可以执行成功，其它用户会收到 10056 错误码；收到这个错误码之后，请您调用 getGroupAttributes 把本地保存的群属性更新到最新之后，再发起修改操作。
      联系我们

      联系我们，为您的业务提供专属服务。

      联系我们
      技术支持

      如果你想寻求进一步的帮助，通过工单与我们进行联络。我们提供7x24的工单服务。

      提交工单
      7x24 电话支持
      Copyright © 2013-2024 Tencent Cloud. All Rights Reserved.
      隐私条款服务条款缓存条款