跳到主要内容

消息扩展

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

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

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

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

实现思路

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

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

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

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

打开消息的可扩展属性(仅发送前)

构建新消息后,设置 RCMessagecanIncludeExpansion 属性打开或关闭某条消息的可扩展属性。必须在发送消息前设置该属性。

RCTextMessage *txt = [RCTextMessage messageWithContent:text];

RCMessage *msg = [[RCMessage alloc] initWithType:self.conversationType targetId:self.targetId direction:(MessageDirection_SEND) messageId:-1 content:txt];
msg.canIncludeExpansion = YES;
参数类型说明
canIncludeExpansionBOOL该条消息是否可扩展。YES:该消息允许设置扩展信息。NO:该消息不允许设置扩展信息。消息发送之后不允许再更改该开关状态。

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

设置消息扩展数据(仅发送前)

如果消息已打开可扩展属性,可调用 RCMessageexpansionDic 属性设置扩展数据。该接口仅可在消息发送前调用。

/*!
消息扩展信息列表

@discussion 扩展信息支持单聊、群组、超级群,其它会话类型不能设置扩展信息
@discussion 默认消息扩展字典 key 长度不超过 32 ,value 长度不超过 4096 ,单次设置扩展数量最大为 20,消息的扩展总数不能超过 300
*/
@property (nonatomic, strong) NSDictionary<NSString *, NSString *> *expansionDic;

以下示例为之前构建的消息 msg 设置了扩展信息数据,并通过 sendMessage 发送了这条文本消息。

msg.expansionDic = @{@"key1":@"value1",@"key2":@"value2"};

[[RCIMClient sharedRCIMClient] sendMessage:msg pushContent:nil pushData:nil successBlock:^(RCMessage *successMessage) {

} errorBlock:^(RCErrorCode nErrorCode, RCMessage *errorMessage) {

}];
参数类型说明
expansionDicNSDictionary消息扩展信息。单次最大设置扩展信息键值对 20 对。单条消息可设置最多 300 个扩展信息。
  • Key 支持大小写英文字母、数字、 特殊字符+ = - _ 的组合方式,不支持汉字。最大 32 个字符。
  • (SDK < 5.2.0)Value 最大 64 个字符
  • (SDK ≧ 5.2.0)Value 最大 4096 个字符

上例中发送的消息会携带 expansionDic 属性中的扩展数据。消息发送成功后,SDK 会将消息及扩展数据存入本地数据库。

如果发送的是本地数据库中已存在的消息(详见插入消息),请注意:

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

更新扩展数据

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

提示
  • 每次更新(或删除)消息扩展时,SDK 内部将向会话对端发送一条类型标识为 RC:MsgExMsg 的消息扩展信令消息。因此,频繁更新消息扩展会导致产生大量消息。
  • 每个终端在设置扩展信息时,如未达到上限都可以进行设置;在并发情况下,会出现设置超过 300 的情况,超出部分会被丢弃。
// 更新消息扩展信息
[[RCCoreClient sharedCoreClient] updateMessageExpansion:dic messageUId:message.messageUId success:^{
RCMessage *msg = [[RCCoreClient sharedCoreClient] getMessageByUId:message.messageUId];
// 更新发起者在这里处理更新扩展后的 UI 数据刷新
} error:^(RCErrorCode status) {
[self showToastMsg:[NSString stringWithFormat:@"msgUid:%@的KV更新失败%zd",message.messageUId,status]];
}];
参数类型说明
expansionDicNSDictionary要更新的消息扩展信息键值对。
  • Key 支持大小写英文字母、数字、 特殊字符+ = - _ 的组合方式,不支持汉字。最大 32 个字符。
  • (SDK < 5.2.0)Value 最大 64 个字符
  • (SDK ≧ 5.2.0)Value 最大 4096 个字符
messageUIdNSString消息 messageUId
successBlockBlock成功的回调
errorBlockBlock失败的回调。status 包含失败的错误码 RCErrorCode

删除扩展数据

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

[[RCIMClient sharedRCIMClient] removeMessageExpansionForKey:keyArray messageUId:messageUId success:^{

} error:^(RCErrorCode status) {

}];
参数类型说明
keyArrayNSArray消息扩展信息中待删除的 key 的列表
messageUIdNSString消息 messageUId
successBlockBlock成功的回调
errorBlockBlock失败的回调。status 包含失败的错误码 RCErrorCode

监听消息扩展数据变更

消息扩展变更发起方调用 API 更新、删除扩展数据后,接收方可通过 RCMessageExpansionDelegate 协议中的代理方法监听扩展数据变更,并进行相应处理。

实现此功能需要开发者遵守 RCMessageExpansionDelegate 协议。

[RCIMClient sharedRCIMClient].messageExpansionDelegate = self;

代理方法

@protocol RCMessageExpansionDelegate <NSObject>
/**
消息扩展信息更改的回调

@param expansionDic 消息扩展信息中更新的键值对
@param message 消息

@discussion expansionDic 只包含更新的键值对,不是全部的数据。如果想获取全部的键值对,请使用 message 的 expansionDic 属性。
*/
- (void)messageExpansionDidUpdate:(NSDictionary<NSString *, NSString *> *)expansionDic
message:(RCMessage *)message;

/**
消息扩展信息删除的回调

@param keyArray 消息扩展信息中删除的键值对 key 列表
@param message 消息

*/
- (void)messageExpansionDidRemove:(NSArray<NSString *> *)keyArray
message:(RCMessage *)message;

@end