tencent cloud

文档反馈

最后更新时间:2023-02-24 15:04:06

    功能描述

    消息扩展可以为消息增加 key/value 状态标识。基于消息扩展,我们可以实现投票、接龙、问卷调查等功能。

    • 在投票场景,我们可以先通过 createCustomMessage (点击查看详情) 接口创建一条用于投票的自定义消息,其中 data 存储投票的标题和选项,然后用消息扩展 key 存储投票用户 ID,用消息扩展 value 存储投票用户选项,有了每个用户的投票选项,我们就可以动态计算出投票选项的用户占比。
    • 在接龙场景,我们可以先通过 createCustomMessage 接口创建一条用于接龙的自定义消息,其中 data 存储接龙的标题,然后用消息扩展 key 存储接龙用户 ID,用消息扩展 value 存储接龙信息。
    • 在问卷调查场景,我们可以先通过 createCustomMessage 接口创建一条用于问卷调查的自定义消息,其中 data 存储问卷调查的标题和选项,然后用消息扩展 key 存储问卷调查的用户 ID,用消息扩展 value 存储问卷调查信息。
    说明:

    • 该功能仅对旗舰版客户开放,购买旗舰版后可使用。
    • 该功能仅SDK 4.1.8 及以上版本支持。
    • 该功能需要先在 即时通信 IM 控制台 > 功能配置 > 登录与消息 > 消息扩展设置中开启。
    • 社群(Community)和直播群(AVChatRoom)消息不支持该功能。

    设置消息扩展

    调用 setMessageExtensions (点击查看详情) 接口可以设置消息扩展,如果扩展 key 已经存在,则修改扩展的 value 信息,如果扩展 key 不存在,则新增扩展。

    设置消息扩展接口入参详解如下:

    属性 含义 说明
    message 消息对象 消息需满足三个条件:
    • 消息发送前需设置 supportMessageExtension (Flutter) 为 YES。
    • 消息必须是发送成功的状态。
    • 消息不能是社群(Community)和直播群(AVChatRoom)消息。
    extensions 扩展列表 如果扩展 key 已经存在,则修改扩展的 value 信息,如果扩展 key 不存在,则新增扩展。
    说明:

    1. 扩展 key 最大支持 100 字节,扩展 value 最大支持 1KB,单次最多支持设置 20 个扩展,单条消息最多可设置 300 个扩展。
    1. 当多个用户同时设置或删除同一个扩展 key 时,只有第一个用户可以执行成功,其它用户会在设置回包收到 23001 错误码和最新的扩展信息,在收到错误码和扩展信息后,请按需重新发起设置操作。
    2. 我们强烈建议不同的用户设置不同的扩展 key,这样大部分场景都不会冲突,例如投票、接龙、问卷调查,都可以把自己的 userID 作为扩展 key。

    示例代码如下:

        // 设置消息扩展
        V2TimValueCallback<List<V2TimMessageExtensionResult>>
            setMessageExtensionsRes = await TencentImSDKPlugin.v2TIMManager
                .getMessageManager()
                .setMessageExtensions(msgID: '', // 需要扩展的消息id
                    extensions: []); // 消息扩展字段
        if (setMessageExtensionsRes.code == 0) {
          // 设置消息扩展成功
        }
    

    获取消息扩展

    调用 getMessageExtensions (点击查看详情) 接口获取消息扩展列表。

    说明:

    如果没有网络,SDK 会直接返回本地缓存的消息扩展列表。

    示例代码如下:

        // 获取消息扩展
        V2TimValueCallback<List<V2TimMessageExtension>> getMessageExtensionsRes =
            await TencentImSDKPlugin.v2TIMManager
                .getMessageManager()
                .getMessageExtensions(
                  msgID: '', // 需要获取扩展信息的消息id
                );
        if (getMessageExtensionsRes.code == 0) {
          // 获取消息扩展成功
          getMessageExtensionsRes.data?.forEach((element) {
            element.extensionKey; // 被更改的扩展字段key
            element.extensionValue; // 被更改的扩展字段values
          });
        }
    

    删除消息扩展

    调用 deleteMessageExtensions (点击查看详情) 接口删除指定消息扩展,如果 keys 字段填 null ,则会清空所有消息扩展。

    示例代码如下:

        // 删除消息扩展
        V2TimValueCallback<List<V2TimMessageExtensionResult>>
            deleteMessageExtensionsRes = await TencentImSDKPlugin.v2TIMManager
                .getMessageManager()
                .deleteMessageExtensions(msgID: '', // 需要删除扩展的消息id
                    keys: []); // 需要删除的扩展字段的key的列表
        if (deleteMessageExtensionsRes.code == 0) {
          // 删除消息扩展成功
          deleteMessageExtensionsRes.data?.forEach((element) {
            element.extension; //消息扩展信息
            element.resultCode; //操作结果码
            element.resultInfo; //描述信息
          });
        }
    

    消息扩展更新

    如果您事先调用 addAdvancedMsgListener 添加了高级消息事件监听器,当消息扩展发生了新增或者更新,您会收到 onRecvMessageExtensionsChanged (点击查看详情) 回调,当消息扩展发生了删除,您会收到 onRecvMessageExtensionsDeleted (点击查看详情) 回调。

    示例代码如下:

        //创建消息监听器
        V2TimAdvancedMsgListener listener = V2TimAdvancedMsgListener(
          onRecvMessageExtensionsChanged:
              (String msgID, List<V2TimMessageExtension> extensions) {
            // msgID 被更改的消息id
            // extensions 被更改的扩展字段列表
            for (V2TimMessageExtension element in extensions) {
              element.extensionKey; // 被更改的扩展字段key
              element.extensionValue; // 被更改的扩展字段values
            }
          },
          onRecvMessageExtensionsDeleted: (msgID, extensionKeys) {
            // msgID 被删除扩展信息的消息id
            // extensionKeys 被删除扩展信息的key列表
          },
        );
        // 添加高级消息的事件监听器
        TencentImSDKPlugin.v2TIMManager
            .getMessageManager()
            .addAdvancedMsgListener(listener: listener);
    
    联系我们

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

    技术支持

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

    7x24 电话支持