v4.0 upgrade checklist

v4.0 包含了一些不向前兼容的改动。以下是从 v3.x 升级到 v4.0 时的具体步骤。

1. 更新 SDK 到 v3 的最新版本（v3.5.7）。各平台更新 JavaScript Realtime SDK 的方法请参考《JavaScript SDK 安装指南》。

2. 运行应用，将所有打印了 deprecation warning 的代码按照提示更新为新的用法。

3. 如果有监听 IMClient 的 'unreadmessages' 事件，需改为使用 'unreadmessagescountupdate'。需要注意这两个事件的回调参数并不相同，请参考以下文档:

   • v3.4.0 更新日志关于未读消息数更新事件的说明
   • API docs: IMClient#unreadmessagescountupdate

4. 如果有监听 Conversation 的 'reciept' 事件，需改为使用 'lastdeliveredatupdate'。需要注意 'lastdeliveredatupdate' 事件的回调函数没有参数，请参考 v3.4.0 更新日志关于消息已读回执的说明。

5. 更新 SDK 到 v4。

6. 在初始化 Realtime 的时候增加 appKey 参数。

   示例

    const realtime = new Realtime({
      appId: 'YOUR_APP_ID',
   +  appKey: 'YOUR_APP_KEY',
    });

7. 如果使用了如果使用富文本消息插件（leancloud-realtime-plugin-typed-messages），更新该插件至 v3。

8. 检查所有对 SDK 异步 API 的调用，有无使用 try catch 进行同步异常捕获。在 v3 中，有部分异步 API 会同步的抛出异常。这部分分异常现在需要通过 .catch(error => {}) 的方式捕获。

   示例

   // before
   try {
     conversation.send(message);
   } catch (error) {
     // handle `Connection unavailable` error
   }
   
   // after
   conversation.add(members).catch(error => {
     // handle `Connection unavailable` error
   });

   我们推荐使用 await 方式调用 SDK 的异步 API 从而统一同步异步 API 的异常处理方式。

9. 检查异常处理的逻辑中，有无对 error.message 进行字符串匹配，如果有字符串匹配并且匹配的异常信息在 这个列表 中，请修改为比较 error.code。

   示例

     const { ErrorCode } = require('leancloud-realtime');
   
     conversation.add(invitedMemberId).then({
       console.log('添加成员成功');
     }).catch(error => {
   -   if (error.message === 'CONVERSATION_FULL') {
   +   if (error.code === ErrorCode.CONVERSATION_FULL) {
         promoteToUser('对话已满，无法添加新成员');
       }
       // handle other errors
     });

10. Conversation#add 与 Conversation#remove 方法在 v3 中会返回当前的 Conversation 实例，请不要依赖这个返回值（在 v4 中返回的是一个包含部分成功与失败信息的 PartiallySuccess 对象）。

11. 如果使用了 Message 以及子类的 #toJSON 方法，替换为 #getPayload 方法。