无 UI 集成方案

服务端 API

诚邀爱技术、爱分享的你,成为文档内容共建者> HOT

功能描述

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

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

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

设置消息扩展

调用 setMessageExtensions (Android / iOS & Mac / Windows) 接口可以设置消息扩展,如果扩展 key 已经存在,则修改扩展的 value 信息,如果扩展 key 不存在,则新增扩展。

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

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

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

示例代码如下:

List<V2TIMMessageExtension> extensionList = new ArrayList<>();
V2TIMMessageExtension extension1 = new V2TIMMessageExtension();
extension1.setExtensionKey("key1");
extension1.setExtensionValue("value1");
extensionList.add(extension1);
V2TIMMessageExtension extension2 = new V2TIMMessageExtension();
extension2.setExtensionKey("key2");
extension2.setExtensionValue("value2");
extensionList.add(extension2);
V2TIMManager.getMessageManager().setMessageExtensions(lastMsg, extensionList, new V2TIMValueCallback<List<V2TIMMessageExtensionResult>>() {
    @Override
    public void onSuccess(List<V2TIMMessageExtensionResult> v2TIMMessageExtensionResults) {
        // 设置消息扩展成功
    }

    @Override
    public void onError(int code, String desc) {
        // 设置消息扩展失败
    }
});

获取消息扩展

调用 getMessageExtensions (Android / iOS & Mac / Windows) 接口获取消息扩展列表。

说明:

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

示例代码如下:

V2TIMManager.getMessageManager().getMessageExtensions(lastMsg, new V2TIMValueCallback<List<V2TIMMessageExtension>>() {
    @Override
    public void onSuccess(List<V2TIMMessageExtension> extensions) {
        // 获取消息扩展成功
    }

    @Override
    public void onError(int code, String desc) {
        // 获取消息扩展失败
    }
});

删除消息扩展

调用 deleteMessageExtensions (Android / iOS & Mac / Windows) 接口删除指定消息扩展,如果 keys 字段填 null/nil ,则会清空所有消息扩展。

示例代码如下:

List<String> keyList = new ArrayList<>();
keyList.add("key1");
keyList.add("key2");
V2TIMManager.getMessageManager().deleteMessageExtensions(lastMsg, keyList, new V2TIMValueCallback<List<V2TIMMessageExtensionResult>>() {
    @Override
    public void onSuccess(List<V2TIMMessageExtensionResult> v2TIMMessageExtensionResults) {
        // 删除消息扩展成功
    }

    @Override
    public void onError(int code, String desc) {
        // 删除消息扩展失败
    }
});

消息扩展更新

如果您事先调用 addAdvancedMsgListener 添加了高级消息事件监听器,当消息扩展发生了新增或者更新,您会收到 onRecvMessageExtensionsChanged (Android / iOS & Mac / Windows) 回调,当消息扩展发生了删除,您会收到 onRecvMessageExtensionsDeleted (Android / iOS & Mac / Windows) 回调。

示例代码如下:

V2TIMManager.getMessageManager().addAdvancedMsgListener(new V2TIMAdvancedMsgListener() {
        @Override
        public void onRecvMessageExtensionsChanged(String msgID, List<V2TIMMessageExtension> extensions) {
            // 收到消息扩展变更通知
        }

        @Override
        public void onRecvMessageExtensionsDeleted(String msgID, List<String> extensionKeys) {
            // 收到消息扩展删除通知
        }
});

交流与反馈

欢迎加入 QQ 群进行技术交流和反馈问题。

目录