Set message extension field
Introduction
ZEGOCLOUD Instant Messaging (ZIM) SDK allows you to add an extension field to a message and send the extension field as additional message information. Message extension fields can be visible to the peer end or visible only to the local end based on the synchronization effects. A message extension field is used to present information such as the translation status and translation content of a message, and the business logic included in the message.
Implementation Steps
- Create a ZIM instance.
- Log in to the ZIM SDK.
- Construct the ZIMMessage object, and fill in the ZIMMessage field in the extendedData object as the message extension field.
- Call the sendMessage interface, pass in the ZIMMessage object, send the message and expand the fields.
// 1. Create a ZIM object and pass in the AppID
ZIMAppConfig appConfig = ZIMAppConfig();
appConfig.appID = appID;
appConfig.appSign = appSign;
ZIM.create(appConfig);
// 2. Login
try {
ZIMLoginConfig loginConfig = ZIMLoginConfig();
// User nickname, leave it blank if you don't want to modify the nickname
loginConfig.userName = 'userName';
// If using token for login authentication, please fill in this parameter, otherwise leave it blank
loginConfig.token = '';
// Whether this login is an offline login, please refer to the offline login documentation for details
loginConfig.isOfflineLogin = false;
await ZIM.getInstance()?.login('zego', loginConfig);
// Login successful, write your business logic for successful login
} on PlatformException catch (onError) {
// Login failed
// Error code for login failure, please refer to the error code table in the documentation for handling
onError.code;
// Error message for login failure
onError.message;
}
// 3. Send a message
ZIMTextMessage textMessage = ZIMTextMessage(message: "message");
textMessage.extendedData = @"Extended data to be sent"; // Extended data to be sent
ZIMMessageSendConfig sendConfig = ZIMMessageSendConfig();
// Set message priority
sendConfig.priority = ZIMMessagePriority.low;
ZIMMessageSendNotification notification = ZIMMessageSendNotification(onMessageAttached: (message) {
// Callback before sending, developers can get a temporary object here, which is the same object as the zimMessage created by the developer. Developers can use this feature to do some business logic, such as displaying UI in advance, etc.
});
// 4. Set the conversation type and send the message to the corresponding conversation type
// Send a message in a one-on-one conversation
ZIMConversationType type = ZIMConversationType.peer;
// Send a message in a group conversation
ZIMConversationType type = ZIMConversationType.room;
// Send a message in a chat room
ZIMConversationType type = ZIMConversationType.group;
ZIM.getInstance()!.sendMessage(textMessage, toConversationID, type, sendConfig).then((value) => {
// Developers can use this callback to listen for whether the message was sent successfully.
}).catchError((onError) {
// Developers can catch the exception if the message fails to send.
});
Configure an extension field visible only to the local end
Procedure for sending a message:
- Log in to ZIM SDK, construct a ZIMMessagefield as an extension field visible only to the local end in the ZIMMessage object.
- Call the sendMessage operation and pass in the ZIMMessage object to send the message and the extension field.
// 1. Configure the local extension field of a message.
// Specify the session ID.
String toConversationID = "xxx1";
// Construct a ZIMMessage object.
ZIMTextMessage zimTextMessage = ZIMTextMessage(message: 'message');
// Configure the local extension field of a message.
zimTextMessage.localExtendedData = "Local extension field of the message";
ZIMMessageSendConfig config = ZIMMessageSendConfig();
// Configure the priority of the message.
config.priority = ZIMMessagePriority.low;
// Send a private-chat message.
ZIMConversationType type = ZIMConversationType.peer;
// Send a group-chat message.
ZIMConversationType type = ZIMConversationType.group;
// Send a room message.
ZIMConversationType type = ZIMConversationType.room;
// 2. Send the message.
ZIM.getInstance()!.sendMessage(zimTextMessage, 'toConversationID', type, config).then((value) {
}).catchError((onError){
});
Update the local extension field of a message
For a message that is already received or sent, you can call the updateMessageLocalExtendedData operation to update the local extension field of the message.
The following sample code shows how to update the local extension field of a message that is already received:
// Update the local extension field of a private-chat message after you receive the message.
ZIMEventHandler.onReceivePeerMessage = (ZIM zim, List<ZIMMessage> messageList, String fromUserID){
for(ZIMMessage message in messageList){
ZIM.getInstance()!.updateMessageLocalExtendedData('Update the local extension field.', message).then((value){
// The request was successful.
}).catchError((onError){
// Handle the error based on the corresponding error code table.
});
}
};