easemob-websdk 4.24.1 → 5.0.0

package/README.md

@@ -1,59 +1,115 @@
-# 环信 IM SDK 介绍
+# 环信 Web IM SDK
 
-sdk 提供完整的即时消息功能开发功能，屏蔽/封装并阻止其内部复杂的细节，并提供相对简单和简洁的 API 接口，以方便第三方应用程序快速集成 PC/mobile Web 应用程序的即时消息功能
+`easemob-websdk` 是面向 Web 应用的 TypeScript IM SDK，提供连接管理、消息、会话、联系人、群组、聊天室、用户资料、在线状态和推送设置等类型安全的 API。
 
-## 可以通过以下方式引用 WebSDK:
-
-1. 安装
+## 安装
 
 ```bash
-npm install easemob-websdk --save
+npm install easemob-websdk
 ```
 
-2. 引入 SDK。
+发布包同时支持 ESM 和 CommonJS。可从主入口导入完整 SDK，也可从 Manager 子路径导入，以便业务构建工具移除未使用的 Manager 代码。
+
+## 快速开始
+
+使用应用所需的 Manager 初始化客户端，再使用由应用服务端签发的用户 Token 登录：
+
+```ts
+import { ChatClient, ChatManager } from 'easemob-websdk';
+
+const client = ChatClient.init({
+  appKey: 'your-org#your-app',
+  managers: [ChatManager],
+});
 
+client.addEventHandler('connection', {
+  onConnected: () => {
+    console.log('connected');
+  },
+  onDisconnected: event => {
+    console.warn('disconnected', event.reason);
+  },
+});
+
+await client.login({
+  userId: 'user-id',
+  token: 'user-token',
+});
 ```
-import EC from 'easemob-websdk'
+
+登录成功后可发送单聊文本消息：
+
+```ts
+const message = client.chatManager.createTextMessage({
+  conversationId: 'peer-user-id',
+  conversationType: 'singleChat',
+  content: 'Hello from Easemob',
+});
+
+await client.chatManager.sendMessage(message);
 ```
 
-3、初始化 SDK
+## Manager 子路径导入
+
+```ts
+import { ChatClient } from 'easemob-websdk';
+import { ChatManager } from 'easemob-websdk/managers/chat';
+import { GroupManager } from 'easemob-websdk/managers/group';
 
-```javascript
-const conn = new EC.connection({
-	appKey: '<your app key>',
+const client = ChatClient.init({
+  appKey: 'your-org#your-app',
+  managers: [ChatManager, GroupManager],
 });
 ```
 
-4、登录环信服务
+可用的 Manager 子路径：
+
+- `easemob-websdk/managers/chat`
+- `easemob-websdk/managers/chat-thread`
+- `easemob-websdk/managers/chatroom`
+- `easemob-websdk/managers/contact`
+- `easemob-websdk/managers/group`
+- `easemob-websdk/managers/presence`
+- `easemob-websdk/managers/push`
+- `easemob-websdk/managers/user-info`
+
+## 浏览器 script 标签
+
+未使用打包工具的 Web 应用可从 CDN 加载 IIFE bundle，加载后的全局变量为 `IMSDK`：
 
-```javascript
-const options = {
-	user: 'username',
-	accessToken: 'accessToken',
-};
-conn.open(options);
+```html
+<script src="https://unpkg.com/easemob-websdk@latest/bundle/im-sdk-web.iife.js"></script>
+<script>
+  const client = IMSDK.ChatClient.init({
+    appKey: 'your-org#your-app',
+    managers: [IMSDK.ChatManager],
+  });
+</script>
 ```
 
-5、发送消息
-
-```javascript
-let option = {
-	chatType: 'singleChat', // 会话类型，设置为单聊。
-	type: 'txt', // 消息类型。
-	to: 'userID', // 消息接收方（用户 ID)。
-	msg: 'message content', // 消息内容。
-};
-let msg = EC.message.create(option);
-conn.send(msg)
-	.then(() => {
-		console.log('send private text Success');
-	})
-	.catch((e) => {
-		console.log('Send private text error');
-	});
+## 错误处理
+
+所有公开异步 API 都会 reject `SDKError` 子类。请根据稳定的 SDK 错误码处理异常，不要解析错误文案：
+
+```ts
+import { isSDKError } from 'easemob-websdk';
+
+try {
+  await client.login({ userId: 'user-id', token: 'user-token' });
+} catch (error) {
+  if (isSDKError(error)) {
+    console.error(error.code, error.message, error.details);
+  }
+}
 ```
 
-## 参考文档
+## 安全建议
+
+- 从应用服务端获取用户 Token，不要把 App 凭据或长期有效 Token 写入浏览器代码。
+- 不要在业务日志中输出 Token、授权请求头或消息正文。
+- 按照应用自身的安全策略保存和刷新 Token。
+
+## 资源
 
--   [Easemob Chat SDK 产品概述](https://doc.easemob.com/product/introduction.html)
--   [Easemob Chat SDK API 参考](https://doc.easemob.com/apidoc/web/index.html)
+- 官网：<https://www.easemob.com/>
+- SDK 发布文档提供生成的 TypeDoc API Reference 与错误码表。