tencent cloud

文档反馈

JavaScript

最后更新时间:2024-11-15 10:51:59

    功能描述

    Chat SDK 提供了群计数器的功能,每个群都可以设置一定数量的计数器。
    与 群自定义属性不同,群计数器主要用来存储整数类型的数据,您可以使用群计数器来存储一些群相关的附加信息,例如直播群的累计观看人数、观看人次、主播被点赞的次数、观众累计送给主播的礼物数等。
    说明:
    1. 除了话题外,群计数器支持所有的群类型。
    2. 该功能仅进阶版本支持,需要购买进阶版
    关于群计数器,需要注意的是:
    1. 单个群内最大支持 20 组群计数器,也即单个群内 key 的个数不超过 20 个。
    2. 单个群计数器的 key 不超过 128 个字符,value 必须为整数类型(最大支持 64 位有符号整型)。
    3. setGroupCountersincreaseGroupCounterdecreaseGroupCounter 接口合并计算,SDK 限制为单个登录用户最多 5 秒调用 20 次,超过限制后接口返回 2996 错误码。
    4. getGroupCounters 接口单独计算,SDK 限制为单个登录用户最多 5 秒 20 次调用,超过限制后接口返回 2996 错误码。

    效果展示

    

    设置群计数器

    计数器设置成功后会触发 TencentCloudChat.EVENT.GROUP_COUNTER_UPDATED 事件。
    说明
    1. 如果您即将设置的计数器的 key 存在,则直接更新计数器的 value 值;如果不存在,则直接添加 key-value。
    2. 如果多个用户同时设置同一个计数器时,计数器最终的值会相互覆盖,推荐由群主发起设置操作。
    接口
    chat.setGroupCounters(options);
    参数
    参数 optionsObject 类型,包含的属性值如下:
    参数
    类型
    说明
    groupID
    String
    群组 ID
    counters
    Object
    群计数器 key-value
    返回值
    Promise
    示例
    // 设置计数器 key1 和 key2 的值为 0
    let promise = chat.setGroupCounters({
    groupID: 'group1',
    counters: { key1: 0, key2: 0 }
    });
    promise.then(function(imResponse) { // 设置成功
    console.log(imResponse.data.counters); // 设置成功的群计数器
    }).catch(function(imError) { // 设置失败
    console.warn('setGroupCounters error:', imError); // 设置群计数器失败的相关信息
    });

    递增群计数器

    操作成功后会触发 TencentCloudChat.EVENT.GROUP_COUNTER_UPDATED 事件。
    说明
    1. 接口参数中的 value 为变化量,调用接口后会在当前值的基础上累加传入的变化量;
    2. 如果您即将设置的计数器的 key 存在,则直接在当前值的基础上根据传入的 value 作递增操作;反之,添加 key,并在默认值为 0 的基础上根据传入的 value 作递增操作。
    接口
    chat.increaseGroupCounter(options);
    参数
    参数 optionsObject类型,包含的属性值如下:
    参数
    类型
    说明
    groupID
    String
    群组 ID
    key
    String
    群计数器 key
    value
    Number
    群计数器 key 的变化量
    返回值
    Promise
    示例
    // 假设当前的计数器 key1 的值是 8,调用 increaseGroupCounter 接口传入的递增变化量 value 为 2 后
    // 最终 key1 的值变为 10。
    let promise = chat.increaseGroupCounter({
    groupID: 'group1',
    key: 'key1',
    value: 2,
    });
    promise.then(function(imResponse) { // 递增成功
    console.log(imResponse.data);
    const { groupID, key, value } = imResponse.data;
    }).catch(function(imError) { // 递增失败
    console.warn('increaseGroupCounter error:', imError);
    });

    递减群计数器

    操作成功后会触发 TencentCloudChat.EVENT.GROUP_COUNTER_UPDATED 事件。
    说明
    1. 接口参数中的 value 为递减的变化量,调用接口后会在当前值的基础上减去传入的变化量;
    2. 如果您即将设置的计数器的 key 存在,则直接在当前值的基础上根据传入的 value 做递减操作;反之,添加 key,并在默认值为 0 的基础上根据传入的 value 作递减操作。
    接口
    chat.decreaseGroupCounter(options);
    参数
    参数 optionsObject 类型,包含的属性值如下:
    参数
    类型
    说明
    groupID
    String
    群组 ID
    key
    String
    群计数器 key
    value
    Number
    群计数器 key 的变化量
    返回值
    Promise
    示例
    // 假设当前的计数器 key1 的值是 8.
    // 调用 decreaseGroupCounter 接口传入的递减变化量 value 为 2 后
    // 最终 key1 的值变为 6。
    let promise = chat.decreaseGroupCounter({
    groupID: 'group1',
    key: 'key1',
    value: 2
    });
    promise.then(function(imResponse) { // 递减成功
    console.log(imResponse.data);
    const { groupID, key, value } = imResponse.data;
    }).catch(function(imError) { // 设置失败
    console.warn('decreaseGroupCounter error:', imError);
    });

    获取群计数器

    说明:
    如果不传 keyList,则返回所有的群计数器。
    接口
    chat.getGroupCounter(options);
    参数
    参数 optionsObject类型,包含的属性值如下:
    参数
    类型
    说明
    groupID
    String
    群组 ID
    keyList
    Array | undefined
    群计数器 key 列表
    返回值
    Promise
    示例
    // 获取群计数器 key1 和 key2 的值
    let promise = chat.getGroupCounters({
    groupID: 'group1',
    keyList: ['key1', 'key2']
    });
    promise.then(function(imResponse) { // 获取成功
    console.log(imResponse.data.counters);
    }).catch(function(imError) {
    console.warn('getGroupCounters error:', imError); // 获取群计数器失败的相关信息
    });
    // 获取某一个群组全部的计数器
    let promise = chat.getGroupCounters({
    groupID: 'group1'
    });
    promise.then(function(imResponse) { // 获取成功
    console.log(imResponse.data.counters);
    }).catch(function(imError) {
    console.warn('getGroupCounters error:', imError); // 获取群计数器失败的相关信息
    });

    群计数器变更通知

    当您调用 setGroupCountersincreaseGroupCounterdecreaseGroupCounter 接口修改群计数器时,会触发 TencentCloudChat.EVENT.GROUP_COUNTER_UPDATED 事件,并返回变化后的 value 值。
    示例
    let onGroupCounterUpdated = function(event) {
    const { groupID, key, value } = event.data;
    // groupID - 群组 ID
    // key - 群计数器 key
    // value - 群计数器 key 对应的 value
    };
    chat.on(TencentCloudChat.EVENT.GROUP_COUNTER_UPDATED, onGroupCounterUpdated);
    
    联系我们

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

    技术支持

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

    7x24 电话支持