ZIM upgrade Guide
This article introduces some instructions and precautions when upgrading the In-app Chat macOS SDK.
2.18.0 upgrade guide
Warning
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 receivePeerMessage for receiving one-to-one messages has been replaced by peerMessageReceived.
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).
Untitled
// New callback
- (void)zim:(ZIM *)zim
peerMessageReceived:(NSArray<ZIMMessage *> *)messageList
info:(ZIMMessageReceivedInfo *)info
fromUserID:(NSString *)fromUserID;
// Old callback
- (void)zim:(ZIM *)zim
receivePeerMessage:(NSArray<ZIMMessage *> *)messageList
fromUserID:(NSString *)fromUserID;
1
Callback on receiving room messages
The deprecated callback receiveRoomMessage for receiving room messages has been replaced by roomMessageReceived.
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.
Untitled
// New callback
- (void)zim:(ZIM *)zim
roomMessageReceived:(NSArray<ZIMMessage *> *)messageList
info:(ZIMMessageReceivedInfo *)info
fromRoomID:(NSString *)fromRoomID;
// Old callback
- (void)zim:(ZIM *)zim
receiveRoomMessage:(NSArray<ZIMMessage *> *)messageList
fromRoomID:(NSString *)fromRoomID;
1
Callback on receiving group messages
The deprecated callback receiveGroupMessage for receiving group messages has been replaced by groupMessageReceived.
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.
Untitled
// New callback
- (void)zim:(ZIM *)zim
groupMessageReceived:(NSArray<ZIMMessage *> *)messageList
info:(ZIMMessageReceivedInfo *)info
fromGroupID:(NSString *)fromGroupID;
// Old callback
- (void)zim:(ZIM *)zim
receiveGroupMessage:(NSArray<ZIMMessage *> *)messageList
fromGroupID:(NSString *)fromGroupID;
1
2.16.0 upgrade guide
Warning
Starting from version 2.16.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.
callCancel
Note
The following changes only apply to Advanced Mode call invitations.
In the new version of callCancelWithInvitees, 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 callCancelWithInvitees interface, 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 individual cancellation logic, if you need to retain the cancellation logic implemented using the old version of ZIM while also using the new version's individual cancellation feature, please isolate the call functionality between the old and new versions of ZIM.
Usage in version 2.16.0
Usage in old versions
ZIMCallCancelConfig *cancelConfig = [[ZIMCallCancelConfig alloc] init];
// Cancel userIdA and userIdB individually
[[ZIM getInstance] callCancelWithInvitees:@[@"userIdA",@"userIdB"] callID:@"callId" config:cancelConfig callback:^(NSString * _Nonnull callID, NSArray<NSString *> * _Nonnull errorInvitees, ZIMError * _Nonnull errorInfo) {
}];
// Cancel the entire call invitation, can be called successfully when none of the callees in the call have accepted
[[ZIM getInstance] callCancelWithInvitees:@[] callID:@"callId" config:cancelConfig callback:^(NSString * _Nonnull callID, NSArray<NSString *> * _Nonnull errorInvitees, ZIMError * _Nonnull errorInfo) {
}];
1
ZIMCallCancelConfig *cancelConfig = [[ZIMCallCancelConfig alloc] init];
// Regardless of whether the userID is passed in the userIDs array, it cancels the entire call, can be called successfully when none of the callees in the call have accepted
[[ZIM getInstance] callCancelWithInvitees:@[@"userIdA",@"userIdB"] callID:@"callId" config:cancelConfig callback:^(NSString * _Nonnull callID, NSArray<NSString *> * _Nonnull errorInvitees, ZIMError * _Nonnull errorInfo) {
}];
// Cancel the entire call invitation, can be called successfully when none of the callees in the call have accepted
[[ZIM getInstance] callCancelWithInvitees:@[] callID:@"callId" config:cancelConfig callback:^(NSString * _Nonnull callID, NSArray<NSString *> * _Nonnull errorInvitees, ZIMError * _Nonnull errorInfo) {
}];
1
2.5.0 upgrade guide
Warning
In-app Chat SDK has optimized the naming of Swift Language API methods in version 2.5.0, so when upgrading from an older version to version 2.5.0, you will need to read the changes listed below.
getInstance
Untitled
// old interface
open class func getInstance() -> ZIM
// new interface
open class func shared() -> ZIM?
1
create
Untitled
// old interface
open class func create(with config: ZIMAppConfig) -> ZIM
// new interface
open class func create(with config: ZIMAppConfig) -> ZIM?
1
setAdvancedConfigWithKey
Untitled
// old interface
open class func setAdvancedConfigWithKey(_ key: String, value: String)
// new interface
open class func setAdvancedConfig(key: String, value: String)
1
uploadLog
Untitled
// old interface
open func uploadLog(_ callback: @escaping ZIMLogUploadedCallback)
// new interface
open func uploadLog(with callback: @escaping ZIMLogUploadedCallback)
1
queryUsersInfo
Untitled
// old interface
open func queryUsersInfo(_ userIDs: [String], config: ZIMUsersInfoQueryConfig, callback: @escaping ZIMUsersInfoQueriedCallback)
// new interface
open func queryUsersInfo(by userIDs: [String], config: ZIMUsersInfoQueryConfig, callback: @escaping ZIMUsersInfoQueriedCallback)
1
deleteConversation
Untitled
// old interface
open func deleteConversation(_ conversationID: String, conversationType: ZIMConversationType, config: ZIMConversationDeleteConfig, callback: @escaping ZIMConversationDeletedCallback)
// new interface
open func deleteConversation(by conversationID: String, conversationType: ZIMConversationType, config: ZIMConversationDeleteConfig, callback: @escaping ZIMConversationDeletedCallback)
1
clearConversationUnreadMessageCount
Untitled
// old interface
open func clearConversationUnreadMessageCount(_ conversationID: String, conversationType: ZIMConversationType, callback: @escaping ZIMConversationUnreadMessageCountClearedCallback)
// new interface
open func clearConversationUnreadMessageCount(for conversationID: String, conversationType: ZIMConversationType, callback: @escaping ZIMConversationUnreadMessageCountClearedCallback)
1
send (send normal message)
Untitled
// old interface
open func send(_ message: ZIMMessage, toConversationID: String, conversationType: ZIMConversationType, config: ZIMMessageSendConfig, notification: ZIMMessageSendNotification?, callback: @escaping ZIMMessageSentCallback)
// new interface
open func sendMessage(_ message: ZIMMessage, toConversationID: String, conversationType: ZIMConversationType, config: ZIMMessageSendConfig, notification: ZIMMessageSendNotification?, callback: @escaping ZIMMessageSentCallback)
1
send (the interface for sending rich media messages in the old version, which has been deprecated since version 2.4.0)
Untitled
// old interface
@available(*, deprecated, message: "Deprecated since ZIM 2.4.0, please use another [sendMediaMessage] instead")
open func send(_ message: ZIMMediaMessage, toConversationID: String, conversationType: ZIMConversationType, config: ZIMMessageSendConfig, progress: @escaping ZIMMediaUploadingProgress, callback: @escaping ZIMMessageSentCallback)
// new interface
@available(*, deprecated, message: "Deprecated since ZIM 2.4.0, please use another [sendMediaMessage] instead")
open func sendMediaMessage(_ message: ZIMMediaMessage, toConversationID: String, conversationType: ZIMConversationType, config: ZIMMessageSendConfig, progress: @escaping ZIMMediaUploadingProgress, callback: @escaping ZIMMessageSentCallback)
1
send (new version sends rich media message interface, version 2.4.0 or above is available)
Untitled
// old interface
open func send(_ message: ZIMMediaMessage, toConversationID: String, conversationType: ZIMConversationType, config: ZIMMessageSendConfig, notification: ZIMMediaMessageSendNotification?, callback: @escaping ZIMMessageSentCallback)
// new interface
open func sendMediaMessage(_ message: ZIMMediaMessage, toConversationID: String, conversationType: ZIMConversationType, config: ZIMMessageSendConfig, notification: ZIMMediaMessageSendNotification?, callback: @escaping ZIMMessageSentCallback)
1
queryHistoryMessage
Untitled
// old interface
open func queryHistoryMessage(byConversationID conversationID: String, conversationType: ZIMConversationType, config: ZIMMessageQueryConfig, callback: @escaping ZIMMessageQueriedCallback)
// new interface
open func queryHistoryMessage(by conversationID: String, conversationType: ZIMConversationType, config: ZIMMessageQueryConfig, callback: @escaping ZIMMessageQueriedCallback)
1
deleteAllMessage
Untitled
// old interface
open func deleteAllMessage(byConversationID conversationID: String, conversationType: ZIMConversationType, config: ZIMMessageDeleteConfig, callback: @escaping ZIMMessageDeletedCallback)
// new interface
open func deleteAllMessage(by conversationID: String, conversationType: ZIMConversationType, config: ZIMMessageDeleteConfig, callback: @escaping ZIMMessageDeletedCallback)
1
delete
Untitled
// old interface
open func delete(_ messageList: [ZIMMessage], conversationID: String, conversationType: ZIMConversationType, config: ZIMMessageDeleteConfig, callback: @escaping ZIMMessageDeletedCallback)
// new interface
open func deleteMessages(_ messageList: [ZIMMessage], conversationID: String, conversationType: ZIMConversationType, config: ZIMMessageDeleteConfig, callback: @escaping ZIMMessageDeletedCallback)
1
insertMessage
Untitled
// old interface
open func insertMessage(toLocalDB message: ZIMMessage, conversationID: String, conversationType: ZIMConversationType, senderUserID: String, callback: @escaping ZIMMessageInsertedCallback)
// new interface
open func insertMessageToLocalDB(_ message: ZIMMessage, conversationID: String, conversationType: ZIMConversationType, senderUserID: String, callback: @escaping ZIMMessageInsertedCallback)
1
createRoom (create and join a room)
Untitled
// old interface
open func createRoom(_ roomInfo: ZIMRoomInfo, callback: @escaping ZIMRoomCreatedCallback)
// new interface
open func createRoom(with roomInfo: ZIMRoomInfo, callback: @escaping ZIMRoomCreatedCallback)
1
createRoom (create a room with advanced settings)
Untitled
// old interface
open func createRoom(_ roomInfo: ZIMRoomInfo, config: ZIMRoomAdvancedConfig, callback: @escaping ZIMRoomCreatedCallback)
// new interface
open func createRoom(with roomInfo: ZIMRoomInfo, config: ZIMRoomAdvancedConfig, callback: @escaping ZIMRoomCreatedCallback)
1
joinRoom
Untitled
// old interface
open func joinRoom(_ roomID: String, callback: @escaping ZIMRoomJoinedCallback)
// new interface
open func joinRoom(by roomID: String, callback: @escaping ZIMRoomJoinedCallback)
1
enterRoom
Untitled
// old interface
open func enterRoom(_ roomInfo: ZIMRoomInfo, config: ZIMRoomAdvancedConfig?, callback: @escaping ZIMRoomEnteredCallback)
// new interface
open func enterRoom(with roomInfo: ZIMRoomInfo, config: ZIMRoomAdvancedConfig?, callback: @escaping ZIMRoomEnteredCallback)
1
leaveRoom
Untitled
// old interface
open func leaveRoom(_ roomID: String, callback: @escaping ZIMRoomLeftCallback)
// new interface
open func leaveRoom(by roomID: String, callback: @escaping ZIMRoomLeftCallback)
1
queryRoomMemberList
Untitled
// old interface
open func queryRoomMemberList(byRoomID roomID: String, config: ZIMRoomMemberQueryConfig, callback: @escaping ZIMRoomMemberQueriedCallback)
// new interface
open func queryRoomMemberList(by roomID: String, config: ZIMRoomMemberQueryConfig, callback: @escaping ZIMRoomMemberQueriedCallback)
1
queryRoomOnlineMemberCount
Untitled
// old interface
open func queryRoomOnlineMemberCount(byRoomID roomID: String, callback: @escaping ZIMRoomOnlineMemberCountQueriedCallback)
// new interface
open func queryRoomOnlineMemberCount(by roomID: String, callback: @escaping ZIMRoomOnlineMemberCountQueriedCallback)
1
beginRoomAttributesBatchOperation
Untitled
// old interface
open func beginRoomAttributesBatchOperation(withRoomID roomID: String, config: ZIMRoomAttributesBatchOperationConfig?)
// new interface
open func beginRoomAttributesBatchOperation(with roomID: String, config: ZIMRoomAttributesBatchOperationConfig?)
1
endRoomAttributesBatchOperation
Untitled
// old interface
open func endRoomAttributesBatchOperation(withRoomID roomID: String, callback: @escaping ZIMRoomAttributesBatchOperatedCallback)
// new interface
open func endRoomAttributesBatchOperation(with roomID: String, callback: @escaping ZIMRoomAttributesBatchOperatedCallback)
1
queryRoomAllAttributes
Untitled
// old interface
open func queryRoomAllAttributes(byRoomID roomID: String, callback: @escaping ZIMRoomAttributesQueriedCallback)
// new interface
open func queryRoomAllAttributes(by roomID: String, callback: @escaping ZIMRoomAttributesQueriedCallback)
1
queryRoomMembersAttributes
Untitled
// old interface
open func queryRoomMembersAttributes(byUserIDs userIDs: [String], roomID: String, callback: @escaping ZIMRoomMembersAttributesQueriedCallback)
// new interface
open func queryRoomMembersAttributes(by userIDs: [String], roomID: String, callback: @escaping ZIMRoomMembersAttributesQueriedCallback)
1
queryRoomMemberAttributesList
Untitled
// old interface
open func queryRoomMemberAttributesList(byRoomID roomID: String, config: ZIMRoomMemberAttributesQueryConfig, callback: @escaping ZIMRoomMemberAttributesListQueriedCallback)
// new interface
open func queryRoomMemberAttributesList(by roomID: String, config: ZIMRoomMemberAttributesQueryConfig, callback: @escaping ZIMRoomMemberAttributesListQueriedCallback)
1
createGroup (create and join a group)
Untitled
// old interface
open func createGroup(_ groupInfo: ZIMGroupInfo, userIDs: [String], callback: @escaping ZIMGroupCreatedCallback)
// new interface
open func createGroup(with groupInfo: ZIMGroupInfo, userIDs: [String], callback: @escaping ZIMGroupCreatedCallback)
1
createGroup (create and join a group with group attributes)
Untitled
// old interface
open func createGroup(_ groupInfo: ZIMGroupInfo, userIDs: [String], config: ZIMGroupAdvancedConfig, callback: @escaping ZIMGroupCreatedCallback)
// new interface
open func createGroup(with groupInfo: ZIMGroupInfo, userIDs: [String], config: ZIMGroupAdvancedConfig, callback: @escaping ZIMGroupCreatedCallback)
1
dismissGroup
Untitled
// old interface
open func dismissGroup(_ groupID: String, callback: @escaping ZIMGroupDismissedCallback)
// new interface
open func dismissGroup(by groupID: String, callback: @escaping ZIMGroupDismissedCallback)
1
joinGroup
Untitled
// old interface
open func joinGroup(_ groupID: String, callback: @escaping ZIMGroupJoinedCallback)
// new interface
open func joinGroup(by groupID: String, callback: @escaping ZIMGroupJoinedCallback)
1
leaveGroup
Untitled
// old interface
open func leaveGroup(_ groupID: String, callback: @escaping ZIMGroupLeftCallback)
// new interface
open func leaveGroup(by groupID: String, callback: @escaping ZIMGroupLeftCallback)
1
inviteUsers
Untitled
// old interface
open func inviteUsers(intoGroup userIDs: [String], groupID: String, callback: @escaping ZIMGroupUsersInvitedCallback)
// new interface
open func inviteUsersIntoGroup(with userIDs: [String], groupID: String, callback: @escaping ZIMGroupUsersInvitedCallback)
1
kickGroupMembers
Untitled
// old interface
open func kickGroupMembers(_ userIDs: [String], groupID: String, callback: @escaping ZIMGroupMemberKickedCallback)
// new interface
open func kickGroupMembers(by userIDs: [String], groupID: String, callback: @escaping ZIMGroupMemberKickedCallback)
1
transferGroupOwner
Untitled
// old interface
open func transferGroupOwner(toUserID: String, groupID: String, callback: @escaping ZIMGroupOwnerTransferredCallback)
// new interface
open func transferGroupOwner(to toUserID: String, groupID: String, callback: @escaping ZIMGroupOwnerTransferredCallback)
1
queryGroupInfo
Untitled
// old interface
open func queryGroupInfo(byGroupID groupID: String, callback: @escaping ZIMGroupInfoQueriedCallback)
// new interface
open func queryGroupInfo(by groupID: String, callback: @escaping ZIMGroupInfoQueriedCallback)
1
deleteGroupAttributes
Untitled
// old interface
open func deleteGroupAttributes(byKeys keys: [String], groupID: String, callback: @escaping ZIMGroupAttributesOperatedCallback)
// new interface
open func deleteGroupAttributes(by keys: [String], groupID: String, callback: @escaping ZIMGroupAttributesOperatedCallback)
1
queryGroupAttributes
Untitled
// old interface
open func queryGroupAttributes(byKeys keys: [String], groupID: String, callback: @escaping ZIMGroupAttributesQueriedCallback)
// new interface
open func queryGroupAttributes(by keys: [String], groupID: String, callback: @escaping ZIMGroupAttributesQueriedCallback)
1
queryGroupAllAttributes
Untitled
// old interface
open func queryGroupAllAttributes(byGroupID groupID: String, callback: @escaping ZIMGroupAttributesQueriedCallback)
// new interface
open func queryGroupAllAttributes(by groupID: String, callback: @escaping ZIMGroupAttributesQueriedCallback)
1
queryGroupMemberInfo
Untitled
// old interface
open func queryGroupMemberInfo(byUserID userID: String, groupID: String, callback: @escaping ZIMGroupMemberInfoQueriedCallback)
// new interface
open func queryGroupMemberInfo(by userID: String, groupID: String, callback: @escaping ZIMGroupMemberInfoQueriedCallback)
1
queryGroupMemberList
Untitled
// old interface
open func queryGroupMemberList(byGroupID groupID: String, config: ZIMGroupMemberQueryConfig, callback: @escaping ZIMGroupMemberListQueriedCallback)
// new interface
open func queryGroupMemberList(by groupID: String, config: ZIMGroupMemberQueryConfig, callback: @escaping ZIMGroupMemberListQueriedCallback)
1
queryGroupMemberCount
Untitled
// old interface
open func queryGroupMemberCount(byGroupID groupID: String, callback: @escaping ZIMGroupMemberCountQueriedCallback)
// new interface
open func queryGroupMemberCount(by groupID: String, callback: @escaping ZIMGroupMemberCountQueriedCallback)
1
callInvite
Untitled
// old interface
open func callInvite(withInvitees invitees: [String], config: ZIMCallInviteConfig, callback: @escaping ZIMCallInvitationSentCallback)
// new interface
open func callInvite(with invitees: [String], config: ZIMCallInviteConfig, callback: @escaping ZIMCallInvitationSentCallback)
1
callCancel
Untitled
// old interface
open func callCancel(withInvitees invitees: [String], callID: String, config: ZIMCallCancelConfig, callback: @escaping ZIMCallCancelSentCallback)
// new interface
open func callCancel(with invitees: [String], callID: String, config: ZIMCallCancelConfig, callback: @escaping ZIMCallCancelSentCallback)
1
callAccept
Untitled
// old interface
open func callAccept(withCallID callID: String, config: ZIMCallAcceptConfig, callback: @escaping ZIMCallAcceptanceSentCallback)
// new interface
open func callAccept(with callID: String, config: ZIMCallAcceptConfig, callback: @escaping ZIMCallAcceptanceSentCallback)
1
callReject
Untitled
// old interface
open func callReject(withCallID callID: String, config: ZIMCallRejectConfig, callback: @escaping ZIMCallRejectionSentCallback)
// new interface
open func callReject(with callID: String, config: ZIMCallRejectConfig, callback: @escaping ZIMCallRejectionSentCallback)
1