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));

專案	說明
當前版本	1.1.1（版本與支援狀態）
安裝	`npm install @deeprespond/im-web`
執行環境	Chrome / Edge 100、Firefox 105、Safari 16.4、Electron 22 以上
現成介面	React UIKit、Vue UIKit（上圖為 React UIKit）
框架繫結	React、Vue

能做什麼

客戶端物件 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.game`	遊戲房間：加入、幀同步、自定義訊息、斷線重連（1.1.0 起）	遊戲房間 · Web 客戶端接入
`im.ai`	AI 機器人回覆的即時內容、停止生成	AI 回覆
`im.push`、`im.reports`	新訊息提醒、推送設定、會話免打擾；舉報	提醒、推送設定與舉報
`im.on()`、`DRError`	事件、錯誤與提示文案	事件與錯誤處理

第一次接入請先看快速整合，想先看效果可以直接下載Demo 執行指南中的演示頁程式碼包；用 React 或 Vue 開發的再看在 React 和 Vue 中使用與可直接執行的React / Vue 工程版 Demo。

需要現成的聊天介面，不必從 Demo 複製整頁：React 專案用 React UIKit（@deeprespond/im-web-react-uikit），Vue 3 專案用 Vue UIKit（@deeprespond/im-web-vue-uikit）。兩者都提供會話、聊天、好友、群組和可組合的元件，與 SDK 同版本釋出。

執行環境

瀏覽器	最低版本
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，完整可執行示例見 Demo 執行指南；UniApp App 使用原生外掛，見 UniApp SDK；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 頻道

im.channels 用於會議、語音房等不建群的音影片頻道，呼叫方式、媒體許可權和頁面收尾見頻道接入，各平臺的支援情況見版本與支援狀態。

語言選擇與偏好

支援簡體中文、繁體中文和英語。網頁語言按 URL lang、本機已儲存選擇、賬號偏好、瀏覽器語言順序確定；SDK 文案由宿主選擇本地目錄，不會翻譯使用者訊息。賬號語言介面、請求頭、通知模板與 SDK 示例見語言與本地化。

Web SDK 概述 ​

能做什麼 ​

執行環境 ​

安裝 ​

用 <script> 引入 ​

子路徑匯出 ​

基本概念 ​

客戶端物件 ​

可訂閱的列表 ​

本地優先，後臺同步 ​

多個標籤頁共用一個連線 ​

與服務端的關係 ​

獨立 RTC 頻道 ​

語言選擇與偏好 ​