ZIM 升级指南
本文介绍 ZIM Flutter 平台 SDK 版本升级时的一些说明和注意事项。
2.18.0 升级指南
从 2.18.0 版本开始，以下接口有重大变更，因此在从旧版本升级到 2.18.0 版本时，请您阅读以下指南。
单聊消息接收回调
原单聊消息接收回调 onReceivePeerMessage 已被废弃，请使用 onPeerMessageReceived 代替。
新回调支持以下功能：
- 用户在线时，可通过此回调接收在线单聊消息。
- 用户重新登录 ZIM SDK 后，可以通过此回调接收离线期间（最长7天）收到的所有单聊消息。
//新接口
static void Function(ZIM zim, List<ZIMMessage> messageList,
ZIMMessageReceivedInfo info, String fromUserID)? onPeerMessageReceived;
//老接口
static void Function(
ZIM zim, List<ZIMMessage> messageList, String fromUserID)?
onReceivePeerMessage;
房间消息接收回调
原房间消息接收回调 onReceiveRoomMessage 已被废弃，请使用 onRoomMessageReceived 代替。
新回调支持以下功能：
- 用户在线时，可通过此回调接收在线房间消息。
- 用户从离线恢复到在线后，若仍在房间中，即可通过此回调接收离线期间内的所有房间消息。
//新接口
static void Function(ZIM zim, List<ZIMMessage> messageList,
ZIMMessageReceivedInfo info, String fromRoomID)? onRoomMessageReceived;
//老接口
static void Function(
ZIM zim, List<ZIMMessage> messageList, String fromRoomID)?
onReceiveRoomMessage;
群组消息接收回调
原群组消息接收回调 onReceiveGroupMessage 已被废弃，请使用 onGroupMessageReceived 代替。
新回调支持以下功能：
- 用户在线时，可通过此回调接收在线群组消息。
- 用户重新登录 ZIM SDK 后，可以通过通过此回调接收离线期间（最长7天）收到的所有群聊消息。
//新接口
static void Function(ZIM zim, List<ZIMMessage> messageList,
ZIMMessageReceivedInfo info, String fromGroupID)? onGroupMessageReceived;
//老接口
static void Function(
ZIM zim, List<ZIMMessage> messageList, String fromGroupID)?
onReceiveGroupMessage;
2.16.0 升级指南
请注意，从 2.16.0 版本开始，以下接口有重大变更，因此在从旧版本升级到 2.16.0 版本时，请您阅读以下指南。
1. callCancel 效果变更
以下变更仅对进阶模式呼叫邀请而言。
在新版本的 callCancel 中，如果参数 userIDs 包含一个 userID，则该接口将仅取消邀请该被叫用户。如果 userIDs 参数为空，则该接口将对所有被叫用户取消邀请。
而对于旧版本的 callCancel 接口，无论参数 userIDs 是否为空，均视为对所有被叫用户取消邀请。
由于旧版 ZIM SDK 不兼容单独取消逻辑，因此如果您既需要保留使用老版本 ZIM 实现的取消逻辑，又需要使用新版本的单独取消功能，请隔离新老版本 ZIM 之间的呼叫功能。
// 单独取消 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) {});
// 无论 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) {});
2.13.0 升级指南
请注意，从 2.13.0 版本开始，以下接口有重大变更，因此在从旧版本升级到 2.13.0 版本时，请您阅读以下指南。
1. login 方法变更
旧版 login 接口被废弃，新版 login 接口支持通过 ZIMLoginConfig 进行更多配置，如是否使用 Token 鉴权、是否离线登录。
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;
}
// 登录时，需要开发者 按照 "使用 Token 鉴权" 文档生成 token 即可
// userID 最大 32 字节的字符串。仅支持数字，英文字符 和 '!', '#', '$', '%', '&', '(', ')', '+', '-', ':', ';', '<', '=', '.', '>', '?', '@', '[', ']', '^', '_', '{', '}', '|', '~'。
// userName 最大 256 字节的字符串，无特殊字符限制。
var userInfo = { userID: 'xxxx', userName: 'xxxx' };
var token = '';
zim.login(userInfo, token)
.then(function () {
// 登录成功
})
.catch(function (err) {
// 登录失败
});
2.9.0 升级指南
请注意，从 2.9.0 版本开始，以下接口有重大变更，因此在从旧版本升级到 2.9.0 版本时，请您阅读以下指南。
1. onCallInvitationTimeout 方法变更
onCallInvitationTimeout 新增参数 ZIMCallInvitationTimeoutInfo，开发者需要在调用回调时补充此参数，否则代码无法编译通过。
ZIMEventHandler.onCallInvitationTimeout = (ZIM zim, ZIMCallInvitationTimeoutInfo info, String callID){
};
ZIMEventHandler.onCallInvitationTimeout = (ZIM zim, String callID){
};
2.3.0 升级指南
请注意，从 2.3.0 版本开始，API 接口有重大变更，因此在从旧版本升级到 2.3.0 版本时，请您阅读以下指南。
1. create 方法变更
将 create 方法从成员函数变为静态函数，并将返回值从 Future<ZIM> 更改为 ZIM?。
当您使用 ZIM 时，请先调用此 API 接口。此外，您应该删除关键字 await。
ZIMAppConfig appConfig = ZIMAppConfig();
appConfig.appID = 12345678;
appConfig.appSign = 'abcdefg...';
ZIM.create(appConfig);
await ZIM.getInstance().create(12345678);
2. getInstance 方法变更
将 getInstance 方法的返回值从 ZIM 改为 ZIM?，因此，请您注意处理空安全问题。
每一个 API 接口都需要调整，下面展示其中一个 API 用法调整。
await ZIM.getInstance()!.login(userInfo, token);
await ZIM.getInstance().login(userInfo, token);
3. 添加 ZIM 实例参数
我们添加了 ZIM 实例参数作为回调参数。每一个回调都需要调整，下面只展示其中的一个回调。
ZIMEventHandler.onConnectionStateChanged = (zim, state, event, extendedData) {
// to do something...
};
ZIMEventHandler.onConnectionStateChanged = (state, event, extendedData) {
// to do something...
};
4. 删除不必要的 Future 返回值
我们删除了一些 API 接口中不必要的 Future 返回值，这样就不需要 await 返回值了。
涉及到的接口有：destroy、logout、setLogConfig、setCacheConfig、beginRoomAttributesBatchOperation。
ZIM.setLogConfig(config);
......
ZIM.setCacheConfig(config);
......
ZIM.getInstance()!.beginRoomAttributesBatchOperation(roomID, config);
......
ZIM.getInstance()!.logout();
......
ZIM.getInstance()!.destroy();
......
await ZIM.getInstance().setLogConfig(config);
......
await ZIM.getInstance().setCacheConfig(config);
......
await ZIM.getInstance().beginRoomAttributesBatchOperation(roomID, config);
......
await ZIM.getInstance().logout();
......
await ZIM.getInstance().destroy();
......