跳到主要内容
版本：2.X

消息扩展

消息扩展功能可为消息增加基于 Key/Value 的状态标识。消息的扩展信息可在发送前、后设置或更新，可用于实现消息评论、礼物领取、订单状态变化等业务需求。

一条消息是否可携带或可设置扩展信息，由发送消息时 Message 的可扩展（canIncludeExpansion）属性决定，发送后无法修改该属性。因此消息发送前需要将消息设置为可扩展，才能对该条消息进行扩展信息添加、删除等操作。

单条消息单次最多可设置 20 个扩展信息 KV 对，总计不可超过 300 个扩展信息 KV 对。在并发情况下如出现设置超过 300 个的情况，超出部分会被丢弃删除。

消息扩展（Key、Value 扩展信息）会被存储。如已开通历史消息云存储功能，从服务端获取的历史消息也会携带已设置的扩展信息。

  • 2.x SDK 从 2.5.12 版本开始支持消息扩展功能。
  • 仅支持单聊、群聊会话类型。不支持聊天室和系统会话。

实现思路​

以订单状态变化为例，可通过消息扩展改变消息显示状态。以订单确认为例：

  1. 当用户购买指定产品下单后，商家需要向用户发送订单确认信息。可在发送消息时，将 canIncludeExpansion 属性设置为可扩展，同时设置用于标识订单状态的 Key 和 Value。例如，在用户未确认前，可用一对 Key/Value 表示该订单状态为「未确认」。
  2. 用户点击确认（或其他确认操作）该订单消息后，订单消息状态需要变更为「已确认」。此时，可通过 updateMessageExpansion 更新此条消息的扩展信息，标识为已确认状态，同时更改本地显示的消息样式。
  3. 发送方通过消息扩展状态监听，获取指定消息的状态变化，根据最新扩展信息显示最新的订单状态。

消息评论、礼物领取可参照以上实现思路：

  • 礼物领取：可通过消息扩展改变消息显示状态实现。例如，向用户发送礼物，默认为未领取状态，用户点击后可设置消息扩展为已领取状态。
  • 消息评论：可通过设置原始消息扩展信息的方式添加评论信息。

设置监听​

  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 属性在发送消息的时候可以设置，消息发出去之后不可更改。
  • 会话列表最后一条消息仅保存发送时携带的扩展，后续更新、删除扩展不会影响会话列表最后一条消息的扩展内容。

参数说明:

参数类型必填默认值说明
canIncludeExpansionBoolean否false是否支持扩展。
expansionObject否--扩展内容。详见 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

参数说明:

参数类型必填默认值说明
expansionObject是---扩展内容
messageObject是---原消息体
callbackObject是---回调对象
callback.onSuccessFunction是---成功回调
callback.onErrorFunction是---失败回调

代码示例:

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

参数说明:

参数类型必填默认值说明
keysArray是--删除的 keys
messageObject是--原消息体
callbackObject是--回调对象
callback.onSuccessFunction是--成功回调
callback.onErrorFunction是--失败回调

代码示例:

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('删除失败')
  }
});
最后于 更新