Web 从零接入晞晗IM

本页面向普通浏览器网站。完成后，你可以用两个测试账号连接同一个 XHIM Server， 发送并接收第一条文字消息。

如果你的应用由 Electron 打包，请改看 Electron 接入。

1. 准备接入信息

向服务端负责人领取：

Server URL       例如 https://im-test.example.com
App ID           例如 xhim-demo
当前用户 ID      例如 alice
对端用户 ID      例如 bob

本地开发网址和正式网址还需要加入服务端允许的 Origin。正式环境使用 HTTPS/WSS， 不要把管理员密钥、数据库密码或长期访问令牌放进网页。

2. 安装 SDK

npm install @xihansoftware/xhim-web

本包是标准 ESM 包，可用于原生 TypeScript、React、Vue 或 Svelte 项目。

3. 连接当前账号

Development Server 已开启测试登录时，可以直接使用开发凭证提供器：

import {
  XHIMWebClient,
  createXHIMDevelopmentCredentialProvider
} from '@xihansoftware/xhim-web'

const server = 'https://im-test.example.com'
const appId = 'xhim-demo'
const currentUserId = 'alice'

const client = await XHIMWebClient.connect({
  server,
  appId,
  accountHint: currentUserId,
  credentialProvider: createXHIMDevelopmentCredentialProvider({
    server,
    appId,
    userId: currentUserId,
    deviceId: `web-${currentUserId}`
  })
})

正式环境把 credentialProvider 换成应用自己的后台接口：

const client = await XHIMWebClient.connect({
  server: 'https://im.example.com',
  appId: 'your-app',
  accountHint: signedInUser.id,
  credentialProvider: async ({ forceRefresh }) => {
    const response = await fetch('/api/im/credential', {
      method: 'POST',
      credentials: 'include',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ forceRefresh })
    })
    if (!response.ok) throw new Error('当前账号无法登录 IM')
    return response.json()
  }
})

凭证只交给 SDK，不写入 localStorage、URL 或日志。

4. 监听连接和数据变化

连接返回后立即注册页面需要的监听。收到 sync 后重新查询当前会话或消息列表， 不要在页面里自己拼一份 IM 数据库。

const stopState = client.on('stateChanged', ({ current }) => {
  console.log('连接状态：', current)
})

const stopSync = client.on('sync', () => {
  conversationStore.reload()
})

const stopError = client.on('error', (error) => {
  console.error(error.code, error.message)
})

5. 发送第一条消息

const conversation = await client.getOrCreateDirectConversation('bob')

const sent = await client.sendText(
  conversation.conversationId,
  '你好，晞晗IM'
)

console.log('服务端消息 ID：', sent.serverMessageId)

让 Bob 使用同一个 Server URL 和 App ID 登录。Bob 收到 sync 后重新查询该会话， 即可看到消息。

6. 在 React 或 Vue 中管理 Client

每个已登录账号只创建一个 XHIMWebClient。把它放在账号级 Service 或 Store， 组件只注册和取消自己的监听。

// 组件卸载
stopState()
stopSync()
stopError()

// 用户真正登出或切换账号
client.disconnect()

关闭一个聊天页面时不要断开整个账号；只有登出或换号时才调用 disconnect()。

7. 常用功能入口

任务	方法
查询消息历史	client.getMessageHistory(...)
标记会话已读	client.markConversationRead(...)
发送业务消息	client.sendCustomMessage(...)
查询在线状态	client.queryPresence(...)
订阅输入状态	client.on('typing', ...)
查询用户资料	client.getUserProfiles(...)
创建群	client.createGroup(...)
取消长查询	传入 AbortSignal

每个公开方法的参数、返回值、错误和 Web 示例见 SDK API Reference。

8. 运行仓库中的 Demo

cd platforms/web/examples/vanilla
npm install
npm run dev

打开两个无痕窗口，分别登录 Alice 和 Bob。先验证文字消息，再继续接群组、媒体、 Presence、Typing 和自定义消息。

9. 常见问题

浏览器提示跨域

把当前网页的精确 Origin 加入服务端允许列表。不要用 * 代替正式域名。

登录成功但收不到新消息

确认页面保留了 sync 监听，并在收到通知后重新查询当前会话。

页面刷新后数据为空

为正式项目配置账号隔离的 XHIMIndexedDBProjectionStore；不要自己解码或改写 SDK 的同步游标。

Web 和 Electron 包能否混用

不能。浏览器使用 @xihansoftware/xhim-web，Electron 使用 @xihansoftware/xhim-electron。