Merge pull request #1130 from haoxiuwen/doc-v2

Add Android/iOS/Web/Applet 4.12.0 Release Notes

docs/document/android/releasenote.md

@@ -2,6 +2,27 @@
 
 <Toc />
 
+## 版本 V4.12.0 Dev 2025-1-10（开发版）
+
+### 新增特性
+
+- [IM SDK] 用户加入聊天室可获取如下信息：
+  1. 聊天室当前人数：通过  `EMChatRoom#getMemberCount` 方法获取。有用户加入或离开聊天室时，当前聊天室人数会更新。
+  2. 聊天室全体禁言状态：通过 `EMChatRoom#isAllMemberMuted` 方法获取。该状态值在收到全体禁言状态变更时会更新。
+  3. 聊天室创建时间戳：新增 `EMChatRoom#getCreateTimestamp` 方法获取。
+  4. 当前用户是否在聊天室白名单中：新增 `EMChatRoom#isInWhitelist` 方法获取。
+  5. 当前用户被禁言截止时间戳：`EMChatRoom#getMuteExpireTimestamp`。
+
+### 优化
+
+- [IM SDK] 移除 Android SDK 4.0.0 版本之前废弃的 API。
+- [IM SDK] 优化部分数据库操作。
+- [IM SDK] JNI 层添加对一些异常的消除机制及判空保护。
+
+### 修复
+
+- [IM SDK] 修复退出登录时因为一些在 SDK 回调里嵌套调用 SDK 相关 API 导致的异常。
+
 ## 版本 V4.11.0 Dev 2024-12-3（开发版）
 
 ### 新增特性

docs/document/applet/alipay.md

@@ -86,6 +86,7 @@ import SDK from "../sdk/Easemob-chat-miniProgram"; // 3.0 SDK
 
 ```javascript
 //实例化 SDK 对象
+// url 和 apiUrl 属性仅在 4.11.0 及之前版本需手动传入。4.12.0 及之后版本，SDK 会自动获取。
 const WebIM = (wx.WebIM = SDK);
 WebIM.conn = new WebIM.connection({
   appKey: "your appKey",

docs/document/applet/baidu.md

@@ -90,6 +90,7 @@ import SDK from "../sdk/Easemob-chat-miniProgram"; // 3.0 SDK
 
 ```javascript
 //实例化 SDK 对象
+// url 和 apiUrl 属性仅在 4.11.0 及之前版本需手动传入。4.12.0 及之后版本，SDK 会自动获取。
 const WebIM = (wx.WebIM = SDK);
 WebIM.conn = new WebIM.connection({
   appKey: "your appKey",

docs/document/applet/bytedance.md

@@ -87,6 +87,7 @@ import SDK from "../sdk/Easemob-chat-miniProgram"; // 3.0 SDK
 
 ```javascript
 //实例化 SDK 对象
+// url 和 apiUrl 属性仅在 4.11.0 及之前版本需手动传入。4.12.0 及之后版本，SDK 会自动获取。
 const WebIM = (wx.WebIM = SDK);
 WebIM.conn = new WebIM.connection({
   appKey: "your appKey",

docs/document/applet/qq.md

@@ -94,6 +94,7 @@ import SDK from "../sdk/Easemob-chat-miniProgram"; // 3.0 SDK
 
 ```javascript
 // 实例化 SDK 对象
+// url 和 apiUrl 属性仅在 4.11.0 及之前版本需手动传入。4.12.0 及之后版本，SDK 会自动获取。
 const WebIM = (wx.WebIM = SDK);
 WebIM.conn = new WebIM.connection({
   appKey: "your appKey",

docs/document/applet/releasenote.md

@@ -2,6 +2,28 @@
 
 <Toc />
 
+## 版本 V4.12.0 Dev 2025-1-10（开发版）
+
+### 新增特性
+
+- `onModifiedMessage` 事件回调参数中增加消息 `ext` 字段。添加该字段后，修改发送成功的消息后，消息接收方会收到发送方发送修改后的消息时添加的扩展信息。
+-  加入聊天室 `joinChatRoom` 成功的回调新增 `info` 字段，包含如下信息，即用户加入聊天室后会收到如下信息：
+   - 聊天室创建时间：`createTimestamp`。
+   - 是否开启全员禁言：`isAllMembersMuted`。
+   - 是否在白名单中：`isInAllowlist`。
+   - 当前聊天室成员数：`memberCount`。
+   - 成员禁言到期时间：`muteExpireTimestamp`。
+
+### 优化
+
+- [IM SDK] 小程序 SDK 支持 HTTPDNS, 默认开启, 用户无需手动传入 `url` 和 `apiUrl`，SDK 会自动获取。
+
+### 修复
+
+- [IM SDK] 格式化小程序 SDK API 请求失败错误码，与 Web 端统一。**请注意使用密码登录 IM 返回的错误码和旧版本不兼容**。
+- [IM SDK] 修复 Uniapp SDK 4.36 版本运行到鸿蒙平台，出现的重连问题。
+- [IM SDK] 修复偶现的无法拉取消息的问题。
+
 ## 版本 V4.11.0 Dev 2024-12-3（开发版）
 
 ### 新增特性

docs/document/applet/uniapp.md

@@ -141,6 +141,7 @@ import SDK from 'easemob-websdk/uniApp/Easemob-chat';
 
 ```javascript
 // 实例化 SDK 对象
+// url 和 apiUrl 属性仅在 4.11.0 及之前版本需手动传入。4.12.0 及之后版本，SDK 会自动获取。
 const WebIM = wx.WebIM = SDK;
 const conn = new WebIM.connection({
     appKey: 'your appKey', //注意这里的 "K" 需大写

docs/document/applet/wechat.md

@@ -111,6 +111,7 @@ import SDK from "../sdk/Easemob-chat-miniProgram"; // 3.0sdk
 
 ```javascript
 //实例化SDK对象
+// url 和 apiUrl 属性仅在 4.11.0 及之前版本需手动传入。4.12.0 及之后版本，SDK 会自动获取。
 const WebIM = (wx.WebIM = SDK);
 WebIM.conn = new WebIM.connection({
   appKey: "your appKey",

docs/document/harmonyos/conversation_delete.md

@@ -22,7 +22,7 @@
 
 ### 单向删除服务端会话及其历史消息
 
-你可以调用 `deleteConversationFromServer` 方法删除服务器端会话，并选择是否删除服务端和本地的历史消息。会话和消息删除后，当前用户无法从服务器获取该会话和消息。调用该接口不会删除本地会话。该接口不影响其他用户的会话和消息。
+你可以调用 `deleteConversationFromServer` 方法单向删除服务器端会话和本地会话，并选择是否删除服务端和本地的历史消息。会话和消息删除后，当前用户无法从服务器获取该会话和消息。该接口不影响其他用户的会话和消息。
 
 调用该方法之前，需调用 `getConversation` 方法获取会话 ID。
 

docs/document/harmonyos/error.md

@@ -89,7 +89,7 @@ HarmonyOS 中错误码的类为 `ChatError`。
 | 703    |   CHATROOM_PERMISSION_DENIED    | 无权限的聊天室操作：例如，聊天室普通成员没有权限设置聊天室管理员。 |
 | 704    |      CHATROOM_MEMBERS_FULL      | 聊天室已满：聊天室成员数量已达到创建聊天室时设置的最大人数。 |
 | 705    |       CHATROOM_NOT_EXIST        | 聊天室不存在：尝试对不存在的聊天室进行操作时提示该错误。   |
-| 706    |       CHATROOM_OWNER_NOT_ALLOW_LEAVE        | 聊天室所有者不允许离开聊天室。若初始化时，`EMOptions#allowChatroomOwnerLeave` 参数设置为 `false`，聊天室所有者调用 `leaveChatRoom` 方法离开聊天室时会提示该错误。   |
+| 706    |       CHATROOM_OWNER_NOT_ALLOW_LEAVE        | 聊天室所有者不允许离开聊天室。若初始化时，`ChatOptions#allowChatroomOwnerLeave` 参数设置为 `false`，聊天室所有者调用 `leaveChatRoom` 方法离开聊天室时会提示该错误。   |
 | 900    |    USERINFO_USERCOUNT_EXCEED    | 获取用户属性的用户个数超过 100。               |
 | 901    |   USERINFO_DATALENGTH_EXCEED    | 设置的用户属性太长。单个用户的所有属性数据不能超过 2 KB，单个 app 所有用户属性数据不能超过 10 GB。 |
 | 1000   |       CONTACT_ADD_FAILED        | 添加联系人失败。  |

docs/document/harmonyos/initialization.md

@@ -13,7 +13,9 @@
 初始化示例代码：
 
 ```typescript
-let options = new ChatOptions("Your appkey");
+let options = new ChatOptions({
+  appKey: "你的 AppKey"
+});
 ......// 其他 ChatOptions 配置。
 // 初始化时传入上下文以及 options
 ChatClient.getInstance().init(context, options);

docs/document/harmonyos/message_retrieve.md

@@ -40,7 +40,8 @@
 
 :::tip
 1. **默认可获取单聊和群组聊天的历史消息。若要获取聊天室的历史消息，需联系环信商务。**
-2. 历史消息在服务器上的存储时间与产品的套餐包相关，详见[产品套餐包详情](/product/pricing.html#套餐包功能详情)。
+2. 对于单聊消息，自 1.5.0 版本开始，从服务器拉取历史消息时会读取服务端的消息已读和送达状态。该功能默认关闭，如果需要，请联系环信商务开通。
+3. 历史消息在服务器上的存储时间与产品的套餐包相关，详见[产品套餐包详情](/product/pricing.html#套餐包功能详情)。
 :::
 
 ```typescript

docs/document/harmonyos/multi_device.md

@@ -41,6 +41,8 @@
 HarmonyOS SDK 初始化时会生成登录 ID 用于在多设备登录和消息推送时识别设备，并将该 ID 发送到服务器。服务器会自动将新消息发送到用户登录的设备，可以自动监听到其他设备上进行的操作。即时通讯 IM HarmonyOS SDK 提供以下多设备场景功能：
 
 - 获取当前用户的其他已登录设备的登录 ID 列表；
+- 设置登录设备的名称；
+- 设置登录设备的平台；
 - 获取其他设备的好友或者群组操作；
 
 ## 前提条件
@@ -69,6 +71,65 @@ ChatClient.getInstance().contactManager()?.getSelfIdsOnOtherPlatform().then(ids
 });
 ```
 
+### 设置登录设备的名称
+
+即时通讯 IM 自 1.5.0 版本开始支持自定义设置设备名称，这样在多设备场景下，若有设备被踢下线，被踢设备就能知道是被哪个设备挤下线的。
+
+初始化 SDK 时，你可以调用 `ChatOptions#setCustomDeviceName` 方法设置登录设备的名称。设置后，若因达到了登录设备数量限制而导致在已登录的设备上强制退出时，被踢设备收到的 `ConnectionListener#onLogout` 回调会包含导致该设备被踢下线的自定义设备名称。
+
+:::tip
+登录成功后才会将该设置发送到服务器。
+:::
+
+```typescript
+let options = new ChatOptions({
+  appKey: "您的AppKey"
+});
+options.setCustomDeviceName("您的自定义设备名称");
+ChatClient.getInstance().init(this.context, options);
+
+ChatClient.getInstance().addConnectionListener({
+  onConnected:() => {
+
+  },
+  onDisconnected: (errorCode: number) => {
+
+  },
+  onLogout: (errorCode: number, info: LoginExtInfo) => {
+    // 当前登录账号在其它设备登录时，当前的登录设备被踢下线时会触发该回调。
+    // errorCode 为 {@link ChatError#USER_LOGIN_ANOTHER_DEVICE}。
+    // info.deviceInfo 是将当前设备踢出/挤下线的自定义设备名称，若设备没有自定义设备名称时默认回调设备型号。
+    // 其他错误码场景下，info.deviceInfo为空。
+  }
+});
+```
+
+### 设置登录设备的平台
+
+即时通讯 IM 自 1.5.0 版本开始支持自定义设置登录设备的平台，例如将手机和平板电脑设置为两个单独的平台，方便用户精细化控制同一平台的登录设备数量及平台间互踢等行为。
+
+你可以按照以下步骤设置登录设备所属的平台：
+
+1. 在环信控制台的**功能配置** > **功能配置总览**页面，点击**基础功能**页签，然后点击**多端多设备在线**对应的**设置**。在弹出的对话框中点击 **新增自定义平台**，在**添加自定义平台**对话框中设置**设备平台**和**设备数量**。
+
+**设备平台**的取值范围为 [1,100]，**设备数量**的取值范围为 [0,4]。
+
+![img](/images/common/multidevice_device_platform.png)
+
+2. 初始化 SDK 时，调用 `ChatOptions#setCustomOSPlatform` 方法自定义设置登录设备的平台。确保该方法中的 `platform` 参数的值与环信控制台的**添加自定义平台**对话框中设置的**设备平台**的值相同。
+
+:::tip
+登录成功后才会将该设置发送到服务器。
+:::
+
+```typescript
+let options = new ChatOptions({
+  appKey: "您的AppKey"
+});
+options.setCustomOSPlatform(1); // 取值范围为 [1,100]
+ChatClient.getInstance().init(this.context, options);
+```
+
 ### 设置登录设备的扩展信息
 
 即时通讯 IM 自 1.4.0 版本开始支持设备的自定义扩展信息，这样在多设备场景下，若有设备被踢下线，被踢设备能获得该设备的自定义扩展信息。
@@ -80,7 +141,9 @@ ChatClient.getInstance().contactManager()?.getSelfIdsOnOtherPlatform().then(ids
 :::
 
 ```typescript
-let options = new ChatOptions("您的AppKey");
+let options = new ChatOptions({
+  appKey: "你的 AppKey"
+});
 options.setLoginCustomExt("您要设置的自定义扩展信息");
 ChatClient.getInstance().init(this.context, options);
 

docs/document/harmonyos/overview.md

@@ -33,7 +33,9 @@ ohos.permission.GET_NETWORK_INFO
 初始化示例代码：
 
 ```typescript
-let options = new ChatOptions("Your appkey");
+let options = new ChatOptions({
+  appKey: "你的 AppKey"
+});
 ......// 其他 ChatOptions 配置。
 // 初始化时传入上下文以及 options
 ChatClient.getInstance().init(context, options);

docs/document/harmonyos/privatecloud.md

@@ -7,7 +7,9 @@
 SDK 默认指向公有云地址，在部署私有云后，需要将地址重新指向到新的地址，以下是地址修改方法：
 
 ```typescript
-let options = new ChatOptions();//实例化 EMOptions 对象
+let options = new ChatOptions({
+  appKey: "您的AppKey"
+});//实例化 ChatOptions 对象
 options.setRestServer("10.10.10.10:00");//设置私有云 REST 地址（ip/域名：port）
 options.setIMServer("10.10.10.10");//设置私有云 IM 地址
 options.setImPort(100);//设置私有云 IM 端口号
@@ -28,7 +30,9 @@ options.setRestServer("https://10.10.10.10:00");//设置私有云 REST 地址（
 2. 从服务器端动态获取地址
 
 ```typescript
-let options = new ChatOptions();
+let options = new ChatOptions({
+  appKey: "您的AppKey"
+});
 options.setDnsURL("url");//从服务器端动态获取地址
 ChatClient.getInstance().init(options);//初始化 SDK
 ```

docs/document/harmonyos/push/push_harmony.md

@@ -66,7 +66,9 @@
 
 ```typescript
 // ChatOptions 需要传入 appkey 参数。
-let options = new ChatOptions("Your appKey");
+let options = new ChatOptions({
+  appKey: "你的 AppKey"
+});
 // 传入 AppGallery Connect 获取到的 ClientID。
 options.setAppIDForPush('Your ClientID');
 // 初始化即时通讯 IM SDK。

docs/document/harmonyos/quickstart.md

@@ -112,7 +112,9 @@
 ### 1. SDK 初始化
 
 ```typescript
-let options = new ChatOptions("Your appkey");
+let options = new ChatOptions({
+  appKey: "你的 AppKey"
+});
 ......// 其他 ChatOptions 配置。
 // 初始化时传入上下文以及options
 ChatClient.getInstance().init(context, options);

docs/document/harmonyos/releasenote.md

@@ -2,6 +2,45 @@
 
 <Toc />
 
+## 版本 V1.5.0 Dev 2025-1-10（开发版）
+
+### 新增特性
+
+- 用户加入聊天室可获取如下信息：
+  1. 聊天室当前人数：新增  `Chatroom#memberCount` 方法获取。有用户加入或离开聊天室时，当前聊天室人数会更新。
+  2. 聊天室全体禁言状态：通过 `Chatroom#isAllMemberMuted` 方法获取。该状态值在收到全体禁言状态变更时会更新。
+  3. 聊天室创建时间戳：新增 `Chatroom#createTimestamp` 方法获取。
+  4. 当前用户是否在聊天室白名单中：新增 `Chatroom#isInWhitelist` 方法获取。
+  5. 当前用户被禁言截止时间戳：新增 `Chatroom#muteExpireTimestamp` 方法获取。
+
+- 新增[自定义设备的平台和名称功能](multi_device.html#设置登录设备的名称)：
+  - `ChatOptions#setCustomOSPlatform` 和 `ChatOptions#getCustomDeviceName`，用于设置和获取当前设备自定义平台代号；
+  - `ChatOptions#setCustomDeviceName` 和 `ChatOptions#getCustomDeviceName`，用于设置和获取当前设备自定义设备名称。
+- 新增 `ChatManager#getDBMsgsCount` 方法，用于获取数据库中的消息总数。
+- 新增[两个错误码](error.html)：
+  - `ChatError#GROUP_USER_IN_BLOCKLIST`（613）：该用户在群组黑名单中。群组黑名单中的用户进行某些操作时，例如，加入群组，会提示该错误。
+  - `ChatError#CHATROOM_USER_IN_BLOCKLIST`（707）：该用户在聊天室黑名单中。聊天室黑名单中的用户进行某些操作时，例如，加入聊天室，会提示该错误。
+- 聊天室成员禁言回调：
+  - 新增聊天室禁言回调 [ChatroomListener#onMuteMapAdded](room_manage.html#监听聊天室事件)，参数 Map 的 key 表示被禁言的用户 ID ，value 表示禁言到期时间戳；
+  - 废弃原来的回调 `ChatroomListener#onMutelistAdded`。
+- 新增[拉取服务器漫游消息](message_retrieve.html#从服务器获取指定会话的消息)时会读取服务端的消息已读和送达状态。该功能只适用于单聊消息，默认关闭，如果需要，请联系环信商务开通。
+
+### 优化
+
+- 废弃 `ChatOptions` 传入字符串的构造函数，新增传入 [AppParam](initialization.html#初始化) 的构造方法。
+- [发送前回调](/document/server-side/callback_presending.html)时修改的[消息扩展字段](message_send_receive.html#使用消息扩展字段)，会同步到发送方。
+- 调用[删除服务端会话 API](conversation_delete.html#单向删除服务端会话及本地会话)，成功后会删除本地会话。之前版本调用该接口可设置删除会话的本地消息，不能删除本地会话。
+- 群组和聊天室操作的默认错误码提示由 `GROUP_MEMBERS_FULL`（604）和 `CHATROOM_MEMBERS_FULL`（704）调整为 `GROUP_PERMISSION_DENIED`（603）和 `CHATROOM_PERMISSION_DENIED`（703）。例如，群组普通成员设置群组管理员时，由于缺乏权限，会提示 603 错误。
+- 优化部分数据库操作。
+
+### 修复
+
+- 修复未拉取好友时收到好友事件，导致好友列表不能更新的问题。
+- 修复置顶的单聊消息被撤回后，该消息未能及时地从置顶消息缓存（`Conversation#getPinnedMessages`）中移除的问题。
+- 修复调用 [PushManager#getSilentModeForConversations](push_notification_mode_dnd.html#获取多个会话的推送通知设置) 方法获取会话的免打扰状态失败的问题。
+- 修复极端情况下因网络异常导致的 Crash。
+- 修复多次设置 `ChatMessage#setMessageStatusCallback` 时导致崩溃的问题。
+
 ## 版本 V1.4.2 Dev 2024-11-04（开发版）
 
 ### 优化

docs/document/harmonyos/room_manage.md

@@ -107,7 +107,7 @@ interface ChatroomListener{
      * 有成员被禁言。
      * 被添加的成员收到该事件。禁言期间成员不能发送发消息。
      */
-    onMutelistAdded?: (roomId: string, mutes: Array<string>, expireTime: number) => void;
+    onMuteMapAdded?: (roomId: string, mutes: Map<string, number>) => void;
     /**
      * 有成员从禁言列表中移除。
      * 被解除禁言的成员会收到该事件。

docs/document/harmonyos/room_members.md

@@ -61,7 +61,9 @@ ChatClient.getInstance().chatroomManager()?.leaveChatroom(chatRoomId).then(()=>
 示例代码如下：
 
 ```typescript
-let options = new ChatOptions();
+let options = new ChatOptions({
+  appKey: "你的 AppKey"
+});
 options.setDeleteMessagesOnLeaveChatroom(false);
 ```
 
@@ -98,7 +100,7 @@ ChatClient.getInstance().chatroomManager()?.removeChatroomMembers(chatroomId, me
 
 仅聊天室所有者和管理员可调用 `ChatroomManager#blockChatroomMembers` 方法将指定成员添加至黑名单。
 
-被加入黑名单后，该成员收到 `ChatroomListener#onRemovedFromChatRoom` 回调，移出原因为 `EMAChatroomManagerListener#BE_KICKED`。其他成员收到 `ChatroomListener#onMemberExited` 回调。
+被加入黑名单后，该成员收到 `ChatroomListener#onRemovedFromChatRoom` 回调，移出原因为 `LEAVE_REASON#BE_KICK`。其他成员收到 `ChatroomListener#onMemberExited` 回调。
 
 被加入黑名单后，该成员无法再收发聊天室消息并被移出聊天室，黑名单中的成员如想再次加入聊天室，聊天室所有者或管理员必须先将其移出黑名单列表。
 
@@ -190,7 +192,7 @@ ChatClient.getInstance().chatroomManager()?.removeFromChatroomWhitelist(chatroom
 
 #### 添加成员至聊天室禁言列表
 
-仅聊天室所有者和管理员可以调用 `ChatroomManager#muteChatroomMembers` 方法将指定成员添加至聊天室禁言列表，操作者外其他成员收到 `ChatroomListener#onMutelistAdded` 回调。
+仅聊天室所有者和管理员可以调用 `ChatroomManager#muteChatroomMembers` 方法将指定成员添加至聊天室禁言列表，操作者外其他成员收到 `ChatroomListener#onMuteMapAdded` 回调。
 
 :::tip
 聊天室所有者可禁言聊天室所有成员，聊天室管理员可禁言聊天室普通成员。