ZIM upgrade Guide
This article introduces some instructions and precautions when upgrading the In-app Chat Flutter SDK.
2.18.0 upgrade guide
Starting from version 2.18.0, the following interfaces have undergone significant changes. Therefore, when upgrading from an older version to version 2.16.0, please read the following guidelines.
Callback on receiving one-to-one messages
The deprecated callback onReceivePeerMessage for receiving one-to-one messages has been replaced by onPeerMessageReceived.
The new callback supports the following features:
- When a user is online, they can receive one-to-one messages through this callback.
- When a user logs back into the ZIM SDK, they can receive all one-to-one messages received during their offline period (up to 7 days).
// New callback
static void Function(
ZIM zim, List<ZIMMessage> messageList,
ZIMMessageReceivedInfo info, String fromUserID)?
onPeerMessageReceived;
// Old callback
static void Function(
ZIM zim, List<ZIMMessage> messageList, String fromUserID)?
onReceivePeerMessage;
Callback on receiving room messages
The deprecated callback onReceiveRoomMessage for receiving room messages has been replaced by onRoomMessageReceived.
The new callback supports the following features:
- When a user is online, they can receive online room messages through this callback.
- When a user goes from offline to online and is still in the room, they can receive all room messages that were sent during their offline period through this callback.
// New callback
static void Function(
ZIM zim, List<ZIMMessage> messageList,
ZIMMessageReceivedInfo info, String fromRoomID)?
onRoomMessageReceived;
// Old callback
static void Function(
ZIM zim, List<ZIMMessage> messageList, String fromRoomID)?
onReceiveRoomMessage;
Callback on receiving group messages
The deprecated callback onReceiveGroupMessage for receiving group messages has been replaced by onGroupMessageReceived.
The new callback supports the following features:
- When the user is online, they can receive online group messages through this callback.
- When the user logs back into the ZIM SDK, they can receive all group chat messages received during the offline period (up to 7 days) through this callback.
// New Callback
static void Function(ZIM zim, List<ZIMMessage> messageList,
ZIMMessageReceivedInfo info, String fromGroupID)? onGroupMessageReceived;
// Old Callback
static void Function(
ZIM zim, List<ZIMMessage> messageList, String fromGroupID)?
onReceiveGroupMessage;
2.16.0 Upgrade Guide
Please note that starting from version 2.16.0, there are significant changes to the following interfaces. Therefore, when upgrading from an older version to version 2.16.0, please read the following guide.
1. Changes to the callCancel method
The following changes only apply to advanced mode call invitations.
In the new version of callCancel, if the parameter userIDs contains a userID, the interface will only cancel the invitation for that callee. If the userIDs parameter is empty, the interface will cancel the invitation for all callees.
For the old version of the callCancel method, regardless of whether the userIDs parameter is empty or not, it is considered as canceling the invitation for all callees.
Since the old version of the ZIM SDK is not compatible with separate cancellation logic, if you need to retain the cancellation logic implemented using the old version of ZIM and also need to use the separate cancellation feature of the new version, please isolate the call functionality between the old and new versions of ZIM.
// Cancel userIdA and userIdB separately
List<String> invitees; // List of invitees
invitees.add("userIdA","userIdB"); // IDs of invitees
String callid = "12352435"; // Call ID
ZIMCallCancelConfig config = new ZIMCallCancelConfig();
ZIM
.getInstance()
!.callCancel(invitees, callID, callCancelConfig)
.then((value) => {
})
.catchError((onError) {});
// Cancel the entire call invitation by passing an empty array to invitees. This can be called successfully when none of the callees in the entire call have accepted the invitation
List<String> invitees; // List of invitees
String callid = "12352435"; // Call ID
ZIMCallCancelConfig config = new ZIMCallCancelConfig();
ZIM
.getInstance()
!.callCancel(invitees, callID, callCancelConfig)
.then((value) => {
})
.catchError((onError) {});
// Whether the userID is passed in the userIDs parameter or not, it is considered as canceling the entire call. This can be called successfully when none of the callees in the entire call have accepted the invitation
List<String> invitees; // List of invitees
invitees.add("userIdA","userIdB"); // IDs of invitees
String callid = "12352435"; // Call ID
ZIMCallCancelConfig config = new ZIMCallCancelConfig();
ZIM
.getInstance()
!.callCancel(invitees, callID, callCancelConfig)
.then((value) => {
})
.catchError((onError) {});
// Cancel the entire call invitation by passing an empty array to invitees. This can be called successfully when none of the callees in the entire call have accepted the invitation
List<String> invitees; // List of invitees
String callid = "12352435"; // Call ID
ZIMCallCancelConfig config = new ZIMCallCancelConfig();
ZIM
.getInstance()
!.callCancel(invitees, callID, callCancelConfig)
.then((value) => {
})
.catchError((onError) {});
2.13.0 Upgrade Guide
Please note that starting from version 2.13.0, there are significant changes to the following interfaces. Therefore, when upgrading from an older version to version 2.13.0, please read the following guide.
1. Changes to the login method
The old version of the login method has been deprecated. The new version of login method supports more configurations through ZIMLoginConfig, such as whether to use Token authentication and whether to login offline.
try{
// When logging in, developers need to generate a token according to the "Token Authentication" document
// userID is a string with a maximum of 32 bytes. It only supports numbers, English characters, and '!', '#', '$', '%', '&', '(', ')', '+', '-', ':', ';', '<', '=', '.', '>', '?', '@', '[', ']', '^', '_', '{', '}', '|', '~'.
// userName is a string with a maximum of 256 bytes, with no special character restrictions.
ZIMLoginConfig loginConfig = ZIMLoginConfig();
// The user nickname, leave it blank if you don't want to modify the user nickname
loginConfig.userName = 'userName';
// If using token for login authentication, please fill in this parameter, otherwise no need to fill in
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 the business logic for successful login
} on PlatformException catch(onError){
// Login failed
// Error code for login failure, please refer to the error code documentation for handling
onError.code;
// Error message for login failure
onError.message;
}
// When logging in, developers need to generate a token according to the "Token Authentication" document
// userID is a string with a maximum of 32 bytes. It only supports numbers, English characters, and '!', '#', '$', '%', '&', '(', ')', '+', '-', ':', ';', '<', '=', '.', '>', '?', '@', '[', ']', '^', '_', '{', '}', '|', '~'.
// userName is a string with a maximum of 256 bytes, with no special character restrictions.
var userInfo = { userID: 'xxxx', userName: 'xxxx' };
var token = '';
zim.login(userInfo, token)
.then(function () {
// Login successful
})
.catch(function (err) {
// Login failed
});
2.9.0 upgrade guide
Please note that starting from version 2.9.0, the API method has undergone major changes, so please read the following guidelines when upgrading from older versions to version 2.9.0.
The onCallInvitationTimeout method changed
The onCallInvitationTimeout callback method has added a new parameter ZIMCallInvitationTimeoutInfo, developers are required to provide this parameter, otherwise the code cannot be compiled successfully.
ZIMEventHandler.onCallInvitationTimeout = (ZIM zim, String callID){
};
ZIMEventHandler.onCallInvitationTimeout = (ZIM zim, ZIMCallInvitationTimeoutInfo info, String callID){
};
2.3.0 upgrade guide
Please note that starting from version 2.3.0, the API method has undergone major changes, so please read the following guidelines when upgrading from older versions to version 2.3.0.
1. The create method changed
Changed the create method from a member function to a static function, and changed the return value from Future<ZIM> to ZIM?.
When you use In-app Chat, please call this method first. Also, you should remove the keyword await.
-
How we use it with the older version of SDK:
Untitledawait ZIM.getInstance().create(12345678);1 -
To use it with SDK V2.3.0:
UntitledZIMAppConfig appConfig = ZIMAppConfig(); appConfig.appID = 12345678; appConfig.appSign = 'abcdefg...'; ZIM.create(appConfig);1
2. The getInstance method changed
Changed the return value of the getInstance method from ZIM to ZIM?, so please be careful about null safety.
Every API method needs to be adjusted, and one of the API usage adjustments is shown below.
-
How we use it with the older version of SDK:
Untitledawait ZIM.getInstance().login(userInfo, token);1 -
To use it with SDK V2.3.0:
Untitledawait ZIM.getInstance()!.login(userInfo, token);1
3. Instance parameters added
We added the In-app Chat instance parameter as a callback parameter. Each callback needs to be adjusted, and the following takes a method as an example:
-
How we use it with the older version of SDK:
UntitledZIMEventHandler.onConnectionStateChanged = (state, event, extendedData) { // to do something... };1 -
To use it with SDK V2.3.0:
UntitledZIMEventHandler.onConnectionStateChanged = (zim, state, event, extendedData) { // to do something... };1
4. Unnecessary Future return value removed
We removed unnecessary Future return values in some API methods, so that await return values are not needed.
The methods involved are: destroy, logout, setLogConfig, setCacheConfig, and beginRoomAttributesBatchOperation.
-
How we use it with the older version of SDK:
Untitledawait ZIM.getInstance().setLogConfig(config); ...... await ZIM.getInstance().setCacheConfig(config); ...... await ZIM.getInstance().beginRoomAttributesBatchOperation(roomID, config); ...... await ZIM.getInstance().logout(); ...... await ZIM.getInstance().destroy(); ......1 -
To use it with SDK V2.3.0:
UntitledZIM.setLogConfig(config); ...... ZIM.setCacheConfig(config); ...... ZIM.getInstance()!.beginRoomAttributesBatchOperation(roomID, config); ...... ZIM.getInstance()!.logout(); ...... ZIM.getInstance()!.destroy(); ......1