ZIM 升级指南
本文介绍 ZIM Flutter 平台 SDK 版本升级时的一些说明和注意事项。
2.19.0 升级指南
注意
从 2.19.0 版本开始，以下接口有重大变更，因此在从旧版本升级到 2.19.0 版本时，请您阅读以下指南。
downloadMediaFile 及相关回调
downloadMediaFile 新增了 config 参数，可用于指定下载组合消息中的单个媒体内容。此参数为非可选，会导致编译报错，请参考本文档更新代码。
2.19.0版本用法（下载组合消息指定媒体内容）
2.19.0用法（下载多媒体消息）
旧版本用法
// 假设 multipleMessage.messageInfoList[0] 是文本消息，multipleMessage.messageInfoList[1] 是图片消息
ZIMMultipleMessage multipleMessage = message as ZIMMultipleMessage;
ZIMMediaDownloadConfig config = ZIMMediaDownloadConfig();
// 指定下载图片消息
config.messageInfoIndex = 1;
zim.downloadMediaFile(multipleMessage, ZIMMediaFileType.originalFile, config, (ZIMMessage message, int currentFileSize, int totalFileSize) {
// 下载进度
}).then((ZIMMessage message) {
// 下载完成
}).catch((ZIMError errorInfo) {
// 下载失败
});
1
ZIMImageMessage imageMessage = message as ZIMImageMessage;
zim.downloadMediaFile(message, ZIMMediaFileType.originalFile, ZIMMediaDownloadConfig(), (ZIMMessage message, int currentFileSize, int totalFileSize) {
// 下载进度
}).then((ZIMMessage message) {
// 下载完成
}).catch((ZIMError errorInfo) {
// 下载失败
});
1
ZIMImageMessage imageMessage = message as ZIMImageMessage;
zim.downloadMediaFile(message, ZIMMediaFileType.originalFile, (ZIMMessage message, int currentFileSize, int totalFileSize) {
// 下载进度
}).then((ZIMMessage message) {
// 下载完成
}).catch((ZIMError errorInfo) {
// 下载失败
});
1
sendMediaMessage
废弃 sendMediaMessage 接口。自 2.19.0 版本后，发送多媒体消息也使用 sendMessage 接口，减少开发者的维护成本。
ZIMMessageSendNotification 中，onMediaUploadingProgress 回调方法的 message 参数类型从 ZIMMessage 变更为 ZIMMediaMessage，以确保仅媒体消息会被回调通知，开发者需要根据 IDE 的编译错误提示修正调用。(目前仅使用了 replyMessage 接口的开发者会受到需要解决编译报错的影响)
2.19.0版本用法
旧版本用法
ZIMImageMessage imageMessage = ZIMImageMessage(fileLocalPath);
ZIMMessageSendConfig config = ZIMMessageSendConfig();
config.priority = ZIMMessagePriority.medium;
ZIMMessageSendNotification notification = ZIMMessageSendNotification();
notification.onMessageAttached = (ZIMMessage message) {
// 开发者可以监听这个回调执行消息发送前的业务逻辑
};
notification.onMessageUploadingProgress = (ZIMMediaMessage message, int currentFileSize, int totalFileSize) {
// 多媒体上传进度
};
zim.sendMessage(imageMessage, "TO_CONVERSATION_ID", ZIMConversationType.peer, config, notification).then((ZIMMessage message) {
// 消息发送结果
}).catch((ZIMError errorInfo) {
// 消息发送失败
});
1
ZIMImageMessage imageMessage = ZIMImageMessage(fileLocalPath);
ZIMMessageSendConfig config = ZIMMessageSendConfig();
config.priority = ZIMMessagePriority.medium;
ZIMMediaMessageSendNotification notification = ZIMMediaMessageSendNotification();
notification.onMessageAttached = (ZIMMessage message) {
// 开发者可以监听这个回调执行消息发送前的业务逻辑
};
notification.onMessageUploadingProgress = (ZIMMessage message, int currentFileSize, int totalFileSize) {
// 多媒体上传进度
};
zim.sendMediaMessage(imageMessage, "TO_CONVERSATION_ID", ZIMConversationType.peer, config, notification).then((ZIMMessage message) {
// 消息发送结果
}).catch((ZIMError errorInfo) {
// 消息发送失败
});
1
2.18.0 升级指南
注意
从 2.18.0 版本开始，以下接口有重大变更，因此在从旧版本升级到 2.18.0 版本时，请您阅读以下指南。
单聊消息接收回调
原单聊消息接收回调 onReceivePeerMessage 已被废弃，请使用 onPeerMessageReceived 代替。
新回调支持以下功能：
- 用户在线时，可通过此回调接收在线单聊消息。
- 用户重新登录 ZIM SDK 后，可以通过此回调接收离线期间（最长7天）收到的所有单聊消息。
Untitled
//新接口
static void Function(ZIM zim, List<ZIMMessage> messageList,
ZIMMessageReceivedInfo info, String fromUserID)? onPeerMessageReceived;
//老接口
static void Function(
ZIM zim, List<ZIMMessage> messageList, String fromUserID)?
onReceivePeerMessage;
1
房间消息接收回调
原房间消息接收回调 onReceiveRoomMessage 已被废弃，请使用 onRoomMessageReceived 代替。
新回调支持以下功能：
- 用户在线时，可通过此回调接收在线房间消息。
- 用户从离线恢复到在线后，若仍在房间中，即可通过此回调接收离线期间内的所有房间消息。
Untitled
//新接口
static void Function(ZIM zim, List<ZIMMessage> messageList,
ZIMMessageReceivedInfo info, String fromRoomID)? onRoomMessageReceived;
//老接口
static void Function(
ZIM zim, List<ZIMMessage> messageList, String fromRoomID)?
onReceiveRoomMessage;
1
群组消息接收回调
原群组消息接收回调 onReceiveGroupMessage 已被废弃，请使用 onGroupMessageReceived 代替。
新回调支持以下功能：
- 用户在线时，可通过此回调接收在线群组消息。
- 用户重新登录 ZIM SDK 后，可以通过通过此回调接收离线期间（最长7天）收到的所有群聊消息。
Untitled
//新接口
static void Function(ZIM zim, List<ZIMMessage> messageList,
ZIMMessageReceivedInfo info, String fromGroupID)? onGroupMessageReceived;
//老接口
static void Function(
ZIM zim, List<ZIMMessage> messageList, String fromGroupID)?
onReceiveGroupMessage;
1
2.16.0 升级指南
注意
请注意，从 2.16.0 版本开始，以下接口有重大变更，因此在从旧版本升级到 2.16.0 版本时，请您阅读以下指南。
1. callCancel 效果变更
说明
以下变更仅对进阶模式呼叫邀请而言。
在新版本的 callCancel 中，如果参数 userIDs 包含一个 userID，则该接口将仅取消邀请该被叫用户。如果 userIDs 参数为空，则该接口将对所有被叫用户取消邀请。
而对于旧版本的 callCancel 接口，无论参数 userIDs 是否为空，均视为对所有被叫用户取消邀请。
由于旧版 ZIM SDK 不兼容单独取消逻辑，因此如果您既需要保留使用老版本 ZIM 实现的取消逻辑，又需要使用新版本的单独取消功能，请隔离新老版本 ZIM 之间的呼叫功能。
2.16.0版本用法
旧版本用法
// 单独取消 userIdA 、userIdB
List<String> invitees; // 被邀请人列表
invitees.add("userIdA","userIdB"); // 被邀请人 ID,
String callid = "12352435"; // 呼叫 ID
ZIMCallCancelConfig config = new ZIMCallCancelConfig();
ZIM
.getInstance()
!.callCancel(invitees, callID, callCancelConfig)
.then((value) => {
})
.catchError((onError) {});
// invitees 传空数组取消整个呼叫邀请,当整个呼叫中所有被叫都未接受时可以调用成功
List<String> invitees; // 被邀请人列表
String callid = "12352435"; // 呼叫 ID
ZIMCallCancelConfig config = new ZIMCallCancelConfig();
ZIM
.getInstance()
!.callCancel(invitees, callID, callCancelConfig)
.then((value) => {
})
.catchError((onError) {});
1
// 无论 userIDs 中是否传递 userID,均为取消整个呼叫，当整个呼叫中所有被叫都未接受时可以调用成功
List<String> invitees; // 被邀请人列表
invitees.add("userIdA","userIdB"); // 被邀请人 ID,
String callid = "12352435"; // 呼叫 ID
ZIMCallCancelConfig config = new ZIMCallCancelConfig();
ZIM
.getInstance()
!.callCancel(invitees, callID, callCancelConfig)
.then((value) => {
})
.catchError((onError) {});
// invitees 传空数组取消整个呼叫邀请,当整个呼叫中所有被叫都未接受时可以调用成功
List<String> invitees; // 被邀请人列表
String callid = "12352435"; // 呼叫 ID
ZIMCallCancelConfig config = new ZIMCallCancelConfig();
ZIM
.getInstance()
!.callCancel(invitees, callID, callCancelConfig)
.then((value) => {
})
.catchError((onError) {});
1
2.13.0 升级指南
注意
请注意，从 2.13.0 版本开始，以下接口有重大变更，因此在从旧版本升级到 2.13.0 版本时，请您阅读以下指南。
1. login 方法变更
旧版 login 接口被废弃，新版 login 接口支持通过 ZIMLoginConfig 进行更多配置，如是否使用 Token 鉴权、是否离线登录。
2.13.0版本用法
旧版本用法
try{
// 登录时，需要开发者 按照 "使用 Token 鉴权" 文档生成 token 即可
// userID 最大 32 字节的字符串。仅支持数字，英文字符 和 '!', '#', '$', '%', '&', '(', ')', '+', '-', ':', ';', '<', '=', '.', '>', '?', '@', '[', ']', '^', '_', '{', '}', '|', '~'。
// userName 最大 256 字节的字符串，无特殊字符限制。
ZIMLoginConfig loginConfig = ZIMLoginConfig();
//该用户的用户昵称，不填写代表不修改用户昵称
loginConfig.userName = 'userName';
//若使用 token 作为登录鉴权的方式，请填写该参数，否则无需填写
loginConfig.token = '';
// 本次登录是否为离线登录，详情请参考离线登录相关文档
loginConfig.isOfflineLogin = false;
await ZIM.getInstance()?.login('zego', loginConfig);
// 登录成功，编写登录成功的业务逻辑
} on PlatformException catch(onError){
// 登录失败
//登录失败的错误码，请参考错误码文档进行处理
onError.code;
//登录失败的错误信息
onError.message;
}
1
// 登录时，需要开发者 按照 "使用 Token 鉴权" 文档生成 token 即可
// userID 最大 32 字节的字符串。仅支持数字，英文字符 和 '!', '#', '$', '%', '&', '(', ')', '+', '-', ':', ';', '<', '=', '.', '>', '?', '@', '[', ']', '^', '_', '{', '}', '|', '~'。
// userName 最大 256 字节的字符串，无特殊字符限制。
var userInfo = { userID: 'xxxx', userName: 'xxxx' };
var token = '';
zim.login(userInfo, token)
.then(function () {
// 登录成功
})
.catch(function (err) {
// 登录失败
});
1
2.9.0 升级指南
注意
请注意，从 2.9.0 版本开始，以下接口有重大变更，因此在从旧版本升级到 2.9.0 版本时，请您阅读以下指南。
1. onCallInvitationTimeout 方法变更
onCallInvitationTimeout 新增参数 ZIMCallInvitationTimeoutInfo，开发者需要在调用回调时补充此参数，否则代码无法编译通过。
2.9.0版本用法
旧版本用法
ZIMEventHandler.onCallInvitationTimeout = (ZIM zim, ZIMCallInvitationTimeoutInfo info, String callID){
};
1
ZIMEventHandler.onCallInvitationTimeout = (ZIM zim, String callID){
};
1
2.3.0 升级指南
注意
请注意，从 2.3.0 版本开始，API 接口有重大变更，因此在从旧版本升级到 2.3.0 版本时，请您阅读以下指南。
1. create 方法变更
将 create 方法从成员函数变为静态函数，并将返回值从 Future<ZIM> 更改为 ZIM?。
当您使用 ZIM 时，请先调用此 API 接口。此外，您应该删除关键字 await。
2.3.0版本用法
旧版本用法
ZIMAppConfig appConfig = ZIMAppConfig();
appConfig.appID = 12345678;
appConfig.appSign = 'abcdefg...';
ZIM.create(appConfig);
1
await ZIM.getInstance().create(12345678);
1
2. getInstance 方法变更
将 getInstance 方法的返回值从 ZIM 改为 ZIM?，因此，请您注意处理空安全问题。
每一个 API 接口都需要调整，下面展示其中一个 API 用法调整。
2.3.0版本用法
旧版本用法
await ZIM.getInstance()!.login(userInfo, token);
1
await ZIM.getInstance().login(userInfo, token);
1
3. 添加 ZIM 实例参数
我们添加了 ZIM 实例参数作为回调参数。每一个回调都需要调整，下面只展示其中的一个回调。
2.3.0版本用法
旧版本用法
ZIMEventHandler.onConnectionStateChanged = (zim, state, event, extendedData) {
// to do something...
};
1
ZIMEventHandler.onConnectionStateChanged = (state, event, extendedData) {
// to do something...
};
1
4. 删除不必要的 Future 返回值
我们删除了一些 API 接口中不必要的 Future 返回值，这样就不需要 await 返回值了。
涉及到的接口有：destroy、logout、setLogConfig、setCacheConfig、beginRoomAttributesBatchOperation。
2.3.0版本用法
旧版本用法
ZIM.setLogConfig(config);
......
ZIM.setCacheConfig(config);
......
ZIM.getInstance()!.beginRoomAttributesBatchOperation(roomID, config);
......
ZIM.getInstance()!.logout();
......
ZIM.getInstance()!.destroy();
......
1
await ZIM.getInstance().setLogConfig(config);
......
await ZIM.getInstance().setCacheConfig(config);
......
await ZIM.getInstance().beginRoomAttributesBatchOperation(roomID, config);
......
await ZIM.getInstance().logout();
......
await ZIM.getInstance().destroy();
......
1