Docs Overview/
Chat/
SDK/
Android/
Group/
Counter/

Counter

Overview

Group counters provide each group with the capability to store data of integer type. You can use it to store additional information on a group level, such as the cumulative viewer count, viewing count, number of likes, and the total number of gifts in an audio-video group.
Note:
This feature is only supported in the Premium Edition, and requires purchasing the Premium Edition.
This feature is only supported in the Enhanced SDK version 7.0 and later.
Group counters support all types of groups, excluding topic-enabled community groups.

Effect

You can use group counters to achieve the following effects:




API Description

Setting Group Counters

Call the setGroupCounters (Android / iOS & macOS / Windows) API to set group counters. After group counters are set, the onGroupCounterChanged (Android / iOS & Mac / Windows) callback will be triggered. For usage of the onGroupCounterChanged callback, see Group Counter Change Notification.
Note
If the key of the group counter to be set already exists, the value of key is updated directly. Otherwise, a key-value pair will be added.
If multiple users set the same counter at the same time, the final value of the counter will be used. It's recommended that the group owner performs counter setting operations.
Sample: Call the setGroupCounters API to set the values of counters key1 and key2 to 0
Android
iOS and macOS
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);
}

Increase Group Counter

Call the increaseGroupCounter (Android / iOS & macOS / Windows) API to increment the value of a group counter. After the value of the group counter is incremented, the onGroupCounterChanged (Android / iOS & Mac / Windows) callback will be triggered. For the usage of the onGroupCounterChanged callback, see Group Counter Change Notification.
Note
The API parameter value is the change value. Each time when the API is called, the current value is incremented by the value passed in.
If the key of the group counter to be set already exists, the current value is directly incremented by the value passed in. Otherwise, a key will be added, and the default value (0) is incremented by the value passed in.
Sample: Assume that the current value of counter key1 is 8. After you call the increaseGroupCounter API to pass in an increment value 2, the final value of key1 becomes 10.
Android
iOS and macOS
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);
}

Decrase Group Counter

Call the decreaseGroupCounter (Android / iOS & macOS / Windows) API to decrement the value of a group counter. After the value of the group counter is decremented, the onGroupCounterChanged (Android / iOS & macOS / Windows) callback will be triggered. For the usage of the onGroupCounterChanged callback, see Group Counter Change Notification.
Note
The API parameter value is the change value. Each time when the API is called, the current value is decremented by the value passed in.
If the key of the group counter to be set already exists, the current value is directly decremented by the value passed in. Otherwise, a key will be added, and the default value (0) is decremented by the value passed in.
Sample: Assume that the current value of counter key1 is 8. After you call the decreaseGroupCounter API to pass in a decrement value 2, the final value of key1 becomes 6.
Android
iOS and macOS
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);
}

Get Group Counters

Call the getGroupCounters (Android / iOS & macOS / Windows) API to pass in a set of keys to get the information of the corresponding group counters. The API will return all key-value pairs matching the keys passed in.
Note
If the key list passed in is empty, all group counters are returned.
Sample: Call the getGroupCounters API to get the values of group counters key1 and key2
Android
iOS and macOS
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);
}

Group Counter Changed Notification

When you call the setGroupCounters, increaseGroupCounter, or decreaseGroupCounter API to modify group counters, the SDK will trigger the onGroupCounterChanged callback and return the updated values.
Note
Before you can use the above-mentioned callback, you need to call the addGroupListener (Android / iOS & macOS / Windows) API to add a group listener.
Sample code:
Android
iOS and macOS
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);

API Limitations

1. A single group supports up to 20 group counters, that is, up to 20 keys per group.
2. For a single group counter, the key can contain up to 128 bytes, and the value must be of integer type (signed integer of up to 64 bits).
3. The setGroupCounters, increaseGroupCounter, and decreaseGroupCounter APIs together can be called by a logged-in user up to 20 times every 5 seconds in the SDK, and the 8516 error code will be called back if the limit is exceeded.
4. The getGroupCounters API can be called by a logged-in user up to 20 times every 5 seconds in the SDK, and the 8516 error code will be called back if the limit is exceeded.