Merge pull request #1282 from haoxiuwen/4_15_0

Add iOS and Web 4.15.0 Release Notes

Author: haoxiuwen

docs/.vuepress/public/images/demo/android_login.png

@@ -25,6 +25,7 @@ EMConnectionListener connectionListener = new EMConnectionListener() {
     }
 
     @Override
+    // 自 4.15.0 版本，SDK 会在 Token 有效期达到 80% 时回调即将过期通知。
     public void onTokenWillExpire() {
 
     }
@@ -64,4 +65,5 @@ EMClient.getInstance().removeConnectionListener(connectionListener);
 - 用户的账号被从服务器端删除，提示错误码 207。
 - 用户在另一设备登录，将当前设备上登录的用户踢出，提示错误码 206。 
 - 用户登录设备数量超过限制，提示错误码 214。
-- 应用程序的日活跃用户数量（DAU）或月活跃用户数量（MAU）达到上限，提示错误码 8。
+- 应用程序的日活跃用户数量（DAU）或月活跃用户数量（MAU）达到上限，提示错误码 8。
+- 开启多设备服务后，用户在其他设备上通过调用 API 或者管理后台将当前设备登录的 ID 强制退出登录（错误码 217）。

docs/.vuepress/public/images/demo/ios_login.png

@@ -1,32 +1,64 @@
-# Demo（EaseIM App）介绍
+# 环信即时通讯 IM Android Demo 
 
-<Toc />
+环信即时通讯 IM Android Demo 提供用户登录、单聊、群组、聊天室、子区、消息(文字、表情、语音、视频、图片、文件等)发送及管理、会话管理、好友管理、用户属性、用户在线状态（Presence）以及实时音视频通话等功能。
 
-环信即时通讯 IM Android 端提供示例应用可供体验。
+## 体验 Demo 
 
 1. [下载 Demo](https://www.easemob.com/download/demo)。
-
 2. 输入你的手机号，获取验证码，然后输入。
-
 3. 选择同意《环信服务条款》与《环信隐私协议》，然后点击 **登录** 登录 Demo。
 
-![img](/images/demo/android_login.png)
+![img](/images/demo/android_login.png =350x750)
+
+下面为部分 UI 界面的展示：
+
+<ImageGallery :columns="2">
+  <ImageItem src="/images/uikit/chatuikit/android/main_chat.png" title="单聊页面" />
+  <ImageItem src="/images/uikit/chatuikit/android/main_chat_group.png" title="群聊页面" />
+  <ImageItem src="/images/uikit/chatuikit/android/main_conversation_list.png" title="会话列表" />
+  <ImageItem src="/images/uikit/chatuikit/android/main_contact_list.png" title="通讯录" />
+</ImageGallery>
+
+## 快速跑通 Demo
+
+### 开发环境要求
 
-## 代码下载
+- Android Studio Flamingo | 2022.2.1 及以上
+- Gradle 8.0 及以上
+- targetVersion 26 及以上
+- Android SDK API 21 及以上
+- JDK 17 及以上
 
-您可以通过以下两种方式获取到源代码：
-- 下载代码压缩包：[IM SDK 及 Demo 下载](https://www.easemob.com/download/im)
-- 下载源代码：[GitHub 源码地址](https://github.com/easemob/easemob-demo-android)
-  - 4.5.0 及之前版本的 Demo 为 Java 语言。你可以查看 [Demo 源码地址](https://github.com/easemob/chat-android)。环信已不再维护该地址的 Demo 源码。
-  - 4.6.0 及之后版本的 Demo 为 Kotlin 语言。你可以查看 [Demo 源码地址](https://github.com/easemob/easemob-demo-android)。
+### 跑通步骤
 
-## 导入 EaseIM
+1. [创建应用](/product/enable_and_configure_IM.html)。 
+2. [获取应用的 App Key](/product/enable_and_configure_IM.html#获取环信即时通讯-im-的信息)。
+3. [创建用户](/product/enable_and_configure_IM.html#创建-im-用户)。
+4. [下载即时通讯 IM Demo 项目源码](https://github.com/easemob/easemob-demo-android)。
+5. 下载完毕，打开 Android Studio，点击 **File > Open**，打开已下载到本地的 Demo (`easemob-demo-android`) 工程根目录即可。
+6. 将你的应用的 App Key 填入 Demo 工程根目录下的 `local.properties` 文件，格式为 `APPKEY = 你申请的appkey`。
+7. 编译运行项目。
+8. 使用注册的用户 ID 和密码登录。
 
-从 [IM SDK 及 Demo 下载](https://www.easemob.com/download/im) 下载 Android SDK 压缩包，然后解压。解压后在 `examples` 文件夹下，即为 EaseIM 的工程目录。
+### App Server
 
-### 导入到 Android Studio
+为方便开发者快速体验即时通讯 IM 功能，跑通本工程 Demo 源码默认使用开发者注册的用户 ID 和密码直接登录，不需要依赖部署服务端 App Server。但是在此模式下，手机验证码、用户头像和 EaseCallKit 实时音视频等相关功能不可用，你可以通过部署 App Server 完整体验这些功能。
 
-打开 Android Studio，点击 `File > Open`，打开 `examples/EaseIm3.0` 根目录即可。
+App Server 为 Demo 提供以下功能：
+
+- 通过手机号获取验证码。
+- 通过手机号和验证码返回环信用户 ID 和环信用户 Token。
+- 上传头像并返回地址。
+- 根据用户的信息生成 [EaseCallKit](https://doc.easemob.com/document/android/easecallkit.html) 登录所需的 Token。
+- 获取音视频通话时环信用户 ID 和 Agora UID 的映射关系。
+
+你通过以下步骤部署 App Server：
+
+1. 部署 App Server。详见 [服务端源码](https://github.com/easemob/easemob-im-app-server/tree/dev-demo)。
+2. 在 Demo 工程根目录下 `local.properties` 文件中，填写 App Server 的域名或 IP 地址，格式为 `APP_SERVER_DOMAIN = 服务器域名或ip地址`。
+3. 在 Demo 工程根目录下 `local.properties` 文件中，填入 `LOGIN_WITH_APPSERVER = true`，即通知 Demo 工程需要启用 App Server，体验完整功能。
+
+**服务端中的 App Key 要跟客户端的 App Key 保持一致。**
 
 ## 使用的第三方库
 
@@ -72,11 +104,3 @@
 | ChatActivity及ChatFragment  | ChatFragment 继承自 EaseIMKit 中的 UIKitChatFragment，展示了扩展条目长按事件，预置条目长按菜单及对重写部分长按事件功能，展示了如何重置及添加更多扩展功能，并展示了实现了头像点击事件及正在输入等事件的相应。  | 
 | ChatContactListFragment                | 继承自 EaseIMKit 中的 ChatUIKitContactsListFragment，展示了添加头布局，添加条目长按功能及实现条目点击事件等  |
 | ChatGroupDetailActivity  | 实现了如下功能：添加群成员，修改群公告及群介绍，上传共享文件，进行群组管理，设置消息免打扰及解散或者退出群组等。   | 
-
-## 部分 UI 展示
-
-<ImageGallery :columns="3">
-  <ImageItem src="/images/uikit/chatuikit/android/main_chat.png" title="聊天页面" />
-  <ImageItem src="/images/uikit/chatuikit/android/main_conversation_list.png" title="会话列表" />
-  <ImageItem src="/images/uikit/chatuikit/android/main_contact_list.png" title="通讯录" />
-</ImageGallery>

docs/.vuepress/public/images/demo/web_react_login.png

@@ -23,7 +23,7 @@ Android 中错误码的类为 [EMError](https://sdkdocs.easemob.com/apidoc/andro
 | 104    |          INVALID_TOKEN          | 用户 token 不正确：登录时提供的 token 为空或不正确。 | 检查调用的 API 中传入的 token 参数是否正确。 |
 | 105    |       USER_NAME_TOO_LONG        | 用户 ID 过长：用户 ID 长度不能超过 64 字节。  | 检查调用的 API 中传入的用户 ID 长度是否超过限制。 |
 | 108    |          TOKEN_EXPIRED          | 用户 token 已过期：超出 token 有效期时间。 | 收到 token 已过期的回调后，需要开发者重新生成 token，并调用 `loginWithToken` 方法重新登录。 |
-| 109    |        TOKEN_WILL_EXPIRE        | 用户 token 即将过期：超出 token 有效期一半时间时开始回调此错误码。 | 收到 token 即将过期的回调后，需重新生成 token，并调用 `EMClient#renewToken` 方法更新 token。 |
+| 109    |        TOKEN_WILL_EXPIRE        | 用户 token 即将过期：达到 token 有效期 80% （4.15.0 版本之前为 50%）时开始回调此错误码。 | 收到 token 即将过期的回调后，需重新生成 token，并调用 `EMClient#renewToken` 方法更新 token。 |
 | 110    |          INVALID_PARAM          | 参数无效。     | 检查调用的 API 中传入的参数是否有效。 |
 | 200    |       USER_ALREADY_LOGIN        | 用户已登录：该用户 ID 已经登录。            | 检查 SDK 是否开启了自动登录或已调用了登录方法。如果已开启，在 IM 登录成功后，下次打开 app 时，无需再调用登录方法。 |
 | 201    |         USER_NOT_LOGIN          | 用户未登录：例如，如果未登录成功时发送消息或者使用群组操作的 API，SDK 会提示该错误。 | 检查调用 API 时，是否已完成 IM 登录。 |

docs/document/android/connection.md

@@ -60,14 +60,14 @@
 受邀用户直接进群，会收到如下回调：
 
 - 新成员会收到 `EMGroupChangeListener#onAutoAcceptInvitationFromGroup` 回调；
-- 邀请人收到 `EMGroupChangeListener#onInvitationAccepted` 回调和 `EMGroupChangeListener#onMemberJoined` 回调；
-- 其他群成员收到 `EMGroupChangeListener#onMemberJoined` 回调。
+- 邀请人收到 `EMGroupChangeListener#onInvitationAccepted` 回调和 `EMGroupChangeListener#onMembersJoined` 回调；
+- 其他群成员收到 `EMGroupChangeListener#onMembersJoined` 回调。
 
 2. 受邀用户需要确认才能进群。
 
 只有 `EMGroupOptions#inviteNeedConfirm` 设置为 `true` 和 `autoAcceptGroupInvitation` 设置为 `false` 时，受邀用户需要确认才能进群。这种情况下，受邀用户收到 `EMGroupChangeListener#onInvitationReceived` 回调，并选择同意或拒绝进群邀请：
 
-- 用户同意入群邀请后，邀请人收到 `EMGroupChangeListener#onInvitationAccepted` 回调和 `EMGroupChangeListener#onMemberJoined` 回调，其他群成员收到 `EMGroupChangeListener#onMemberJoined` 回调；
+- 用户同意入群邀请后，邀请人收到 `EMGroupChangeListener#onInvitationAccepted` 回调和 `EMGroupChangeListener#onMembersJoined` 回调，其他群成员收到 `EMGroupChangeListener#onMembersJoined` 回调；
 - 用户拒绝入群邀请后，邀请人收到 `EMGroupChangeListener#onInvitationDeclined` 回调。
 
 邀请用户入群的流程如下图所示：
@@ -371,15 +371,27 @@ EMGroupChangeListener groupListener = new EMGroupChangeListener() {
     }
 
     // 有新成员加入群组。除了新成员，其他群成员会收到该回调。
+    // 已废弃。请使用 onMembersJoined(String, List) 代替。
     @Override
     public void onMemberJoined(String groupId, String member) {
     }
 
-    // 有成员主动退出群。除了退群的成员，其他群成员会收到该回调。
+    // 有新成员（单个或多个）加入群组。除了新成员，其他群成员会收到该回调。
+    @Override
+    public void onMembersJoined(final String groupId, final List<String> members) {
+    }
+
+    // 有成员退出群。除了退群的成员，其他群成员会收到该回调。
+   // 已废弃。请使用 onMembersExited(String, List) 代替。
     @Override
     public void onMemberExited(String groupId, String member) {
     }
 
+    // 有成员（单个或多个）退出群（主动或被动）。除了退群的成员，其他群成员会收到该回调。
+    @Override
+    public void onMembersExited(final String groupId,  final List<String> members) {
+    }
+
     // 群组公告更新。群组所有成员会收到该回调。
     @Override
     public void onAnnouncementChanged(String groupId, String announcement) {

docs/document/android/demo.md

@@ -61,7 +61,7 @@ String cursor = result.getCursor();
 
 2. 调用 `joinGroup` 或 `applyJoinToGroup` 方法传入群组 ID，申请加入对应群组。
 
-   - 调用 `joinGroup` 方法加入无需群主或管理员审批的公开群，即 `EMGroupStyle` 设置为 `EMGroupStylePublicOpenJoin`。申请人不会收到任何回调，其他群成员会收到 `EMGroupChangeListener#onMemberJoined` 回调。
+   - 调用 `joinGroup` 方法加入无需群主或管理员审批的公开群，即 `EMGroupStyle` 设置为 `EMGroupStylePublicOpenJoin`。申请人不会收到任何回调，其他群成员会收到 `EMGroupChangeListener#onMembersJoined` 回调。
 
    示例代码如下：
 
@@ -79,7 +79,7 @@ String cursor = result.getCursor();
 
    - 若同意加入群组，需要调用 `acceptApplication` 方法。
 
-   申请人会收到 `EMGroupChangeListener#onRequestToJoinAccepted` 回调，其他群成员会收到 `EMGroupChangeListener#onMemberJoined` 回调。
+   申请人会收到 `EMGroupChangeListener#onRequestToJoinAccepted` 回调，其他群成员会收到 `EMGroupChangeListener#onMembersJoined` 回调。
 
    示例代码如下：
 
@@ -135,7 +135,7 @@ String cursor = result.getCursor();
 
 #### 群成员主动退出群组
 
-群成员可以调用 `leaveGroup` 方法退出群组。其他成员收到 `EMGroupChangeListener#onMemberExited` 回调。
+群成员可以调用 `leaveGroup` 方法退出群组。其他成员收到 `EMGroupChangeListener#onMembersExited` 回调。
 
 退出群组后，该用户将不再收到群消息。群主不能调用该接口退出群组，只能调用 `DestroyGroup` 解散群组。
 
@@ -149,7 +149,7 @@ EMClient.getInstance().groupManager().leaveGroup(groupId);
 
 #### 群成员被移出群组
 
-仅群主和群管理员可以调用 `removeUserFromGroup` 或 `asyncRemoveUsersFromGroup` 方法将单个或多个成员移出群组。被踢出群组后，被踢成员将会收到群组事件回调 `EMGroupChangeListener#onUserRemoved`，其他成员将会收到回调 `EMGroupChangeListener#onMemberExited`。被移出群组后，用户还可以再次加入群组。
+仅群主和群管理员可以调用 `removeUserFromGroup` 或 `asyncRemoveUsersFromGroup` 方法将单个或多个成员移出群组。被踢出群组后，被踢成员将会收到群组事件回调 `EMGroupChangeListener#onUserRemoved`，其他成员将会收到回调 `EMGroupChangeListener#onMembersExited`。被移出群组后，用户还可以再次加入群组。
 
 - 移出单个群成员，示例代码如下：
 

docs/document/android/error.md

@@ -10,7 +10,7 @@
 
 示例代码如下所示：  
 
- ```java
+```java
 // 注册失败会抛出 HyphenateException。
 EMClient.getInstance().createAccount(mAccount, mPassword);// 同步方法。
 ``` 
@@ -25,9 +25,7 @@ EMClient.getInstance().createAccount(mAccount, mPassword);// 同步方法。
 
 测试环境下，你在[环信即时通讯云控制台](https://console.easemob.com/user/login)创建用户后，环信服务器会自动为这些用户分配用户 Token，详见[测试环境下创建用户的介绍](/product/enable_and_configure_IM.html#测试环境)。
 
-在生产环境中，为了安全考虑，你需要在你的应用服务器集成[获取 App Token API](/server-side/easemob_app_token.html) 和[获取用户 Token API](/server-side/easemob_user_token.html) 实现获取 Token 的业务逻辑，使你的用户从你的应用服务器获取 Token。
-
-使用 token 登录时需要处理 token 过期的问题，比如在每次登录时更新 token 等机制。
+在生产环境中，为了安全考虑，你需要在你的应用服务器集成 [获取 App Token API](/server-side/easemob_app_token.html) 和 [获取用户 Token API](/server-side/easemob_user_token.html) 实现获取 Token 的业务逻辑，使你的用户从你的应用服务器获取 Token。SDK 会在 Token 过期时或者其有效期达到 80%（4.15.0 之前为 50%）时分别回调 `onTokenExpired` 和 `onTokenWillExpire` 通知用户更新 Token。你可以采取各种机制更新 Token，例如，每次登录时更新 token。
 
 ```java
 EMClient.getInstance().loginWithToken(mAccount, mToken, new EMCallBack() {
@@ -45,7 +43,7 @@ EMClient.getInstance().loginWithToken(mAccount, mToken, new EMCallBack() {
 });
 ```
 
-2. **用户 ID + 密码**登录是传统的登录方式。用户名和密码均由你的终端用户自行决定，密码需要符合[密码规则要求](/document/server-side/account_system.html#开放注册单个用户)。
+1. **用户 ID + 密码**登录是传统的登录方式。用户名和密码均由你的终端用户自行决定，密码需要符合[密码规则要求](/document/server-side/account_system.html#开放注册单个用户)。
 
 ```java
 EMClient.getInstance().login(mAccount, mPassword, new EMCallBack() {

docs/document/android/group_manage.md

@@ -2,13 +2,14 @@
 
 <Toc />
 
-发送方可以撤回一条发送成功的消息，包括已经发送的历史消息，离线消息或漫游消息。
-
-默认情况下，发送方可撤回发出 2 分钟内的消息。你可以在[环信即时通讯云控制台](https://console.easemob.com/user/login)的**功能配置** > **功能配置总览** > **基础功能**页面设置消息撤回时长，该时长不超过 7 天。
-
-:::tip
-除了透传消息，其他各类型的消息都支持撤回。
-:::
+单聊、群聊和聊天室聊天支持撤回一条发送成功的消息：
+
+- 对于单聊会话，只支持发送方撤回发送成功的消息。若消息过期，撤回失败。
+- 对于群组/聊天室会话，群主/聊天室所有者和管理员可撤回其他用户发送的消息。若消息过期，发送方撤回失败，只有群主/聊天室所有者和管理员可撤回。
+- **除了透传消息，其他各类型的消息都支持撤回**。
+- 默认情况下，发送方可撤回发出 2 分钟内的消息。你可以在[环信即时通讯云控制台](https://console.easemob.com/user/login)的 **功能配置** > **功能配置总览** > **基础功能** 页面设置消息撤回时长，该时长不超过 7 天。
+- 撤回消息时，服务端的消息（历史消息，离线消息或漫游消息）以及消息发送方和接收方的内存和数据库中的消息均会被移出。
+- 对于附件类型消息，包括图片、音频和视频和文件消息，撤回消息后，消息附件也相应删除。
 
 ## 技术原理