消息扩展
消息扩展功能可为消息增加基于 Key/Value 的状态标识。消息的扩展信息可在发送前、后设置或更新,可用于实现消息评论、礼物领取、订单状态变化等业务需求。
一条消息是否可携带或可设置扩展信息,由发送消息时 Message
的可扩展(canIncludeExpansion
)属性决定,发送后无法修改该属性。因此消息发送前需要将消息设置为可扩展,才能对该条消息进行扩展信息添加、删除等操作。
单条消息单次最多可设置 20 个扩展信息 KV 对,总计不可超过 300 个扩展信息 KV 对。在并发情况下如出现设置超过 300 个的情况,超出部分会被丢弃删除。
消息扩展(Key、Value 扩展信息)会被存储。如已开通历史消息云存储功能, 从服务端获取的历史消息也会携带已设置的扩展信息。
- 2.x SDK 从
2.5.12
版本开始支持消息扩展功能。- 仅支持单聊、群聊会话类型。不支持聊天室和系统会话。
实现思路
以订单状态变化为例,可通过消息扩展改变消息显示状态。以订单确认为例:
- 当用户购买指定产品下单后,商家需要向用户发送订单确认信息。可在发送消息时,将
canIncludeExpansion
属性设置为可扩展,同时设置用于标识订单状态的 Key 和 Value。例如,在用户未确认前,可用一对 Key/Value 表示该订单状态为「未确认」。 - 用户点击确认(或其他确认操作)该订单消息后,订单消息状态需要变更为「已确认」。此时,可通过
updateMessageExpansion
更新此条消息的扩展信息,标识为已确认状态,同时更改本地显示的消息样式。 - 发送方通过消息扩展状态监听,获取指定消息的状态变化,根据最新扩展信息显示最新的订单状态。
消息评论、礼物领取可参照以上实现思路:
- 礼物领取:可通过消息扩展改变消息显示状态实现。例如,向用户发送礼物,默认为未领取状态,用户点击后可设置消息扩展为已领取状态。
- 消息评论:可通过设置原始消息扩展信息的方式添加评论信息。
设置监听
RongIMClient.setMessageExpansionListener({
onUpdated: function(updatedExpansion) { // 新增、修改扩展监听
/*
updatedExpansion: {
expansion: { key: value },
messageUId: 'BKCP-VBUT-0006-9GPP'
}
*/
var expansion = updatedExpansion.expansion; // 新增、修改的扩展信息
var messageUId = updatedExpansion.messageUId; // 扩展消息的 messageUId
},
onDeleted: function(deletedExpansion) { // 删除扩展监听
/*
deletedExpansion: {
deletedKeys: ['key1', 'key2'],
messageUId: 'BKCP-VBUT-0006-9GPP'
}
*/
let deletedKeys = deletedExpansion.deletedKeys; // 删除扩展的 keys
let messageUId = deletedExpansion.messageUId; //扩展消息的 messageUId
}
})
设置消息是否支持扩展
发消息前,设置 CanIncludeExpansion
属性为 true
,打开消息的可扩展属性。在 expansion
中设置发消息时需要携带的扩展信息。
API 参考:sendMessage
注意:
- 设置消息扩展后,会产生内置消息。频繁设置扩展会产生大量消息,如果对消息量增长敏感,请谨慎使用此功能。
CanIncludeExpansion
属性在发送消息的时候可以设置,消息发出去之后不可更改。- 会话列表最后一条消息仅保存发送时携带的扩展,后续更新、删除扩展不会影响会话列表最后一条消息的扩展内容。
参数说明:
参数 | 类型 | 必填 | 默认值 | 说明 |
---|---|---|---|---|
canIncludeExpansion | Boolean | 否 | false | 是否支持扩展。 |
expansion | Object | 否 | -- | 扩展内容。详见 expansion 参数说明。 |
-
expansion
参数说明- 单次最大设置扩展信息键值对 20 对。单条消息可设置最多 300 个扩展信息。
- Key 支持大小写英文字母、数字、 特殊字符
+ = - _
的组合方式,不支持汉字。最大 32 个字符。 - (SDK < 5.2.0)Value 最大 64 个字符。
- (SDK ≧ 5.2.0)Value 最大 4096 个字符。
代码示例
var conversationType = RongIMLib.ConversationType.PRIVATE; // 群聊, 其他会话选择相应的消息类型即可
var targetId = '接收方的 userId'; // 目标 Id
var msg = new RongIMLib.TextMessage({ content: 'hello RongCloud!', extra: '附加信息'});
var config = {
canIncludeExpansion: true, //是否支持扩展
expansion: { key: '这是 value' } //消息直接携带的扩展
};
RongIMClient.getInstance().sendMessage(conversationType, targetId, msg, {
onSuccess: function (message) {
console.log('发送文本消息成功', message);
},
onError: function (errorCode) {
console.log('发送文本消息失败', errorCode);
}
}, false, null, null, null, config);
更新扩展
更新消息的扩展内容
API 参考:updateMessageExpansion
参数说明:
参数 | 类型 | 必填 | 默认值 | 说明 |
---|---|---|---|---|
expansion | Object | 是 | --- | 扩展内容 |
message | Object | 是 | --- | 原消息体 |
callback | Object | 是 | --- | 回调对象 |
callback.onSuccess | Function | 是 | --- | 成功回调 |
callback.onError | Function | 是 | --- | 失败回调 |
代码示例:
var expansion = {
key: '这是 value'
};
var message = {
conversationType: 1,
targetId: 'user1',
messageUId: 'BK96-PP18-OIQ6-9GPP',
canIncludeExpansion: true
// ....
};
RongIMClient.getInstance().updateMessageExpansion(expansion, message, {
onSuccess: function () {
console.log('设置成功')
},
onError: function (reason) {
console.log('设置失败', reason)
}
});
删除扩展
API 参考:removeMessageExpansionForKey
参数说明:
参数 | 类型 | 必填 | 默认值 | 说明 |
---|---|---|---|---|
keys | Array | 是 | -- | 删除的 keys |
message | Object | 是 | -- | 原消息体 |
callback | Object | 是 | -- | 回调对象 |
callback.onSuccess | Function | 是 | -- | 成功回调 |
callback.onError | Function | 是 | -- | 失败回调 |
代码示例:
var keys = ['key1', 'key2'];
var message = {
conversationType: 1,
targetId: 'user1',
messageUId: 'BK96-PP18-OIQ6-9GPP'
//...
};
RongIMClient.getInstance().removeMessageExpansionForKey(keys, message, {
onSuccess: function () {
console.log('删除成功')
},
onError: function (reason) {
console.log('删除失败')
}
});