Merge pull request #501 from haoxiuwen/doc-v2

Add 4.2.1 Release Notes and Integration Docs

docs/document/android/error.md

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

docs/document/android/group_manage.md

@@ -209,6 +209,24 @@ List<EMGroupInfo> groupsList = result.getData();
 String cursor = result.getCursor();
 ```
 
+### 查询当前用户已加入的群组数量
+
+你可以调用 `EMGroupManager#asyncGetJoinedGroupsCountFromServer` 方法从服务器获取当前用户已加入的群组数量。单个用户可加入群组数量的上限取决于订阅的即时通讯的套餐包，详见[产品价格](product/pricing.html#套餐包功能详情)。
+
+```java
+EMClient.getInstance().groupManager().asyncGetJoinedGroupsCountFromServer(new EMValueCallBack<Integer>() {
+    @Override
+    public void onSuccess(Integer value) {
+
+    }
+
+    @Override
+    public void onError(int error, String errorMsg) {
+
+    }
+});
+```
+
 ### 屏蔽和解除屏蔽群消息
 
 群成员可以屏蔽群消息和解除屏蔽群消息。
@@ -280,7 +298,7 @@ EMGroupChangeListener groupListener = new EMGroupChangeListener() {
 
     // 群主或群管理员拒绝用户的进群申请。申请人、群主和管理员（除操作者）收到该回调。
     @Override
-    public void onRequestToJoinDeclined(String groupId, String groupName, String decliner, String reason) {
+    public void onRequestToJoinDeclined(String groupId, String groupName, String decliner, String reason, String applicant) {
     }
 
     // 用户同意进群邀请。邀请人收到该回调。

docs/document/android/group_overview.md

@@ -23,7 +23,7 @@
 | 创建方式 | 所有 app 用户都可以创建群组。   | 仅 [超级管理员](/document/server-side/chatroom.html#管理超级管理员) 有权限创建聊天室。  |
 | 类型 | 分为公开群和私有群，创建群组时可设置入群是否需获得群主和群管理员的同意，支持不同使用场景。 | 没有公开和私有之分，所有用户均可自由加入或退出。      |
 | 最大成员数   | 成员数支持取决于所选择的版本，最高版本支持 8,000 人。        | 成员数支持取决于所选择的版本，最高版本支持 10,000 人。如需提升该上限，请联系商务。 |
-| 离线推送消息 | 离线时，会收到推送消息。             | 离线时，不会收到推送消息；成员离线超过 2 分钟会自动退出聊天室。          |
+| 离线推送消息 | 离线时，会收到推送消息。             | 离线时，不会收到推送消息；成员（除聊天室白名单中的成员）离线超过 2 分钟会自动退出聊天室。          |
 | 离线消息存储 | 支持离线消息存储，每个会话存储 200 条消息。<br/>用户上线时，会收到离线消息。 | 不支持离线消息存储。如果需要用户新加入聊天室时服务器推送最近的历史消息，可以联系商务开通聊天室历史消息推送，每个会话默认支持 10 条消息，最多可调整至 200 条。 |
 | 漫游消息存储 | 支持漫游消息存储。你可以从服务器获取指定会话的消息。 | 不支持漫游消息存储。 |
 | 消息可靠性   | 群组中发送的所有消息，用户都会收到。        | 当消息量大时，聊天室中超过阈值的消息会被丢弃。消息开始丢弃的阈值为每秒 100 条消息，可以根据需求进行调整。 |

docs/document/android/message_manage.md

@@ -39,7 +39,7 @@
 
 ### 获取本地所有会话
 
-你可以调用 `getAllConversationsBySort` 方法一次性获取本地所有会话。
+你可以调用 `getAllConversationsBySort` 方法一次性获取本地所有会话。若在初始化时，将 `EMOptions#setLoadEmptyConversations` 设置为 `true` 允许返回空会话，则会话列表中会包含空会话，否则不包含。
 
 SDK 从内存中获取会话，若未从本地数据库中加载过，会先从数据库加载到内存中。获取会话后，SDK 按照会话活跃时间（最新一条消息的时间戳）的倒序返回会话，置顶会话在前，非置顶会话在后，会话列表为 `List<EMConversation>` 结构。
 

docs/document/android/message_retrieve.md

@@ -32,9 +32,11 @@
 
 对于单聊或群聊，用户发消息时会自动将对方添加到用户的会话列表。
 
-你可以调用 `asyncFetchConversationsFromServer` 方法从服务端分页获取会话列表，每个会话包含最新一条历史消息。
+你可以调用 `asyncFetchConversationsFromServer` 方法从服务端分页获取会话列表。若在初始化时，将 `EMOptions#setLoadEmptyConversations` 设置为 `true` 允许返回空会话，则会话列表中会包含空会话，否则不包含。
 
-SDK 按照会话活跃时间（会话的最新一条消息的时间戳）的倒序返回会话列表。服务器默认存储 100 条会话，可存储 7 天。若提升这两个上限，需联系环信商务。
+SDK 按照会话活跃时间（会话的最新一条消息的时间戳）的倒序返回会话列表，每个会话对象中包含会话 ID、会话类型、是否为置顶状态、置顶时间（对于未置顶的会话，值为 `0`）以及最新一条消息。从服务端拉取会话列表后会更新本地会话列表。
+
+服务器默认存储 100 条会话，可存储 7 天。若提升这两个上限，需联系环信商务。
 
 :::notice
 1. 若使用该功能，需将 SDK 升级至 4.0.3。 

docs/document/android/message_send_receive.md

@@ -99,12 +99,12 @@ EMClient.getInstance().chatManager().sendMessage(message);
 
 ### 接收消息
 
-你可以用注册监听 `EMMessageListener` 接收消息。
-
-该 `EMMessageListener` 可以多次添加，请记得在不需要的时候移除 `listener`，如在 `activity` 的 `onDestroy()` 时。
+你可以用注册监听 `EMMessageListener` 接收消息。该 `EMMessageListener` 可以多次添加，请记得在不需要的时候移除 `listener`，如在 `activity` 的 `onDestroy()` 时。
 
 在新消息到来时，你会收到 `onMessageReceived` 的回调，消息接收时可能是一条，也可能是多条。你可以在该回调里遍历消息队列，解析并显示收到的消息。
 
+对于聊天室消息，你可以通过消息的 `EMMessage#isBroadcast` 属性判断通过该消息是否为[通过 REST API 发送的聊天室全局广播消息](server-side/message_chatroom.html#发送聊天室全局广播消息)。
+
 ```java
 EMMessageListener msgListener = new EMMessageListener() {
 
@@ -120,6 +120,8 @@ EMClient.getInstance().chatManager().addMessageListener(msgListener);
 EMClient.getInstance().chatManager().removeMessageListener(msgListener);
 ```
 
+
+
 ### 撤回消息
 
 发送方可以撤回一条发送成功的消息。调用 API 撤回消息后，服务端的该条消息（历史消息，离线消息或漫游消息）以及消息发送方和接收方的内存和数据库中的消息均会被移除，消息的接收方会收到 `onMessageRecalled` 事件。

docs/document/android/releasenote.md

@@ -2,20 +2,48 @@
 
 <Toc />
 
-## 版本 V4.1.3 Dev 2023-9-25（开发版）
+## 版本 V4.2.1 Dev 2023-11-17（开发版）
+
+### 新增特性
+
+- [IM SDK] 新增[好友备注功能](user_relationship.html#设置好友备注)。
+- [IM SDK] 新增 `EMMessage#isBroadcast` 属性用于判断通过该消息是否为聊天室全局广播消息。可通过[调用 REST API 发送聊天室全局广播消息](server-side/message_chatroom.html#发送聊天室全局广播消息)。
+- [IM SDK] 新增 `EMGroupManager#asyncGetJoinedGroupsCountFromServer` 方法用于[从服务器获取当前用户已加入的群组数量](group_manage.html#查询当前用户已加入的群组数量)。 
+- [IM SDK] 新增[错误码 706](error.html) `CHATROOM_OWNER_NOT_ALLOW_LEAVE`，表示聊天室所有者不允许离开聊天室。若初始化时，`EMOptions#allowChatroomOwnerLeave` 参数设置为 `false`，聊天室所有者调用 `leaveChatRoom` 方法离开聊天室时会提示该错误。
+- [IM SDK] 新增 `EMOptions#setLoadEmptyConversations` 方法用于在初始化时配置是否允许返回空会话。
+- [IM SDK] [申请入群被拒绝的回调](group_manage.html#监听群组事件) `EMGroupChangeListener#onRequestToJoinDeclined` 中新增 `decliner` 和 `applicant` 参数表示申请者和拒绝者的用户 ID。  
+- [IM Demo] 好友详情页面可添加和修改好友备注。
+
+### 优化
+
+- [IM SDK] 统一 Agora Token 和 EaseMob Token 登录方式： `EMClient#loginWithAgoraToken` 接口废弃，统一使用 `EMClient#loginWithToken` 接口。此外，新增 EaseMob Token 即将过期及已过期的回调，即 EaseMob Token 已过期或有效期过半时也返回 `EMConnectionListener#onTokenExpired` 和 `EMConnectionListener#onTokenWillExpire` 回调。
+- [IM SDK] 优化发消息时重试的逻辑。
+- [IM SDK] 移除网络请求时对 `NetworkOnMainThreadException` 异常的捕获。
+- [IM SDK] 数据库升级逻辑优化。
+
+### 修复
+
+- [IM SDK] 修复网络恢复时重连 2 次的问题。
+- [IM SDK] 修复未登录时调用 `leaveChatroom` 方法返回的错误提示不准确。
+- [IM CallKit] 一对一视频通话时对方未接听，发起方进入悬浮窗状态，悬浮窗未刷新。 
+- [IM CallKit] 挂断音视频后，最小化 app，最近任务中窗口中仍然显示音视频页面。 
+- [IM CallKit] 悬浮窗需要点击两次才响应。
+- [IM CallKit] 多人音视频前，发起方静音，对方接听后看不到发起方的 UI 界面。
+
+## 版本 V4.1.3 Dev 2023-9-25
 
 ### 修复
 
 - [IM SDK] 特殊场景下，SDK 退出后再登录会丢失聊天室监听事件问题。
 
-## 版本 V4.1.2 Dev 2023-9-5（开发版）
+## 版本 V4.1.2 Dev 2023-9-5
 
 ### 优化
 
 - [IM SDK] 适配 Android 14 Beta。
   - 适配以 Android 14 为目标平台时动态注册广播接收者必须设置 `RECEIVER_EXPORTED` 或者 `RECEIVER_NOT_EXPORTED` 的规定。
 
-## 版本 V4.1.1 Dev 2023-8-3（开发版）
+## 版本 V4.1.1 Dev 2023-8-3
 
 ### 修复
 
@@ -59,7 +87,7 @@
 - [IM SDK] 修复调用接口 `EMChatManager#deleteMessagesBeforeTimestamp` 和 `EMConversation#removeMessages(long,long)` 偶现崩溃的问题；
 - [IM UIKit] 修复语音消息自动下载失败后点击语音图标无法再次下载的问题。
 
-## 版本 V4.0.3 Dev 2023-6-19（开发版）
+## 版本 V4.0.3 Dev 2023-6-19
 
 ### 新增特性
 
@@ -82,7 +110,7 @@
 - [IM UIKit] 修复部分空指针问题。
 - [IM UIKit] 修复部分场景下不展示自定义头像的问题。
 
-## 版本 V4.0.2 Dev 2023-4-26（开发版）
+## 版本 V4.0.2 Dev 2023-4-26
 
 ### 新增特性
 
@@ -108,7 +136,7 @@
 - [IM SDK] 修复部分场景下用户调用下载消息附件接口时，附件未下载到私有目录的问题。
 - [IM SDK] 修复某些场景下消息已读状态不更新的问题。
 
-## 版本 V4.0.1 Dev 2023-3-16（开发版）
+## 版本 V4.0.1 Dev 2023-3-16
 
 ### 新增特性
 
@@ -189,7 +217,7 @@
 - [IM SDK] 适配 Android 12，修复依赖环信即时通讯云 SDK 的 APK 在 Android 12 版本的部分手机上第一次安装后打开时出现异常弹框的问题。
 - [IM SDK] 修复某些场景下调用 `updateMessage` 方法导致的内存与数据库消息不一致问题。
 
-## 版本 V3.9.7 Dev 2022-9-30（开发版）
+## 版本 V3.9.7 Dev 2022-9-30
 
 ### 新增特性
 
@@ -206,7 +234,7 @@
 - [IM SDK] 修复开启全链路加入（FPA）功能时导致崩溃的问题。
 - [IM SDK] 修复聊天室自定义属性部分设置失败时，返回的错误码为字符串类型（修改为 Int 类型）的问题。
 
-## 版本 V3.9.6.1 Dev 2022-9-21（开发版）
+## 版本 V3.9.6.1 Dev 2022-9-21
 
 ### 新增特性
 
@@ -218,7 +246,7 @@
 - [IM SDK] 优化聊天室自定义属性移除的回调方法 `onAttributesRemoved`，返回成功移除的聊天室自定义属性的 key 数组。
 - [IMKit] 语音播放切换至媒体音量。
 
-## 版本 V3.9.6 Dev 2022-9-16（开发版）
+## 版本 V3.9.6 Dev 2022-9-16
 
 ### 新增特性
 

docs/document/android/room_manage.md

@@ -107,7 +107,7 @@ EMOptions options = new EMOptions();
 options.setDeleteMessagesAsExitChatRoom(false);
 ```
 
-与群主无法退出群组不同，聊天室所有者可以离开聊天室，例如所有者从服务器下线则 2 分钟后自动离开聊天室。如果所有者重新进入聊天室仍是该聊天室的所有者。
+与群主无法退出群组不同，聊天室所有者可以离开聊天室，例如，所有者从服务器下线则 2 分钟后自动离开聊天室。如果所有者重新进入聊天室仍是该聊天室的所有者。若 `EMOptions#allowChatroomOwnerLeave` 参数在初始化时设置为 `false`，聊天室所有者调用 `leaveChatRoom` 方法离开聊天室时会提示错误 706 `CHATROOM_OWNER_NOT_ALLOW_LEAVE`。
 
 ### 解散聊天室
 

docs/document/android/room_overview.md

@@ -4,7 +4,7 @@
 
 ## 功能描述
 
-聊天室是支持多人加入的类似 Twitch 的组织，聊天室中的成员没有固定关系，一旦离线后，不会收到聊天室中的任何消息，超过 2 分钟会自动退出聊天室。聊天室可以应用于直播、消息广播等。若需调整该时间，需联系环信商务经理。
+聊天室是支持多人加入的类似 Twitch 的组织，聊天室中的成员没有固定关系，一旦离线后，不会收到聊天室中的任何消息，（除了聊天室白名单中的成员）超过 2 分钟会自动退出聊天室。聊天室可以应用于直播、消息广播等。若需调整该时间，需联系环信商务经理。
 
 聊天室的使用限制视不同套餐版本而定，请参见 [使用限制](/product/limitation.html)。
 

docs/document/android/user_relationship.md

@@ -13,16 +13,13 @@ SDK 提供用户关系管理功能，包括好友列表管理和黑名单管理
 
 ## 技术原理
 
-环信即时通讯 IM Android SDK 提供 `EMContactManager` 类实现好友的添加移除，黑名单的添加移除等功能。主要方法如下：
+环信即时通讯 IM Android SDK 提供 `EMContactManager` 类实现好友的添加移除，黑名单的添加移除等功能。
 
-- `addContact` 申请添加好友。
-- `acceptInvitation` 同意好友申请。
-- `declineInvitation` 拒绝好友申请。
-- `deleteContact` 删除好友。
-- `getAllContactsFromServer` 从服务器获取好友列表。
-- `addUserToBlackList` 添加用户到黑名单。
-- `removeUserFromBlackList` 将用户从黑名单移除。
-- `getBlackListFromServer` 从服务器获取黑名单列表。
+- 添加、删除好友。
+- 设置和获取好友备注。
+- 从服务器获取好友列表。
+- 将用户添加到或移除黑名单。
+- 从服务器获取黑名单列表。
 
 ## 前提条件
 
@@ -106,21 +103,120 @@ EMClient.getInstance().contactManager().deleteContact(username);
 
 调用 `deleteContact` 删除好友后，对方会收到 `onContactDeleted` 回调。
 
+#### 设置好友备注
+
+你可以调用 `asyncSetContactRemark` 方法设置单个好友的备注。
+
+好友备注的长度不能超过 100 个字符。
+
+```java
+EMClient.getInstance().contactManager().asyncSetContactRemark(userId, remark, new EMCallBack() {
+    @Override
+    public void onSuccess() {
+
+    }
+
+    @Override
+    public void onError(int code, String error) {
+
+    }
+});
+```
+
 #### 获取好友列表
 
-你可以从服务器获取好友列表，也可以从本地数据库获取已保存的好友列表。
+- 从服务端获取好友列表：
 
-:::notice
-需要从服务器获取好友列表之后，才能从本地数据库获取到好友列表。
-:::
+调用以下两种方法返回好友列表，其中每个好友对象包含好友的用户 ID 和好友备注。
 
-示例代码如下：
+```java
+//一次性从服务端获取整个好友列表
+EMClient.getInstance().contactManager().asyncFetchAllContactsFromServer(new EMValueCallBack<List<EMContact>>() {
+    @Override
+    public void onSuccess(List<EMContact> value) {
+
+    }
+
+    @Override
+    public void onError(int error, String errorMsg) {
+
+    }
+});
+
+//从服务端分页获取好友列表
+// limit 的取值范围为 [1,50]
+List<EMContact> contacts=new ArrayList<>();
+String cursor= "";
+int limit=20;
+doAsyncFetchAllContactsFromServer(contacts,cursor,limit);
+
+private void doAsyncFetchAllContactsFromServer(List<EMContact> contacts, String cursor, int limit) {
+    EMClient.getInstance().contactManager().asyncFetchAllContactsFromServer(limit, cursor, new EMValueCallBack<EMCursorResult<EMContact>>() {
+        @Override
+        public void onSuccess(EMCursorResult<EMContact> value) {
+            List<EMContact> data = value.getData();
+            String resultCursor = value.getCursor();
+            if(!CollectionUtils.isEmpty(data)) {
+                contacts.addAll(data);
+            }
+            if(!TextUtils.isEmpty(resultCursor)) {
+                doAsyncFetchAllContactsFromServer(contacts, resultCursor, limit);
+            }
+        }
+
+        @Override
+        public void onError(int error, String errorMsg) {
+
+        }
+    });
+```
+
+你也可以调用 `getAllContactsFromServer` 方法从服务器获取所有好友的列表，该列表只包含好友的用户 ID。
 
 ```java
 // 从服务器获取好友列表。
 // 同步方法，会阻塞当前线程。异步方法为 asyncGetAllContactsFromServer(EMValueCallBack)。
 List<String> usernames = EMClient.getInstance().contactManager().getAllContactsFromServer();
-// 从本地数据库获取好友列表。
+```
+
+- 从本地获取好友列表
+
+调用以下两种方法返回好友列表，其中每个好友对象包含好友的用户 ID 和好友备注。
+
+:::notice
+需要从服务器获取好友列表之后，才能从本地获取到好友列表。
+:::
+
+```java
+//从本地获取单个好友
+try {
+    EMContact emContact = EMClient.getInstance().contactManager().fetchContactFromLocal(userId);
+    String remark = emContact.getRemark();
+    String username = emContact.getUsername();
+    EMLog.e(TAG, "fetchContactFromLocal success, username:" + username + ",remark:" + remark);
+} catch (HyphenateException e) {
+    EMLog.e(TAG, "fetchContactFromLocal error:" + e.getMessage());
+};
+
+//一次性从本地获取整个好友列表
+EMClient.getInstance().contactManager().asyncFetchAllContactsFromLocal(new EMValueCallBack<List<EMContact>>() {
+    @Override
+    public void onSuccess(List<EMContact> value) {
+
+    }
+
+    @Override
+    public void onError(int error, String errorMsg) {
+
+    }
+});
+```
+
+你也可以调用 `getContactsFromLocal` 方法从本地获取所有好友的列表，该列表只包含好友的用户 ID。
+
+示例代码如下：
+
+```java
 List<String> usernames = EMClient.getInstance().contactManager().getContactsFromLocal();
 ```