• UIKit
  • SDK
  • 服务端 API
Chat/
SDK/
Android/
消息/
SDK
  • 集成 SDK
  • 初始化
  • 登录登出
  • 消息
    • 介绍
    • 发送消息
    • 接收消息
    • 历史消息
    • 转发消息
    • 消息变更
    • 插入消息
    • 删除消息
    • 清空消息
    • 撤回消息
    • 在线消息
    • 已读回执
    • 查询消息
    • 群 @ 消息
    • 群定向消息
    • 消息免打套
    • 消息扩展
    • 消息回应
    • 消息翻译
    • 消息置顶
  • 会话
    • 介绍
    • 会话列表
    • 获取会话
    • 会话未读数
    • 置顶会话
    • 删除会话
    • 会话草稿
    • 会话标记
    • 会话分组
  • 群组
    • 介绍
    • 管理群组
    • 群资料
    • 管理群成员
    • 群成员资料
    • 自定义属性
    • 群计数器
  • 社群话题
    • 管理社群
    • 权限组
  • 用户
    • 用户资料
    • 用户状态
    • 管理好友
    • 好友分组
    • 黑名单
    • 关注与粉丝
  • 本地搜索
    • 搜索消息
    • 搜索好友
    • 搜索群组
    • 搜索群成员
  • 信令
  • 客户端 API
    • Java
  • 开发指引
  • 控制台指南
    • 创建和升级应用
    • 基本配置
    • 功能配置
    • 账号管理
    • 群组管理
    • 回调配置
  • 产品介绍
    • 消息管理
      • 单聊消息
      • 消息存储
      • 离线推送
      • 群消息
      • 消息格式
    • 账号系统
      • 登陆验证
      • 在线状态管理
    • 群相关
      • 群组系统
      • 群组管理
    • 用户资料和关系链
      • 资料管理
      • 关系链管理
  • 购买指南
    • 计费概述
    • 价格中心
  • 错误码

消息扩展

功能描述

消息扩展可以为消息增加 key/value 状态标识。基于消息扩展,我们可以实现投票、接龙、问卷调查等功能。
在投票场景,我们可以先通过 createCustomMessage (Android / iOS & Mac / Windows) 接口创建一条用于投票的自定义消息,其中 data 存储投票的标题和选项,然后用消息扩展 key 存储投票用户 ID,用消息扩展 value 存储投票用户选项,有了每个用户的投票选项,我们就可以动态计算出投票选项的用户占比。
在接龙场景,我们可以先通过 createCustomMessage 接口创建一条用于接龙的自定义消息,其中 data 存储接龙的标题,然后用消息扩展 key 存储接龙用户 ID,用消息扩展 value 存储接龙信息。
在问卷调查场景,我们可以先通过 createCustomMessage 接口创建一条用于问卷调查的自定义消息,其中 data 存储问卷调查的标题和选项,然后用消息扩展 key 存储问卷调查的用户 ID,用消息扩展 value 存储问卷调查信息。
说明:
该功能仅对进阶版客户开放,购买进阶版后可使用。
该功能仅增强版 6.7 及以上版本支持。
该功能需要先在 控制台 开启,开关路径:Applications > Your App > Chat > Configuration > Login and Message > Set message extension。
直播群(AVChatRoom)消息不支持该功能。

设置消息扩展

调用 setMessageExtensions (Android / iOS & Mac / Windows) 接口可以设置消息扩展,如果扩展 key 已经存在,则修改扩展的 value 信息,如果扩展 key 不存在,则新增扩展。
设置消息扩展接口入参详解如下:
属性
含义
说明
message
消息对象
消息需满足三个条件:
1. 消息发送前需设置 supportMessageExtension (Android / iOS & Mac / Windows) 为 YES。
2. 消息必须是发送成功的状态。
3. 消息不能是社群(Community)和直播群(AVChatRoom)消息。
extensions
扩展列表
如果扩展 key 已经存在,则修改扩展的 value 信息,如果扩展 key 不存在,则新增扩展。
说明:
1. 扩展 key 最大支持 100 字节,扩展 value 最大支持 1KB,单次最多支持设置 20 个扩展,单条消息最多可设置 300 个扩展。
2. 当多个用户同时设置或删除同一个扩展 key 时,只有第一个用户可以执行成功,其它用户会在设置回包收到 23001 错误码和最新的扩展信息,在收到错误码和扩展信息后,请按需重新发起设置操作。
3. 我们强烈建议不同的用户设置不同的扩展 key,这样大部分场景都不会冲突,例如投票、接龙、问卷调查,都可以把自己的 userID 作为扩展 key。
示例代码如下:
Android
iOS & Mac
Windows
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) {
// 设置消息扩展失败
}
});

NSMutableArray *extensionList = [NSMutableArray array];
V2TIMMessageExtension *extension1 = [[V2TIMMessageExtension alloc] init];
extension1.extensionKey = @"key1";
extension1.extensionValue = @"value1";
[extensionList addObject:extension1];
V2TIMMessageExtension *extension2 = [[V2TIMMessageExtension alloc] init];
extension2.extensionKey = @"key2";
extension2.extensionValue = @"value2";
[extensionList addObject:extension2];
[[V2TIMManager sharedInstance] setMessageExtensions:message extensions:extensionList succ:^(NSArray<V2TIMMessageExtensionResult *> *extensionResultList) {
// 设置消息扩展成功
} fail:^(int code, NSString *desc) {
// 设置消息扩展失败
}];
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_;
};

V2TIMMessageExtensionVector extensionList;
V2TIMMessageExtension extension1;
extension1.extensionKey = "key1";
extension1.extensionValue = "value1";
extensionList.PushBack(extension1);
V2TIMMessageExtension extension2;
extension2.extensionKey = "key2";
extension2.extensionValue = "value2";
extensionList.PushBack(extension2);

auto *callback = new ValueCallback<V2TIMMessageExtensionResultVector>{};
callback->SetCallback(
[=](const V2TIMMessageExtensionResultVector &extensionResultList) {
// 设置消息扩展成功
delete callback;
},
[=](int error_code, const V2TIMString &error_message) {
// 设置消息扩展失败
delete callback;
});

V2TIMManager::GetInstance()->GetMessageManager()->SetMessageExtensions(message, extensionList, callback);

获取消息扩展

调用 getMessageExtensions (Android / iOS & Mac / Windows) 接口获取消息扩展列表。
说明:
如果没有网络,SDK 会直接返回本地缓存的消息扩展列表。
示例代码如下:
Android
iOS & Mac
Windows
V2TIMManager.getMessageManager().getMessageExtensions(lastMsg, new V2TIMValueCallback<List<V2TIMMessageExtension>>() {
@Override
public void onSuccess(List<V2TIMMessageExtension> extensions) {
// 获取消息扩展成功
}

@Override
public void onError(int code, String desc) {
// 获取消息扩展失败
}
});
[[V2TIMManager sharedInstance] getMessageExtensions:message succ:^(NSArray<V2TIMMessageExtension *> *extensionList) {
// 获取消息扩展成功
} fail:^(int code, NSString *desc) {
// 获取消息扩展失败
}];
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_;
};

auto *callback = new ValueCallback<V2TIMMessageExtensionVector>{};
callback->SetCallback(
[=](const V2TIMMessageExtensionVector &extensionList) {
// 获取消息扩展成功
delete callback;
},
[=](int error_code, const V2TIMString &error_message) {
// 获取消息扩展失败
delete callback;
});

V2TIMManager::GetInstance()->GetMessageManager()->GetMessageExtensions(message, callback);

删除消息扩展

调用 deleteMessageExtensions (Android / iOS & Mac / Windows) 接口删除指定消息扩展,如果 keys 字段填 null/nil ,则会清空所有消息扩展。
示例代码如下:
Android
iOS & Mac
Windows
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) {
// 删除消息扩展失败
}
});
[[V2TIMManager sharedInstance] deleteMessageExtensions:message keys:@[@"key1",@"key2"] succ:^(NSArray<V2TIMMessageExtensionResult *> *extensionResultList){
// 删除消息扩展成功
} fail:^(int code, NSString *desc) {
// 删除消息扩展失败
}];
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_;
};

V2TIMStringVector keys;
keys.PushBack("key1");
keys.PushBack("key2");

auto *callback = new ValueCallback<V2TIMMessageExtensionResultVector>{};
callback->SetCallback(
[=](const V2TIMMessageExtensionResultVector &extensionResultList) {
// 删除消息扩展成功
delete callback;
},
[=](int error_code, const V2TIMString &error_message) {
// 删除消息扩展失败
delete callback;
});

V2TIMManager::GetInstance()->GetMessageManager()->DeleteMessageExtensions(message, keys, callback);

消息扩展更新

如果您事先调用 addAdvancedMsgListener 添加了高级消息事件监听器,当消息扩展发生了新增或者更新,您会收到 onRecvMessageExtensionsChanged (Android / iOS & Mac / Windows) 回调,当消息扩展发生了删除,您会收到 onRecvMessageExtensionsDeleted (Android / iOS & Mac / Windows) 回调。
示例代码如下:
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) {
// 收到消息扩展删除通知
}
});
[[V2TIMManager sharedInstance] addAdvancedMsgListener:self];
- (void)onRecvMessageExtensionsChanged:(NSString *)msgID extensions:(NSArray<V2TIMMessageExtension *> *)extensions {
// 收到消息扩展变更通知
}
- (void)onRecvMessageExtensionsDeleted:(NSString *)msgID extensionKeys:(NSArray<NSString *> *)extensionKeys {
// 收到消息扩展删除通知
}
class AdvancedMsgListener final : public V2TIMAdvancedMsgListener {
public:
void OnRecvMessageExtensionsChanged(const V2TIMString &msgID,
const V2TIMMessageExtensionVector &extensions) override {
// 收到消息扩展变更通知
}

void OnRecvMessageExtensionsDeleted(const V2TIMString &msgID,
const V2TIMStringVector &extensionKeys) override {
// 收到消息扩展删除通知
}
// 其他成员 ...
};

// 添加高级消息的事件监听器,注意在移除监听器之前需要保持 advancedMsgListener 的生命期,以免接收不到事件回调
AdvancedMsgListener advancedMsgListener;
V2TIMManager::GetInstance()->GetMessageManager()->AddAdvancedMsgListener(&advancedMsgListener);