Message Extension
The message extension feature allows you to add Key/Value-based status identifiers to the message object (RCMessage). The extension information of a message can be set or updated before or after sending, and can be used to implement business requirements such as message comments, gift redemption, and order status changes.
Whether a message can carry or set extension information is determined by the canIncludeExpansion property of the RCMessage when sending the message. This property must be set before sending and cannot be modified afterward. A single message can set up to 20 Key/Value pairs of extension information at a time, with a total of no more than 300 Key/Value pairs. In concurrent scenarios, if more than 300 pairs are set, the excess will be discarded.
The Key/Value extension information added to the RCMessage object will be stored. If the historical message cloud storage feature is enabled, historical messages retrieved from the server will also carry the set extension information.
- Message extension is only supported in one-to-one chat, group chat, and ultra group conversation types. It is not supported in chatroom and system conversation.
- The 4.x SDK supports the message extension feature starting from version 4.0.3.
Implementation Approach
Taking order status change as an example, the message display status can be changed through message extension. For order confirmation:
- When a user places an order for a specified product, the merchant needs to send an order confirmation message to the user. When sending the message, the
canIncludeExpansionproperty of the message object can be set to allow extension, and a Key/Value pair can be set to identify the order status. For example, before the user confirms, a Key/Value pair can be used to indicate that the order status is "Unconfirmed." - After the user clicks to confirm (or performs other confirmation actions) the order message, the order message status needs to be changed to "Confirmed." At this point, the
updateMessageExpansionmethod can be used to update the extension information of this message, marking it as confirmed, and changing the local display style of the message. - The sender can listen for message extension status changes, obtain the status changes of the specified message, and display the latest order status based on the latest extension information.
Message comments and gift redemption can be implemented with reference to the above approach:
- Gift Redemption: The message display status can be changed through message extension. For example, a gift is sent to the user with a default status of "Unredeemed," and the user can set the message extension to "Redeemed" upon clicking.
- Message Comments: Comments can be added by setting the extension information of the original message.
Enabling the Message Extension Property (Before Sending Only)
After constructing a new message, set the canIncludeExpansion property of the RCMessage to enable or disable the extension property of a message. This property must be set before sending the message.
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;
| Parameter | Type | Description |
|---|---|---|
| canIncludeExpansion | BOOL | Whether the message can be extended. YES: The message allows setting extension information. NO: The message does not allow setting extension information. This switch state cannot be changed after the message is sent. |
If the app inserts the message locally before sending it (for example, if the app requires message content review before sending), this property must be set when inserting the message (see Insert Message). Messages returned after successful local insertion do not support modifying the canIncludeExpansion property to change the extension property switch state.
Setting Message Extension Data (Before Sending Only)
If the message has the extension property enabled, the expansionDic property of the RCMessage can be called to set the extension data. This interface can only be called before the message is sent.
/*!
Message extension information list
@discussion Extension information is supported in one-to-one chat, group chat, and ultra group. Other conversation types cannot set extension information.
@discussion By default, the message extension dictionary key length does not exceed 32, the value length does not exceed 4096, the maximum number of extensions set at a time is 20, and the total number of extensions for a message cannot exceed 300.
*/
@property (nonatomic, strong) NSDictionary<NSString *, NSString *> *expansionDic;
The following example sets the extension information data for the previously constructed message msg and sends this text message via sendMessage.
msg.expansionDic = @{@"key1":@"value1",@"key2":@"value2"};
[[RCIMClient sharedRCIMClient] sendMessage:msg pushContent:nil pushData:nil successBlock:^(RCMessage *successMessage) {
} errorBlock:^(RCErrorCode nErrorCode, RCMessage *errorMessage) {
}];
| Parameter | Type | Description |
|---|---|---|
| expansionDic | NSDictionary | Message extension information. The maximum number of Key/Value pairs that can be set at a time is 20. A single message can set up to 300 extension information pairs.
|
The message sent in the above example will carry the extension data in the expansionDic property. After the message is successfully sent, the SDK will store the message and extension data in the local database.
If the message being sent already exists in the local database (see Insert Message), please note:
- （SDK ≧ 5.3.4）After successful sending, the SDK will refresh the extension data of the message in the local database.
- （SDK < 5.3.4）After successful sending, the SDK cannot refresh the extension data of the message in the local database. It is recommended that the app first sends the message and then updates the local and remote extension information by calling
updateMessageExpansion. The other end can receive the updated extension data through listening.
Updating Extension Data
Call the updateMessageExpansion method of RCIMClient to update the message extension information. Only messages with the extension property enabled are supported. After updating the message extension information, the initiator should handle UI data refresh in the success callback, and the other end of the conversation can receive the updated data through the message extension listener.
- Each time the message extension is updated (or deleted), the SDK will internally send a signal message of type
RC:MsgExMsgto the other end of the conversation. Therefore, frequent updates to the message extension will result in a large number of messages. - Each terminal can set extension information if the limit is not reached; in concurrent scenarios, if more than 300 pairs are set, the excess will be discarded.
// Update message extension information
[[RCCoreClient sharedCoreClient] updateMessageExpansion:dic messageUId:message.messageUId success:^{
RCMessage *msg = [[RCCoreClient sharedCoreClient] getMessageByUId:message.messageUId];
// The initiator handles UI data refresh after updating the extension here.
} error:^(RCErrorCode status) {
[self showToastMsg:[NSString stringWithFormat:@"msgUid:%@的KV更新失败%zd",message.messageUId,status]];
}];
| Parameter | Type | Description |
|---|---|---|
| expansionDic | NSDictionary | The Key/Value pairs of the message extension information to be updated.
|
| messageUId | NSString | The message messageUId |
| successBlock | Block | Success callback |
| errorBlock | Block | Failure callback. status contains the failure error code RCErrorCode |
Deleting Extension Data
After the message is sent, call the removeMessageExpansionForKey method of RCIMClient to delete specific Key/Value pairs in the message extension information. Only messages with the extension property enabled are supported. After deleting the message extension information, the initiator should handle the UI data refresh after deletion in the success callback, and the other end of the conversation can receive the notification through the message extension listener.
[[RCIMClient sharedRCIMClient] removeMessageExpansionForKey:keyArray messageUId:messageUId success:^{
} error:^(RCErrorCode status) {
}];
| Parameter | Type | Description |
|---|---|---|
| keyArray | NSArray | The list of keys to be deleted in the message extension information |
| messageUId | NSString | The message messageUId |
| successBlock | Block | Success callback |
| errorBlock | Block | Failure callback. status contains the failure error code RCErrorCode |
Listening for Message Extension Data Changes
After the message extension change initiator calls the API to update or delete extension data, the receiver can listen for extension data changes through the RCMessageExpansionDelegate protocol and handle them accordingly.
To implement this feature, developers need to comply with the RCMessageExpansionDelegate protocol.
[RCIMClient sharedRCIMClient].messageExpansionDelegate = self;
Delegate Methods
@protocol RCMessageExpansionDelegate <NSObject>
/**
Callback for message extension information changes
@param expansionDic The updated Key/Value pairs in the message extension information
@param message The message
@discussion expansionDic only contains the updated Key/Value pairs, not all the data. To get all the Key/Value pairs, use the expansionDic property of the message.
*/
- (void)messageExpansionDidUpdate:(NSDictionary<NSString *, NSString *> *)expansionDic
message:(RCMessage *)message;
/**
Callback for message extension information deletion
@param keyArray The list of keys deleted in the message extension information
@param message The message
*/
- (void)messageExpansionDidRemove:(NSArray<NSString *> *)keyArray
message:(RCMessage *)message;
@end