tencent cloud

PrevNext

文档反馈

请输入关键字

Recent Pages

文档
即时通信 IM
    文档
    Download PDF

    Android&iOS&Windows&Mac

    最后更新时间：2024-09-18 16:43:44
    下载PDF

      功能描述

      群计数器是给每个群组开放了一个用于存储整数类型数据的能力。您可以用它存储一些群组纬度、整数类型的附加信息，例如直播群的累计观看人数、观看人次、主播被点赞的次数、观众累计送给主播的礼物数等。
      说明
      该功能仅进阶版本支持，需要购买进阶版。
      该功能仅增强版 SDK 7.0 及以上版本支持。
      除了话题外，群计数器支持所有的群类型。

      效果展示

      您可以使用群计数器实现如下的效果：
      
      
      

      接口说明

      设置群计数器

      您可以调用接口 setGroupCounters（Android / iOS & Mac / Windows）设置多组群计数器。计数器设置成功后会触发 onGroupCounterChanged （Android / iOS & Mac / Windows）回调，onGroupCounterChanged 的使用参见下文的 群计数器变更通知。
      说明
      如果您即将设置的计数器的 key 存在，则直接更新计数器的 value 值；如果不存在，则直接添加 key-value。
      如果多个用户同时设置同一个计数器时，计数器最终的值会相互覆盖，推荐由群主发起设置操作。
      示例：调用 setGroupCounters 接口分别设置计数器 key1 和 key2 的值为 0。
      Android
      iOS & Mac
      Windows
      HashMap<String, Long> counters = new HashMap<>();
      counters.put("key1", 0);
      counters.put("key2", 0);
      V2TIMManager.getGroupManager().setGroupCounters("your group id", counters, new V2TIMValueCallback<Map<String, Long>>(){
          @Override
          public void onError(int code, String desc) {
              Log.d(TAG, "set group counters fail");
          }
      
          @Override
          public void onSuccess(Map<String, Long> stringLongMap) {
              Log.d(TAG, "set group counters succ");
          }
      });
      NSDictionary *counters = @{
          @"key1": @(0),
          @"key2": @(0)
      };
      [V2TIMManager.sharedInstance setGroupCounters:@"your group id" counters:counters succ:^(NSDictionary<NSString *,NSNumber *> *groupCounters) {
          NSLog(@"set group counters succ");
      } fail:^(int code, NSString *desc) {
          NSLog(@"set group counters fail");
      }];
      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_;
      };
      
      void setGroupCounters() {
          V2TIMString groupID = "your group id";
          V2TIMStringToInt64Map counters;
          counters.Insert("key1", 0);
          counters.Insert("key2", 0);
      
          auto callback = new ValueCallback<V2TIMStringToInt64Map>{};
          callback->SetCallback(
              [=](const V2TIMStringToInt64Map &counters){
                  // succ
              },
              [=](int error_code, const V2TIMString& error_message){
                  // fail
              });
          V2TIMManager::GetInstance()->GetGroupManager()->SetGroupCounters(groupID, counters, callback);
      }

      递增群计数器

      您可以调用递增接口 increaseGroupCounter (Android / iOS & Mac / Windows) 对群计数器作累加操作，操作成功后会触发 onGroupCounterChanged （Android / iOS & Mac / Windows）回调。onGroupCounterChanged 的使用参见下文的 群计数器变更通知。
      说明
      接口参数中的 value 为变化量，调用接口后会在当前值的基础上累加传入的变化量；
      如果您即将设置的计数器的 key 存在，则直接在当前值的基础上根据传入的 value 作递增操作；反之，添加 key，并在默认值为 0 的基础上根据传入的 value 作递增操作。
      示例：假设当前的计数器 key1 的值是 8，调用 increaseGroupCounter 接口传入的递增变化量 value 为 2 后，最终 key1 的值变为 10。
      Android
      iOS & Mac
      Windows
      V2TIMManager.getGroupManager().increaseGroupCounter("your group id", "key1", 2, new V2TIMValueCallback<Map<String, Long>>(){
          @Override
          public void onError(int code, String desc) {
              Log.d(TAG, "increase group counters fail");
          }
      
          @Override
          public void onSuccess(Map<String, Long> stringLongMap) {
              Log.d(TAG, "increase group counters succ");
          }
      });
      [V2TIMManager.sharedInstance increaseGroupCounter:@"your group id" key:@"key1" value:2 succ:^(NSDictionary<NSString *,NSNumber *> *groupCounters) {
          NSLog(@"increase group counters succ");
      } fail:^(int code, NSString *desc) {
          NSLog(@"increase group counters fail");
      }];
      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_;
      };
      
      void increaseGroupCounters() {
          V2TIMString groupID = "your group id";
            V2TIMString key = "key1";
            int64_t value = 2;
      
          auto callback = new ValueCallback<V2TIMStringToInt64Map>{};
          callback->SetCallback(
              [=](const V2TIMStringToInt64Map &counters){
                  // succ
              },
              [=](int error_code, const V2TIMString& error_message){
                  // fail
              });
          V2TIMManager::GetInstance()->GetGroupManager()->IncreaseGroupCounter(groupID, key, value, callback);
      }

      递减群计数器

      您可以调用递减接口 decreaseGroupCounter (Android / iOS & Mac / Windows) 对群计数器作累减操作，操作成功后会触发 onGroupCounterChanged （Android / iOS & Mac / Windows）回调，onGroupCounterChanged 的使用参见下文的 群计数器变更通知。
      说明
      接口参数中的 value 为递减的变化量，调用接口后会在当前值的基础上减去传入的变化量；
      如果您即将设置的计数器的 key 存在，则直接在当前值的基础上根据传入的 value 作递减操作；反之，添加 key，并在默认值为 0 的基础上根据传入的 value 作递减操作。
      示例：假设当前的计数器 key1 的值是 8，调用 decreaseGroupCounter 接口传入的递减变化量 value 为 2 后，最终 key1 的值变为 6。
      Android
      iOS & Mac
      Windows
      V2TIMManager.getGroupManager().decreaseGroupCounter("your group id", "key1", 2, new V2TIMValueCallback<Map<String, Long>>(){
          @Override
          public void onError(int code, String desc) {
              Log.d(TAG, "decrease group counters fail");
          }
      
          @Override
          public void onSuccess(Map<String, Long> stringLongMap) {
              Log.d(TAG, "decrease group counters succ");
          }
      });
      [V2TIMManager.sharedInstance decreaseGroupCounter:@"your group id" key:@"key1" value:2 succ:^(NSDictionary<NSString *,NSNumber *> *groupCounters) {
          NSLog(@"decrease group counters succ");
      } fail:^(int code, NSString *desc) {
          NSLog(@"decrease group counters fail");
      }];
      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_;
      };
      
      void decreaseGroupCounters() {
          V2TIMString groupID = "your group id";
            V2TIMString key = "key1";
            int64_t value = 2;
      
          auto callback = new ValueCallback<V2TIMStringToInt64Map>{};
          callback->SetCallback(
              [=](const V2TIMStringToInt64Map &counters){
                  // succ
              },
              [=](int error_code, const V2TIMString& error_message){
                  // fail
              });
          V2TIMManager::GetInstance()->GetGroupManager()->decreaseGroupCounter(groupID, key, value, callback);
      }

      获取群计数器

      您可以调用接口 getGroupCounters (Android / iOS & Mac / Windows) ，并通过传入一组指定的 key 来获取对应的群计数器信息。接口会返回所有的与 key 相匹配的 key-value 键值对。
      说明
      如果传入的 key 列表为空，则返回所有的群计数器。
      示例：调用接口 getGroupCounters 分别获取计数器 key1 和 key2 的值。
      Android
      iOS & Mac
      Windows
      List<String> keyList = Arrays.asList("key1", "key2");
      V2TIMManager.getGroupManager().getGroupCounters("your group id", keyList, new V2TIMValueCallback<Map<String, Long>>() {
          @Override
          public void onError(int code, String desc) {
              Log.d(TAG, "get group counters fail");
          }
      
          @Override
          public void onSuccess(Map<String, Long> stringLongMap) {
              Log.d(TAG, "get group counters succ");
          }
      });
      [V2TIMManager.sharedInstance getGroupCounters:@"your group id" keys:@[@"key1", @"key2"] succ:^(NSDictionary<NSString *,NSNumber *> *groupCounters) {
          NSLog(@"get group counters succ");
      } fail:^(int code, NSString *desc) {
          NSLog(@"get group counters fail");
      }];
      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_;
      };
      
      void getGroupCounters() {
          V2TIMString groupID = "your group id";
          V2TIMStringVector keys;
          keys.PushBack("key1");
          keys.PushBack("key2");
      
          auto callback = new ValueCallback<V2TIMStringToInt64Map>{};
          callback->SetCallback(
              [=](const V2TIMStringToInt64Map &counters){
                  // succ
              },
              [=](int error_code, const V2TIMString& error_message){
                  // fail
              });
          V2TIMManager::GetInstance()->GetGroupManager()->GetGroupCounters(groupID, keys, callback);
      }

      群计数器变更通知

      当您调用 setGroupCounters、increaseGroupCounter、decreaseGroupCounter 接口修改群计数器时，会触发 onGroupCounterChanged 回调，并返回变化后的 value 值。
      说明
      在使用上述回调之前，您需要调用接口 addGroupListener （Android / iOS & Mac / Windows）添加群监听器。
      示例代码如下：
      Android
      iOS & Mac
      Windows
      private void initListener() {
          if (groupListener == null) {
              groupListener = new V2TIMGroupListener() {
                  @Override
                  public void onGroupCounterChanged(String groupID, String key, long newValue) {
                      StringBuilder stringBuilder = new StringBuilder();
                      stringBuilder.append("onGroupCounterChanged groupID:").append(groupID).append("\\n");
                      stringBuilder.append("key:").append(key).append(", newValue:").append(String.valueOf(newValue)).append("\\n");
                      String result = "onGroupCounterChanged :" + stringBuilder.toString();
                      Log.d(TAG, result);
                  }
              };
              V2TIMManager.getInstance().addGroupListener(groupListener);
          }
      }
      [V2TIMManager.sharedInstance addGroupListener:self];
      
      #pragma mark - V2TIMGroupListener
      - (void)onGroupCounterChanged:(NSString *)groupID key:(NSString *)key newValue:(NSInteger)newValue {
          NSLog(@"groupID:%@, changed:\\n%@:%zd\\n", groupID, key, newValue);
      }
      class GroupListener final : public V2TIMGroupListener {
      public:
          GroupListener() = default;
          ~GroupListener() override = default;
      
          void OnGroupCounterChanged(const V2TIMString &groupID, const V2TIMString &key, int64_t newValue) override {
              // changed
          }
      };
      
      GroupListener listener;
      V2TIMManager::GetInstance()->AddGroupListener(&listener);

      接口限制

      1. 单个群内最大支持 20 组群计数器，也即单个群内 key 的个数不超过 20 个；
      2. 单个群计数器的 key 不超过 128 个字符，value 必须为整数类型（最大支持 64 位有符号整型）；
      3. setGroupCounters、increaseGroupCounter、decreaseGroupCounter 接口合并计算，SDK 限制为单个登录用户最多 5 秒调用 20 次，超过限制后接口回调 8516 错误码；
      4. getGroupCounters 接口单独计算，SDK 限制为单个登录用户最多 5 秒 20 次调用，超过限制后接口回调 8516 错误码。
      联系我们

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

      联系我们
      技术支持

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

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