Overview
Starting from v7.0, Tencent Cloud Chat SDK provides the group counter feature. You can configure a certain number of counters for each group.
Unlike custom group attributes, group counters are used to store data of integer type. Group counters can be used to store additional information related to a group, such as the cumulative number of viewers, the number of views, the number of likes, and the number of gifts the audience has given to the host of an audio-video group. Group counter related methods are all in the core classes V2TIMGroupManager(Android)
/ V2TIMManager(Group)(iOS & Mac)
/ V2TIMGroupManager(Windows)
.
Note
Group counters support all types of groups, excluding topic-enabled community groups.
The group counter feature is supported only by the Premium edition.
Keep the following in mind for group counters:
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 five 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 five seconds in the SDK, and the 8516 error code will be called back if the limit is exceeded.
Setting Group Counters
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
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){
},
[=](int error_code, const V2TIMString& error_message){
});
V2TIMManager::GetInstance()->GetGroupManager()->SetGroupCounters(groupID, counters, callback);
}
Incrementing the Value of a Group Counter
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>>(){
@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){
},
[=](int error_code, const V2TIMString& error_message){
});
V2TIMManager::GetInstance()->GetGroupManager()->IncreaseGroupCounter(groupID, key, value, callback);
}
Decrementing the Value of a Group Counter
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>>(){
@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){
},
[=](int error_code, const V2TIMString& error_message){
});
V2TIMManager::GetInstance()->GetGroupManager()->decreaseGroupCounter(groupID, key, value, callback);
}
Getting 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>>() {
@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){
},
[=](int error_code, const V2TIMString& error_message){
});
V2TIMManager::GetInstance()->GetGroupManager()->GetGroupCounters(groupID, keys, callback);
}
Group Counter Change 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() {
@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 {
}
};
GroupListener listener;
V2TIMManager::GetInstance()->AddGroupListener(&listener);
Was this page helpful?