Web SDK 概述

Web SDK（npm 包 @deeprespond/im-web）让你在网页（桌面浏览器、手机浏览器中的 H5 页面、Electron 应用）中接入 IM 服务：登录、长连接与断线重连、消息收发、会话同步和本地缓存都由 SDK 完成，你只需要把数据显示出来。SDK 用 TypeScript 编写，自带类型声明，不依赖任何前端框架；React 和 Vue 另有官方的绑定包。

import { createDRClient } from '@deeprespond/im-web';

const im = createDRClient({ appKey: '1575529652#demo', apiUrl: 'https://im.example.com' });
await im.auth.loginWithTicket({ ticket });          // 已登录过的，创建后自动恢复，不必再登录
const list = im.conversations.list();               // 会话列表：先显示本地数据，后台同步
list.subscribe(() => render(list.getSnapshot().items));

能做什么

客户端对象 im 按功能分为以下几个部分：

属性	功能	文档
`im.auth`、`im.connection`、`im.config`	登录、退出、修改密码；连接状态与诊断；应用的运行配置	初始化、登录与连接
`im.conversations`	会话列表、未读数、置顶、草稿、正在输入	会话
`im.messages`	消息列表、发送、撤回、表情回应、置顶、已读回执、本地搜索	消息
`im.users`、`im.friends`、`im.presence`、`im.devices`	本人与其他用户的资料、好友与黑名单、在线状态、本人的登录设备	用户、好友与在线状态
`im.groups`	群、群成员、入群申请与邀请、入群链接	群组
`im.files`	上传、下载、群文件、录音	文件
`im.chatrooms`	聊天室	聊天室
`im.calls`	一对一和群组的语音、视频通话	音视频通话
`im.channels`	独立 RTC 频道：加入、恢复、媒体、状态与退出	频道接入
`im.push`、`im.reports`	新消息提醒、推送设置、会话免打扰；举报	提醒、推送设置与举报
`im.on()`、`DRError`	事件、错误与提示文案	事件与错误处理

第一次接入请先看快速集成，用 React 或 Vue 开发的再看在 React 和 Vue 中使用。

运行环境

浏览器	最低版本
Chrome、Edge	100
Firefox	105
Safari、iOS Safari	16.4
Electron	22

Android 上的 WebView 跟随系统的 Chrome 版本，iOS 上各种 App 内的 WebView 跟随系统的 Safari 版本。SDK 用到 WebSocket、fetch、IndexedDB、Web Locks、BroadcastChannel 等浏览器能力，不满足要求的浏览器在创建客户端时抛出 unsupported 错误（details.missing 列出缺少的能力），SDK 不做降级。

请使用 HTTPS：Web Locks 等能力只在安全上下文（HTTPS、localhost、Electron 的本地页面）中可用。用 HTTP 访问的页面中 SDK 仍可使用，但多个标签页之间的协调改用可靠性较低的方式，并在控制台打印警告，见多个标签页。
IndexedDB 不可用时（个别浏览器的隐私模式），SDK 自动改用内存保存数据：功能照常，只是刷新页面后要重新从服务端加载。
服务端渲染：可以在 Next.js、Nuxt 等框架的服务端代码中导入 SDK（导入时不访问浏览器对象），但只能在浏览器中创建客户端，见在 React 和 Vue 中使用。
Electron：创建客户端时把 platform 设为 windows、macos 或 linux，这样按平台限制设备数时它算作电脑而不是网页。
不用于服务端：Node.js 中调用 IM 服务请使用服务端 REST API。微信小程序使用专用 /miniprogram 子路径或原生预打包包，见微信小程序 SDK；UniApp H5 使用专用入口，见 UniApp H5；UniApp App 和 React Native 尚未提供对应原生实现。

页面设置了内容安全策略（CSP）的，connect-src 要允许 IM 服务的地址（含 wss://）、文件存储和 CDN 的地址以及音视频的媒体服务地址，img-src、media-src 要允许文件存储和 CDN 的地址，worker-src 要允许 blob:（上传前在 Worker 中处理图片）。

安装

用 npm 或 pnpm 安装：

bash

npm install @deeprespond/im-web
# 或
pnpm add @deeprespond/im-web

包只提供 ES 模块，适用于 Vite、webpack、Rollup 等构建工具。React、Vue 的绑定包另外安装，见在 React 和 Vue 中使用。

用 `<script>` 引入

不使用构建工具的页面，可以直接引入包中的 dist/drim.min.js（把它放到你自己的服务器或 CDN 上）。它把 SDK 的全部导出放在全局变量 DRIM 上：

html

<script src="/static/drim.min.js"></script>
<script>
  const im = DRIM.createDRClient({ appKey: '1575529652#demo', apiUrl: 'https://im.example.com' });
  im.on('connection.stateChanged', (state) => console.log('连接状态', state.kind));
</script>

DRIM 中只有主入口的内容，不含下文的显示辅助和中文提示文案，需要它们的请使用 npm 包。

用 <script> 引入时使用音视频通话：drim.min.js 不含音视频的媒体组件，第一次通话时从 drim.min.js 所在的目录自动加载 livekit-client.umd.js，页面不需要另外引入。自己托管时，把下载包中的 livekit-client.umd.js 与 drim.min.js 放在同一目录，否则通话时以 unsupported 拒绝。用 npm 安装 Web SDK 时，媒体组件随包安装，由打包工具按需拆分，不需要这一步。

html

<!-- 同一目录下还有下载包中的 livekit-client.umd.js -->
<script src="/static/drim/drim.min.js"></script>

子路径导出

除了主入口，包中还有两个按需引入的子模块，不用时不会打包进你的应用：

导入路径	内容
`@deeprespond/im-web/render`	显示辅助：`displayName`（用户的显示名，按好友备注、群昵称、昵称、用户名取第一个非空的）、`conversationTitle`（会话标题）、`summarize`（会话列表中最后一条消息的摘要）、`renderTip`（群提示的文字）、`renderCallRecord`（通话记录的文字）、`renderRecall`（撤回提示），用法见消息
`@deeprespond/im-web/locale/zh-CN`	中文提示文案：`zhCN`（文案表，可以整体替换为其他语言）、`describeError`（按错误码给出提示文字），见事件与错误处理

import { conversationTitle, summarize } from '@deeprespond/im-web/render';
import { describeError } from '@deeprespond/im-web/locale/zh-CN';

基本概念

客户端对象

createDRClient() 创建一个客户端对象（类型为 DRClient），整个页面共用这一个：同一页面中每个 AppKey 同一时刻只能有一个客户端。创建时不发任何请求；这个浏览器中已经登录过的，SDK 立即恢复登录，你不必再调用登录。详见初始化、登录与连接。

可订阅的列表

会话列表、消息列表、好友列表、群成员列表等会持续变化的数据，以可订阅的对象（LiveList，消息列表为 MessageList）提供：

const list = im.conversations.list();
const off = list.subscribe(() => {
  const { items, loading, hasMore } = list.getSnapshot();
  render(items, loading, hasMore);
});
// 不再显示时
off();
list.dispose();

getSnapshot() 返回当前的快照。没有变化时每次返回同一个对象；有变化时返回新的快照，其中没有变化的条目仍是原来的对象，界面可以按引用判断哪些行要重新渲染。
快照和其中的数据都已冻结，不能修改；要附加界面状态的，另外保存。
subscribe(listener) 在快照变化时调用 listener（不带参数），返回取消订阅的函数。同一轮事件循环中的多次变化合并为一次通知。
getSnapshot、subscribe 已绑定到所属的对象，可以单独传递，如 React 的 useSyncExternalStore(list.subscribe, list.getSnapshot)。
不再显示时调用 dispose() 释放。退出登录、切换用户时 SDK 先把快照清空并通知一次，再释放全部列表。

登录状态、连接状态、未读总数等单个的值可以同步读取（如 im.auth.state、im.conversations.getUnreadTotal()），变化时发出对应的事件。

本地优先，后台同步

会话列表、消息、好友、群等数据都保存在浏览器的 IndexedDB 中，你读到的总是本地的数据：页面刷新后立即显示上次的内容，不必等待网络。SDK 在后台连接长连接、同步变化，写入本地后再通知你。离线时发送的消息进入发送队列，网络恢复后自动发出。

多个标签页共用一个连接

同一浏览器中打开了多个标签页时，它们共用一个设备标识、一次登录和一条长连接：其中一个是主标签页，负责连接、同步和发送；其他标签页读取同一份本地数据，需要请求服务端的操作由 SDK 转给主标签页执行。每个标签页照常创建自己的客户端、调用同样的方法，这些协调对你是透明的。一个标签页登录或退出，其他标签页随之登录或退出。详见同一浏览器的多个标签页。

与服务端的关系

Web SDK 只调用 IM 服务的客户端接口，用户的身份由你的业务服务端担保：

你的业务服务端用 App Token 调用 IM 服务的 REST API，为用户创建 IM 账号，并在用户登录你的业务系统后为他签发登录凭证；
网页从你的业务服务端取得凭证，交给 SDK 登录 IM；
之后收发消息、同步会话都由 SDK 直接与 IM 服务通信。

App Token 和 Client Secret 是服务端凭据，不能出现在网页中。AppKey（org_name#app_name）是应用的公开标识，可以写在网页中，在控制台的应用详情中查看。

Web SDK 返回的消息、会话、群等数据对象与服务端 REST API 中的对象字段相同（如 client_msg_id、unread_count），可以对照服务端文档使用。

独立 RTC 频道

已提供独立频道接入源码，调用 API、媒体权限与前后台边界见频道接入。频道版本制品尚未发布，实际支持和验收范围见平台表。

Web SDK 概述 ​

能做什么 ​

运行环境 ​

安装 ​

用 <script> 引入 ​

子路径导出 ​

基本概念 ​

客户端对象 ​

可订阅的列表 ​

本地优先，后台同步 ​

多个标签页共用一个连接 ​

与服务端的关系 ​

独立 RTC 频道 ​