• IMLib / IMKit >
 
• 无 UI SDK（IMLib） >
 
• 消息相关 >
 
• 消息扩展

消息扩展

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

一条消息是否可携带或可设置扩展信息，由发送消息时 Message 的可扩展（canIncludeExpansion）属性决定，该属性必须在发送前设置，发送后无法修改。单条消息单次最多可设置 20 个扩展信息 KV 对，总计不可超过 300 个扩展信息 KV 对。在并发情况下如出现设置超过 300 个的情况，超出部分会被丢弃。

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

实现思路

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

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

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

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

打开消息的可扩展属性（仅发送前）

构建新消息后，调用 Message 的 setCanIncludeExpansion() 方法打开或关闭某条消息的可扩展属性。必须在发送消息前设置该属性。

 
TextMessage textMessage = TextMessage.obtain("content");
Message message = Message.obtain("userId", Conversation.ConversationType.PRIVATE, textMessage);
message.setCanIncludeExpansion(true);
              

                
已复制
                复制代码
              
              
1
2
3

如果 App 先在本地插入消息，再发送本地已插入的消息（例如 App 业务要求在发送前审核消息内容），则必须在插入消息时设置此属性（详见插入消息）。本地插入成功后返回的消息不支持再通过 setCanIncludeExpansion 修改可扩展属性开关的状态。

设置消息扩展数据（仅发送前）

如果消息已打开可扩展属性，可调用 Message 的 setExpansion 方法设置扩展数据。该接口仅可在消息发送前调用。

 
/** 为消息设置扩展数据 */
HashMap expansionKey = new HashMap();
expansionKey.put("key", "value");
message.setExpansion(expansionKey);

/** 发送消息 */
RongIMClient.getInstance().sendMessage(message, null, null, new IRongCallback.ISendMessageCallback() {
    @Override
    public void onAttached(io.rong.imlib.model.Message message) {

    }

    @Override
    public void onSuccess(io.rong.imlib.model.Message message) {

    }

    @Override
    public void onError(io.rong.imlib.model.Message message, RongIMClient.ErrorCode errorCode) {

    }
});
              

                
已复制
                复制代码
              
              
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22

上例中发送的消息会携带 setExpansion 方法设置的扩展数据。消息发送成功后，SDK 会将消息及扩展数据存入本地数据库。

如果发送的是本地数据库中已存在的消息（详见插入消息），请注意：

• （SDK ≧ 5.3.4）发送成功后 SDK 会刷新本地数据库中消息的扩展数据。
• （SDK < 5.3.4）发送成功后 SDK 无法刷新本地数据库中消息的扩展数据。建议 App 先发送消息，再通过调用 updateMessageExpansion 更新本地与远端的扩展信息。对端可通过监听收到扩展数据更新。

更新扩展数据

调用 RongIMClient 的 updateMessageExpansion() 方法更新消息扩展信息。仅支持已打开可扩展属性的消息。更新消息扩展信息后，更新发起者应在成功回调里处理 UI 数据刷新，会话对端可通过消息扩展监听器收到更新的数据。

 
RongIMClient.getInstance()
        .updateMessageExpansion(
                expansionMap,
                messageUId,
                new RongIMClient.OperationCallback() {
                    @Override
                    public void onSuccess() {
                     // 更新发起者在这里处理更新扩展后的 UI 数据刷新

                    }

                    @Override
                    public void onError(RongIMClient.ErrorCode errorCode) {
                        Toast.makeText(
                                        getApplicationContext(),
                                        "设置失败，ErrorCode : " + errorCode.getValue(),
                                        Toast.LENGTH_LONG)
                                .show();
                    }
                });
              

                
已复制
                复制代码
              
              
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

删除扩展数据

消息发送后调用 RongIMClient 的 removeMessageExpansion 方法删除消息扩展信息中特定的键值对。仅支持已打开可扩展属性的消息。删除消息扩展信息后，发起者应在成功回调里处理删除后的数据刷新，会话对端可通过消息扩展监听器收到通知。

 
RongIMClient.getInstance().removeMessageExpansion(keyArray, messageUId, callback);
              

                
已复制
                复制代码
              
              
1

监听消息扩展数据变更

消息扩展变更的发起方调用 API 更新、删除扩展数据后，SDK 内部将向会话对端发送一条类型标识为 RC:MsgExMsg 的消息扩展信令消息。MessageExpansionListener 监听器会在 SDK 接收该信令消息后触发相应的回调方法。

调用 RongIMClient 的 setMessageExpansionListener 方法设置消息扩展监听器。

 
RongIMClient.getInstance().setMessageExpansionListener(listener);
              

                
已复制
                复制代码
              
              
1

• MessageExpansionListener 说明

  返回值	方法	触发时机
  void	onMessageExpansionUpdate()	消息扩展信息更改时
  void	onMessageExpansionRemove()	消息扩展信息删除时

  • onMessageExpansionUpdate(Map<String, String> expansion, Message message)

    触发时机：消息扩展信息更改时

    参数	类型	说明
    expansion	Map<String, String>	消息扩展信息中被更新的键值对。只包含更新的键值对，不是全部数据。如果想获取全部的键值对，请使用 Message 对象的 expansion 属性。
    message	Message	消息对象

  • onMessageExpansionRemove(List<String> keyArray, Message message)

    触发时机：消息扩展信息删除时

    参数	类型	说明
    keyArray	List<String>	消息扩展信息中被删除的键值对 key 列表
    message	Message	消息对象