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 0HashMap<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>>(){@Overridepublic void onError(int code, String desc) {Log.d(TAG, "set group counters fail");}@Overridepublic 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.V2TIMManager.getGroupManager().increaseGroupCounter("your group id", "key1", 2, new V2TIMValueCallback<Map<String, Long>>(){@Overridepublic void onError(int code, String desc) {Log.d(TAG, "increase group counters fail");}@Overridepublic 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.V2TIMManager.getGroupManager().decreaseGroupCounter("your group id", "key1", 2, new V2TIMValueCallback<Map<String, Long>>(){@Overridepublic void onError(int code, String desc) {Log.d(TAG, "decrease group counters fail");}@Overridepublic 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
List<String> keyList = Arrays.asList("key1", "key2");V2TIMManager.getGroupManager().getGroupCounters("your group id", keyList, new V2TIMValueCallback<Map<String, Long>>() {@Overridepublic void onError(int code, String desc) {Log.d(TAG, "get group counters fail");}@Overridepublic 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:
private void initListener() {if (groupListener == null) {groupListener = new V2TIMGroupListener() {@Overridepublic 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.