Merge pull request #638 from haoxiuwen/doc-v2

Add Docs of Delivering Messages to Online Users

docs/.vuepress/sidebar/document.ts

@@ -69,6 +69,7 @@ const documentSidebar = [
           { text: '删除消息', link: 'message_delete.html' },         
           { text: '实现消息回执', link: 'message_receipt.html'},
           { text: '翻译消息', link: 'message_translation.html' },
+          { text: '只投在线用户', link: 'message_deliver_only_online.html'},
           { text: '获取消息流量统计', link: 'message_traffic_statis.html', only: ['android', 'ios'] },
         ]
       },
@@ -181,7 +182,8 @@ const documentSidebar = [
           { text: '撤回消息', link: 'message_recall.html' },
           { text: '修改消息', link: 'message_modify.html' },
           { text: '删除消息', link: 'message_delete.html' }, 
-          { text: '实现消息回执', link: 'message_receipt.html' },         
+          { text: '实现消息回执', link: 'message_receipt.html' }, 
+          { text: '只投在线用户', link: 'message_deliver_only_online.html'},        
           { text: '翻译消息', link: 'message_translation.html' },
         ]
       },

docs/document/android/message_deliver_only_online.md

@@ -0,0 +1,41 @@
+# 消息只投递给在线用户
+
+环信即时通讯 IM 支持只将消息投递给在线用户。若接收方不在线，则无法收到消息。该功能用于实现应用只需要向在线用户进行展示目的，例如，利用透传消息实现群投票的票数实时变化, 只有在线用户需要关注实时变化的动态, 离线用户只需要再次上线时获取最终状态。
+
+各类型的消息均支持该功能，但该功能只支持单聊和群组聊天，不适用于聊天室。该类的消息与普通消息相比，存在如下差异：
+
+1. 不支持离线存储：若发送消息时，接收方离线则无法收到消息，即使重新登录后也收不到消息。对于普通消息，当接收方在线时, 实时收到消息提醒；当接收方离线时，实时发送离线推送消息，接收方再次上线时, 由环信 IM 服务器主动推给客户端离线期间的消息。
+2. 支持本地存储：消息成功发送后，写入数据库。
+3. 默认不支持漫游存储：发送的消息默认不存储在环信消息服务器，用户在其他终端设备上无法获取到该消息。如需开通在线消息的漫游存储，需联系环信商务。
+
+## 技术原理
+
+环信即时通讯 IM 通过 `EMMessage` 类支持只将消息投递给在线用户：
+
+- `deliverOnlineOnly`：设置消息是否只投递给在线用户。
+
+## 前提条件
+
+开始前，请确保满足以下条件：
+
+- 完成 SDK 初始化，详见 [快速开始](quickstart.html)。
+- 了解环信即时通讯 IM 的使用限制，详见 [使用限制](/product/limitation.html)。
+
+## 实现方法
+
+要将消息只投递给在线用户，你需要在发送消息时将 `EMMessage#deliverOnlineOnly` 设置为 `true`。
+
+下面以发送文本消息为例进行说明：
+
+```java
+// 创建一条文本消息，`content` 为消息文字内容。
+// `conversationId` 为消息接收方，单聊时为对端用户 ID、群聊时为群组 ID。
+EMMessage message = EMMessage.createTextSendMessage(content, conversationId);
+// 消息是否只投递在线用户。（默认）`false`：不论用户是否在线均投递；`true`：只投递给在线用户。若用户离线，消息不投递。
+message.deliverOnlineOnly(true);
+// 会话类型：单聊为 EMMessage.ChatType.Chat，群聊为 EMMessage.ChatType.GroupChat，默认为单聊。
+message.setChatType(EMMessage.ChatType.Chat);
+// 发送消息。
+EMClient.getInstance().chatManager().sendMessage(message);
+```
+

docs/document/applet/message_deliver_only_online.md

@@ -0,0 +1,6 @@
+---
+{
+    pageUri: "/document/web/message_deliver_only_online.html",
+    title: "消息只投在线用户"
+}
+---

docs/document/flutter/message_deliver_only_online.md

@@ -0,0 +1,45 @@
+# 消息只投递给在线用户
+
+环信即时通讯 IM 支持只将消息投递给在线用户。若接收方不在线，则无法收到消息。该功能用于实现应用只需要向在线用户进行展示目的，例如，利用透传消息实现群投票的票数实时变化, 只有在线用户需要关注实时变化的动态, 离线用户只需要再次上线时获取最终状态。
+
+各类型的消息均支持该功能，但该功能只支持单聊和群组聊天，不适用于聊天室。该类的消息与普通消息相比，存在如下差异：
+
+1. 不支持离线存储：若发送消息时，接收方离线则无法收到消息，即使重新登录后也收不到消息。对于普通消息，当接收方在线时, 实时收到消息提醒；当接收方离线时，实时发送离线推送消息，接收方再次上线时, 由环信 IM 服务器主动推给客户端离线期间的消息。
+2. 支持本地存储：消息成功发送后，写入数据库。
+3. 默认不支持漫游存储：发送的消息默认不存储在环信消息服务器，用户在其他终端设备上无法获取到该消息。如需开通在线消息的漫游存储，需联系环信商务。
+
+## 技术原理
+
+环信即时通讯 IM 通过 `EMMessage` 类支持只将消息投递给在线用户：
+
+- `deliverOnlineOnly`：设置消息是否只投递给在线用户。
+
+## 前提条件
+
+开始前，请确保满足以下条件：
+
+- 完成 SDK 初始化，详见 [快速开始](quickstart.html)。
+- 了解环信即时通讯 IM 的使用限制，详见 [使用限制](/product/limitation.html)。
+
+## 实现方法
+
+要将消息只投递给在线用户，你需要在发送消息时将 `EMMessage#deliverOnlineOnly` 设置为 `true`。
+
+下面以发送文本消息为例进行说明：
+
+```dart
+// 创建一条文本消息。
+final msg = EMMessage.createTxtSendMessage(
+  // `targetId` 为接收方，单聊为对端用户 ID、群聊为群组 ID。
+  targetId: conversationId,
+  // `content` 为消息文字内容。
+  content: 'hello',
+  // 会话类型：单聊为 `Chat`，群聊为 `GroupChat`，默认为单聊。
+  chatType: ChatType.Chat,
+  deliverOnlineOnly: true,
+);
+
+// 发送消息。
+EMClient.getInstance.chatManager.sendMessage(msg);
+```
+

docs/document/ios/message_deliver_only_online.md

@@ -0,0 +1,48 @@
+# 消息只投递给在线用户
+
+环信即时通讯 IM 支持只将消息投递给在线用户。若接收方不在线，则无法收到消息。该功能用于实现应用只需要向在线用户进行展示目的，例如，利用透传消息实现群投票的票数实时变化, 只有在线用户需要关注实时变化的动态, 离线用户只需要再次上线时获取最终状态。
+
+各类型的消息均支持该功能，但该功能只支持单聊和群组聊天，不适用于聊天室。该类的消息与普通消息相比，存在如下差异：
+
+1. 不支持离线存储：若发送消息时，接收方离线则无法收到消息，即使重新登录后也收不到消息。对于普通消息，当接收方在线时, 实时收到消息提醒；当接收方离线时，实时发送离线推送消息，接收方再次上线时, 由环信 IM 服务器主动推给客户端离线期间的消息。
+2. 支持本地存储：消息成功发送后，写入数据库。
+3. 默认不支持漫游存储：发送的消息默认不存储在环信消息服务器，用户在其他终端设备上无法获取到该消息。如需开通在线消息的漫游存储，需联系环信商务。
+
+## 技术原理
+
+环信即时通讯 IM 通过 `EMChatMessage` 类支持只将消息投递给在线用户：
+
+- `deliverOnlineOnly`：设置消息是否只投递给在线用户。
+
+## 前提条件
+
+开始前，请确保满足以下条件：
+
+- 完成 SDK 初始化，详见 [快速开始](quickstart.html)。
+- 了解环信即时通讯 IM 的使用限制，详见 [使用限制](/product/limitation.html)。
+
+## 实现方法
+
+要将消息只投递给在线用户，你需要在发送消息时将 `EMChatMessage#deliverOnlineOnly` 设置为 `YES`。
+
+下面以发送文本消息为例进行说明：
+
+```objective-c
+// 调用 initWithText 创建文本消息。`content` 为文本消息的内容。
+EMTextMessageBody *textMessageBody = [[EMTextMessageBody alloc] initWithText:content];
+// 消息接收方：单聊为对端用户的 ID，群聊为群组 ID。
+NSString* conversationId = @"remoteUserId";
+EMChatMessage *message = [[EMChatMessage alloc] initWithConversationID:conversationId
+                                                      body:textMessageBody
+                                                               ext:messageExt];
+// 会话类型：单聊为 `EMChatTypeChat`，群聊为 `EMChatTypeGroupChat`。
+message.chatType = EMChatTypeChat;
+// 消息是否只投递在线用户。（默认）`NO`：不论用户是否在线均投递；`YES`：只投递给在线用户。若用户离线，消息不投递。
+message.deliverOnlineOnly = YES；
+// 发送消息。
+[[EMClient sharedClient].chatManager sendMessage:message
+                                        progress:nil
+                                      completion:nil];
+
+```
+

docs/document/react-native/message_deliver_only_online.md

@@ -0,0 +1,47 @@
+# 消息只投递给在线用户
+
+环信即时通讯 IM 支持只将消息投递给在线用户。若接收方不在线，则无法收到消息。该功能用于实现应用只需要向在线用户进行展示目的，例如，利用透传消息实现群投票的票数实时变化, 只有在线用户需要关注实时变化的动态, 离线用户只需要再次上线时获取最终状态。
+
+各类型的消息均支持该功能，但该功能只支持单聊和群组聊天，不适用于聊天室。该类的消息与普通消息相比，存在如下差异：
+
+1. 不支持离线存储：若发送消息时，接收方离线则无法收到消息，即使重新登录后也收不到消息。对于普通消息，当接收方在线时, 实时收到消息提醒；当接收方离线时，实时发送离线推送消息，接收方再次上线时, 由环信 IM 服务器主动推给客户端离线期间的消息。
+2. 支持本地存储：消息成功发送后，写入数据库。
+3. 默认不支持漫游存储：发送的消息默认不存储在环信消息服务器，用户在其他终端设备上无法获取到该消息。如需开通在线消息的漫游存储，需联系环信商务。
+
+## 技术原理
+
+环信即时通讯 IM 通过 `ChatMessage` 类支持只将消息投递给在线用户：
+
+- `deliverOnlineOnly`：设置消息是否只投递给在线用户。
+
+## 前提条件
+
+开始前，请确保满足以下条件：
+
+- 完成 SDK 初始化，详见 [快速开始](quickstart.html)。
+- 了解环信即时通讯 IM 的使用限制，详见 [使用限制](/product/limitation.html)。
+
+## 实现方法
+
+要将消息只投递给在线用户，你需要在发送消息时将 `ChatMessage#deliverOnlineOnly` 设置为 `true`。
+
+下面以发送文本消息为例进行说明：
+
+```ts
+// 创建一条文本消息，`content` 为消息文字内容。
+// `conversationId` 为消息接收方，单聊时为对端用户 ID、群聊时为群组 ID。
+// `conversationIdType` 会话类型：单聊为 ChatMessageChatType.PeerChat，群聊为 ChatMessageChatType.GroupChat
+// 消息是否只投递在线用户。（默认）`false`：不论用户是否在线均投递；`true`：只投递给在线用户。若用户离线，消息不投递。
+const message = createTextMessage(conversationId, content, conversationIdType, {
+  deliverOnlineOnly: true,
+});
+// 发送消息。
+ChatClient.getInstance().chatManager.sendMessage(msg, {
+  onError: (localMsgId: string, error: ChatError) => {
+    // todo: 发送消息失败
+  },
+  onSuccess: (message: ChatMessage) => {
+    // todo: 发送消息成功,
+  },
+});
+```

docs/document/server-side/callback_configurations.md

@@ -2046,7 +2046,7 @@ payload 字段含义：
     "group_id": "662XXXX13", 
     "host": "XXXX", 
     "appkey": "XXXX#XXXX", 
-    "from": "XXXX#XXXX", 
+    "from": "662XXXX13", 
     "to": "aaa111", 
     "eventType": "chat", 
     "msg_id": "976432657191668068", 
@@ -2091,7 +2091,7 @@ payload 字段含义：
             "error_code": "ok" 
         } 
     }, 
-    "group_id": "XXXX", 
+    "group_id": "662XXXX13", 
     "host": "XXXX", 
     "appkey": "XXXX#XXXX", 
     "from": "662XXXX13", 
@@ -2139,10 +2139,10 @@ payload 字段含义：
             "error_code": "ok" 
         } 
     }, 
-    "group_id": "XXXX", 
+    "group_id": "632XXXX13", 
     "host": "XXXX", 
     "appkey": "XXXX#XXXX", 
-    "from": "662XXXX13", 
+    "from": "632XXXX13", 
     "to": "aaa111", 
     "eventType": "chat", 
     "msg_id": "976432657191668068", 

docs/document/unity/message_deliver_only_online.md

@@ -0,0 +1,46 @@
+# 消息只投递给在线用户
+
+环信即时通讯 IM 支持只将消息投递给在线用户。若接收方不在线，则无法收到消息。该功能用于实现应用只需要向在线用户进行展示目的，例如，利用透传消息实现群投票的票数实时变化, 只有在线用户需要关注实时变化的动态, 离线用户只需要再次上线时获取最终状态。
+
+各类型的消息均支持该功能，但该功能只支持单聊和群组聊天，不适用于聊天室。该类的消息与普通消息相比，存在如下差异：
+
+1. 不支持离线存储：若发送消息时，接收方离线则无法收到消息，即使重新登录后也收不到消息。对于普通消息，当接收方在线时, 实时收到消息提醒；当接收方离线时，实时发送离线推送消息，接收方再次上线时, 由环信 IM 服务器主动推给客户端离线期间的消息。
+2. 支持本地存储：消息成功发送后，写入数据库。
+3. 默认不支持漫游存储：发送的消息默认不存储在环信消息服务器，用户在其他终端设备上无法获取到该消息。如需开通在线消息的漫游存储，需联系环信商务。
+
+## 技术原理
+
+环信即时通讯 IM 通过 `Message` 类支持只将消息投递给在线用户：
+
+- `DeliverOnlineOnly`：设置消息是否只投递给在线用户。
+
+## 前提条件
+
+开始前，请确保满足以下条件：
+
+- 完成 SDK 初始化，详见 [快速开始](quickstart.html)。
+- 了解环信即时通讯 IM 的使用限制，详见 [使用限制](/product/limitation.html)。
+
+## 实现方法
+
+要将消息只投递给在线用户，你需要在发送消息时将 `Message#DeliverOnlineOnly` 设置为 `true`。
+
+下面以发送文本消息为例进行说明：
+
+```csharp
+// 创建一条文本消息，`content` 为消息文字内容。
+// `conversationId` 为消息接收方，单聊时为对端用户 ID、群聊时为群组 ID。
+Message message = Message.CreateTextSendMessage(conversationId, content);
+// 消息是否只投递在线用户。（默认）`false`：不论用户是否在线均投递；`true`：只投递给在线用户。若用户离线，消息不投递。
+message.DeliverOnlineOnly = true;
+// 会话类型：单聊为 MessageType.Chat，群聊为 MessageType.Group，默认为单聊。
+message.MessageType = MessageType.Chat;
+// 发送消息。
+SDKClient.Instance.ChatManager.SendMessage(ref message, new CallBack(
+    onSuccess: () => {
+    },
+    onError: (code, desc) => {
+    }
+));
+```
+

docs/document/web/message_deliver_only_online.md

@@ -0,0 +1,53 @@
+# 消息只投递给在线用户
+
+环信即时通讯 IM 支持只将消息投递给在线用户。若接收方不在线，则无法收到消息。该功能用于实现应用只需要向在线用户进行展示目的，例如，利用透传消息实现群投票的票数实时变化, 只有在线用户需要关注实时变化的动态, 离线用户只需要再次上线时获取最终状态。
+
+各类型的消息均支持该功能，但该功能只支持单聊和群组聊天，不适用于聊天室。该类的消息与普通消息相比，存在如下差异：
+
+1. 不支持离线存储：若发送消息时，接收方离线则无法收到消息，即使重新登录后也收不到消息。对于普通消息，当接收方在线时, 实时收到消息提醒；当接收方离线时，实时发送离线推送消息，接收方再次上线时, 由环信 IM 服务器主动推给客户端离线期间的消息。
+2. 默认不支持漫游存储：发送的消息默认不存储在环信消息服务器，用户在其他终端设备上无法获取到该消息。如需开通在线消息的漫游存储，需联系环信商务。
+
+## 技术原理
+
+环信即时通讯 IM 通过 `Message` 类支持只将消息投递给在线用户：
+
+- `deliverOnlineOnly`：设置消息是否只投递给在线用户。
+
+## 前提条件
+
+开始前，请确保满足以下条件：
+
+- 完成 SDK 初始化，详见 [快速开始](quickstart.html)。
+- 了解环信即时通讯 IM 的使用限制，详见 [使用限制](/product/limitation.html)。
+
+## 实现方法
+
+要将消息只投递给在线用户，你需要在发送消息时将 `Message#deliverOnlineOnly` 设置为 `true`。
+
+下面以发送文本消息为例进行说明：
+
+```javascript
+// 发送文本消息。
+function sendTextMessage() {
+  let option = {
+    // 消息类型。
+    type: "txt",
+    // 消息内容。
+    msg: "message content",
+    // 消息接收方：单聊为对方用户 ID，群聊为群组 ID。
+    to: "username",
+    // 会话类型：单聊和群聊分别为 `singleChat` 和 `groupChat`，默认为单聊。
+    chatType: "singleChat",
+    // 消息是否只投递在线用户。（默认）`false`：不论用户是否在线均投递；`true`：只投递给在线用户。若用户离线，消息投递失败。
+    deliverOnlineOnly: "true",
+  };
+  // 创建文本消息。
+  let msg = WebIM.message.create(option);
+  // 调用 `send` 方法发送该文本消息。
+    conn.send(msg).then((res)=>{
+      console.log("Send message success",res);
+    }).catch((e)=>{
+      console.log("Send message fail",e);
+    });
+}
+```

docs/document/windows/message_deliver_only_online.md

@@ -0,0 +1,46 @@
+# 消息只投递给在线用户
+
+环信即时通讯 IM 支持只将消息投递给在线用户。若接收方不在线，则无法收到消息。该功能用于实现应用只需要向在线用户进行展示目的，例如，利用透传消息实现群投票的票数实时变化, 只有在线用户需要关注实时变化的动态, 离线用户只需要再次上线时获取最终状态。
+
+各类型的消息均支持该功能，但该功能只支持单聊和群组聊天，不适用于聊天室。该类的消息与普通消息相比，存在如下差异：
+
+1. 不支持离线存储：若发送消息时，接收方离线则无法收到消息，即使重新登录后也收不到消息。对于普通消息，当接收方在线时, 实时收到消息提醒；当接收方离线时，实时发送离线推送消息，接收方再次上线时, 由环信 IM 服务器主动推给客户端离线期间的消息。
+2. 支持本地存储：消息成功发送后，写入数据库。
+3. 默认不支持漫游存储：发送的消息默认不存储在环信消息服务器，用户在其他终端设备上无法获取到该消息。如需开通在线消息的漫游存储，需联系环信商务。
+
+## 技术原理
+
+环信即时通讯 IM 通过 `Message` 类支持只将消息投递给在线用户：
+
+- `DeliverOnlineOnly`：设置消息是否只投递给在线用户。
+
+## 前提条件
+
+开始前，请确保满足以下条件：
+
+- 完成 SDK 初始化，详见 [快速开始](quickstart.html)。
+- 了解环信即时通讯 IM 的使用限制，详见 [使用限制](/product/limitation.html)。
+
+## 实现方法
+
+要将消息只投递给在线用户，你需要在发送消息时将 `Message#DeliverOnlineOnly` 设置为 `true`。
+
+下面以发送文本消息为例进行说明：
+
+```csharp
+// 创建一条文本消息，`content` 为消息文字内容。
+// `conversationId` 为消息接收方，单聊时为对端用户 ID、群聊时为群组 ID。
+Message message = Message.CreateTextSendMessage(conversationId, content);
+// 消息是否只投递在线用户。（默认）`false`：不论用户是否在线均投递；`true`：只投递给在线用户。若用户离线，消息不投递。
+message.DeliverOnlineOnly = true;
+// 会话类型：单聊为 MessageType.Chat，群聊为 MessageType.Group，默认为单聊。
+message.MessageType = MessageType.Chat;
+// 发送消息。
+SDKClient.Instance.ChatManager.SendMessage(ref message, new CallBack(
+    onSuccess: () => {
+    },
+    onError: (code, desc) => {
+    }
+));
+```
+