微信 / 通用小程序接入

本页先帮你在微信小程序中连接 XHIM，并发送第一条文字消息。 支付宝、抖音等小程序的接入思路相同，区别只在平台提供的网络和存储 API。

完成本页后

你将完成以下流程：

准备 Server URL 和测试账号
  → 配置小程序合法域名
  → 安装 SDK
  → 获取当前用户的 IM 凭证
  → 连接并监听消息变化
  → 向测试用户发送文字消息

第一次接入只需阅读第 1～7 节。自定义 Adapter 和发布边界放在后面， 不会阻断基础收发消息。

1. 接入前准备

向服务端或业务后台负责人获取：

内容	示例	用途
XHIM Server URL	https://im.example.com	SDK 连接的服务地址
App ID	customer-app	区分客户或业务空间
当前用户 ID	alice	已登录的业务账号
对端用户 ID	bob	用于验证首条消息

小程序不使用管理员密码、Business Key 或数据库密码。当前用户登录 业务系统后，由业务后台返回这个用户的短期 XHIM 凭证。

2. 配置合法域名

在微信公众平台的“开发管理 → 开发设置 → 服务器域名”中配置：

• request 合法域名：XHIM Server 的 HTTPS 域名；
• socket 合法域名：Server 公开配置中返回的 WSS 域名；
• 业务后台域名：获取当前用户 IM 凭证的 HTTPS 地址。

正式环境必须使用 HTTPS/WSS。开发者工具的“不校验合法域名”只能用于 本地调试，不能作为上线配置。

3. 安装 SDK

npm install @xihansoftware/xhim-mini-program

在微信开发者工具中开启“使用 npm 模块”，然后执行“工具 → 构建 npm”。 业务代码只需导入小程序包，并使用对应平台的 adapter。

4. 获取当前用户的 IM 凭证

credentialProvider 是一个普通异步函数。SDK 首次登录或凭证即将过期时 会调用它。下面示例使用小程序已有的业务登录态请求业务后台：

type XHIMCredential = {
  accessToken: string
  expiresAtMs: number
}

function fetchXHIMCredential(): Promise<XHIMCredential> {
  return new Promise((resolve, reject) => {
    wx.request({
      url: 'https://api.example.com/im/credential',
      method: 'POST',
      header: {
        Authorization: `Bearer ${getApp().globalData.sessionToken}`
      },
      success: ({ statusCode, data }) => {
        const value = data as Partial<XHIMCredential>
        if (
          statusCode >= 200 &&
          statusCode < 300 &&
          typeof value.accessToken === 'string' &&
          typeof value.expiresAtMs === 'number'
        ) {
          resolve({
            accessToken: value.accessToken,
            expiresAtMs: value.expiresAtMs
          })
          return
        }
        reject(new Error('无法获取 IM 登录凭证'))
      },
      fail: reject
    })
  })
}

不要把 accessToken 写入 Storage、页面路由或日志。刷新凭证仍调用同一个函数。

5. 连接并监听变化

import {
  XHIMMiniProgramClient,
  createXHIMWeChatMiniProgramAdapter
} from '@xihansoftware/xhim-mini-program'

const currentUserId = 'alice'

const client = await XHIMMiniProgramClient.connect({
  server: 'https://im.example.com',
  appId: 'customer-app',
  accountHint: currentUserId,
  credentialProvider: fetchXHIMCredential,
  adapter: createXHIMWeChatMiniProgramAdapter(wx),
  storageNamespace: `xhim:${currentUserId}`
})

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

const stopSyncListener = client.on('sync', () => {
  // 收到变化后重新查询当前会话或消息列表。
  void chatStore.reloadVisibleConversation()
})

Client 应由 App 级账号 Store 持有，不要在每个 Page 中重复创建。 storageNamespace 必须包含当前账号，避免切换账号后读到上一个用户的数据。

6. 发送第一条消息

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

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

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

对端收到消息后，sync 监听会通知当前账号有数据变化。页面应重新查询 会话或消息，不要把事件内容当成另一份聊天记录。

7. 页面退出、登出与换号

• 普通页面退出：取消该页面注册的监听，不关闭账号 Client；
• 当前账号登出：先调用 stopStateListener() 和 stopSyncListener()，再调用 client.disconnect()；
• 切换账号：关闭旧 Client，然后使用新的 currentUserId 和 storageNamespace 创建新 Client。

小程序进入后台时不需要每次登出。断网恢复和短时前后台切换由 SDK 处理。

8. 支付宝、抖音等小程序

微信小程序可直接使用 createXHIMWeChatMiniProgramAdapter(wx)。其他小程序 需要将平台提供的下列 API 映射到 XHIMMiniProgramAdapter：

XHIM 能力	平台侧常见 API
HTTPS 请求	request
WebSocket 连接	connectSocket
读取本地数据	getStorage
保存本地数据	setStorage
删除本地数据	removeStorage

Adapter 只负责调用平台 API。登录、重连、消息同步和游标都由 SDK 处理， 不要在 Adapter 中重新实现一遍。

9. 常见问题

连接失败或 WebSocket 立即关闭

确认 HTTPS 和 WSS 域名都已加入小程序合法域名，并且真机可以访问该域名。

重启后看不到之前的会话

确认 storageNamespace 稳定且包含当前账号。不要使用随机值，也不要让两个 账号共用同一个命名空间。

开发者工具可以运行，真机不可以

开发者工具可能跳过域名和 TLS 校验。真机联调时需要使用正式 HTTPS/WSS 证书，并在小程序后台配置完整域名。

收到消息但页面没有刷新

确认账号 Store 只创建一个 Client，并且页面正在处理 sync 通知后重新查询。

10. 上线前检查

• 使用固定版本 SDK，不在发布时自动漂移依赖；
• 使用 HTTPS/WSS，并完成真机合法域名验收；
• 验证首次登录、凭证刷新、断网重连、前后台和切换账号；
• 验证 Storage 配额，并确认账号数据互相隔离；
• 确认代码和日志中不包含 Admin Key、Business Key 或长期凭证。

需要自定义账号 Store、消息 Renderer 或项目分层时，再阅读 客户端二次开发指南。