更新记录

1.0.0（2026-04-16） 下载此版本

v1.0.0（首次上架） 支持用户、智能客服、服务人员、门店客服四方多方聊天 实现基础 IM 通讯：文字消息、消息发送 / 接收、未读提示 支持会话创建、会话列表、消息历史记录 支持客服在线状态显示 支持消息实时推送与多端同步 优化消息传输稳定性，支持高并发场景 适配主流后台管理系统与前端框架

平台兼容性

uni-app(3.8.1)

其他

JSZN IM SDK

jszn-im-sdk 是一个基于 uni-app 的 IM 插件，面向第三方业务系统提供 可复用的会话与聊天能力。

本文档面向接入方开发者，描述 SDK 的能力边界、接入步骤、配置模型和 API。

1. 能力概览

• 支持角色：user（用户端）、staff（员工端）

• 支持会话：会话列表、会话直达、平台客服会话

• 支持消息：文本、图片、位置、已读回执

• 传输层：WebSocket 长连接，内置心跳与重连

• 适配平台：微信小程序、H5、App（Vue）

• 后台管理案例： https://admin.im.orchiport.asia/ 账号密码: admin admin123

• webSDK案例： https://websdk.im.orchiport.asia/

• wenSDK下载地址: 平台客服：pnpm add @zjw-jszn/platform-imsdk 门店客服：pnpm add @zjw-jszn/store-imsdk

2. 安装

2.1 方式一（推荐）

通过 HBuilderX 插件市场导入 jszn-im-sdk。

2.2 方式二

手动将插件目录复制到项目 uni_modules/ 目录。

2.3 安装三方依赖（必须）

SDK 使用 ts-md5 参与签名计算。
请在接入项目根目录安装依赖（不是在 uni_modules/jszn-im-sdk 子目录）：

pnpm add ts-md5@^2.0.1

说明：uni-app 的 npm 解析要求 node_modules 位于项目根目录，若未在根目录安装，会出现：

文件查找失败：'ts-md5' at uni_modules/jszn-im-sdk/core/transport/request.js

3. 接入前提

SDK 依赖业务后端提供以下能力（按角色前缀路由）：

• 鉴权：/{rolePrefix}/authorization/getAuthorization
• 会话列表：/{rolePrefix}/chat/getList
• 历史消息（session）：/{rolePrefix}/chat/getChatListBySession
• 历史消息（平台客服）：/{rolePrefix}/chat/getChatListByCustomer
• 用户信息：/{rolePrefix}/user/getUserInfo
• 会话用户信息：/{rolePrefix}/user/getUserInfoBySessionId
• 未读总数：/{rolePrefix}/chat/getUnReadCount (仅 staff 角色支持)

其中：

• user 角色的 rolePrefix 为 /user/IM
• staff 角色的 rolePrefix 为 /staff/IM

4. 快速开始

4.1 注册页面路由

在 pages.json 中注册 SDK 页面：

{
  "pages": [
    {
      "path": "uni_modules/jszn-im-sdk/page/index",
      "style": {
        "navigationStyle": "custom",
        "backgroundColor": "#f7f8fa"
      }
    }
  ]
}

4.2 创建 SDK 实例

import { createStaffIMSDK, createUserIMSDK } from '@/uni_modules/jszn-im-sdk/index'

const imConfig = {
  api: {
    baseURL: 'https://your-api.com',
    resourceBaseURL: 'https://your-resource.com',
    uploadURL: 'https://your-resource.com/system/uploadImage',
    signKey: 'your-sign-key',
    suffix: '43cf28',
    groupId: '6',
    siteId: '6'
  },
  websocket: {
    url: 'wss://your-api.com',
    reconnectInterval: 3000,
    heartbeatInterval: 3000,
    maxReconnectAttempts: 5
  },
  chat: {
    platformServicePhone: '***'
  }
}

const userSDK = createUserIMSDK(imConfig)
const staffSDK = createStaffIMSDK(imConfig)

补充：若仅配置 api.baseURL，未显式配置 websocket.url，SDK 会自动从 api.baseURL 推导 WS 地址（https -> wss，http -> ws，仅保留域名部分）。

4.3 鉴权并进入页面

await userSDK.ensureRoleAuthorized({
  phone: '***',
  username: '张三',
  avatar: 'https://example.com/avatar-user.png'
})

uni.navigateTo({
  url: '/uni_modules/jszn-im-sdk/page/index?role=user'
})

后门：仅做“进入页面前快速校验”时，可不重复传登录载荷：

await userSDK.ensureRoleAuthorized(null, { forceRefresh: false })

4.4 状态订阅 (NEW)

SDK 内部维护了一个微型状态机，支持多平台响应式同步。

const off = sdk.subscribeState((state) => {
  console.log('未读总数：', state.totalUnread)
  console.log('身份状态：', state.authStatus) // unauthorized | authorized | loading
  console.log('默认头像：', state.defaultAvatar)
})

// 销毁时取消订阅
off()

5. 传输层可靠性

SDK 对物理链路做了深度优化，接入方无需关注底层细节：

• 并发连接锁：防止页面高频切换或组件重复挂载导致的并发 WS 握手冲突。
• 指数退避重连：断线后以 3s, 6s, 12s... 频率自动重连，最大间隔 30s。
• 动态身份验证：连接握手前自动核对 Token 及时效性，防止身份错乱。

SDK 页面路由：/uni_modules/jszn-im-sdk/page/index

支持参数：

• session_id：按会话 ID 直达
• phone：按目标手机号直达
• friend_type：目标类型
• customeronly=1：平台客服会话模式
• role：建议始终传递；当应用同时持有 user/staff 两个 SDK 实例时为必传

示例：

uni.navigateTo({
  url: '/uni_modules/jszn-im-sdk/page/index?role=user&session_id=xxx'
})

uni.navigateTo({
  url: '/uni_modules/jszn-im-sdk/page/index?role=user&phone=***&friend_type=1'
})

uni.navigateTo({
  url: '/uni_modules/jszn-im-sdk/page/index?role=user&friend_type=4&customeronly=1'
})

6. 字段语义约定

phone 在接入中有两种语义，必须区分：

• 鉴权 phone：当前登录用户手机号（传给 ensureRoleAuthorized）
• 会话 phone：目标会话手机号（拼接在路由参数中）

7. 关键接入约束

• SDK 页面内会话列表会自动拉取 chat/getList
• 进入 SDK 页面前，不应再手动调用一次 session.getSessionList()
• staff 鉴权必须提供 site（可来自 api.siteId）
• SDK 页面不再支持 authphone/authname/authavatar/authsite 路由鉴权
• 同角色重复 navigateTo 会创建新的页面实例；日志出现“复用注入 SDK 实例”属于正常行为
• WebSocket 仅在“未连接”或“连接身份不匹配”时主动发起连接；断线后由 SDK 自动重连
• 历史消息拉取优先 session_id（getChatListBySession），无 session_id 且为平台客服模式时才走 getChatListByCustomer

8. 开发文档

• 配置说明
• API 参考
• Vue2 接入
• Vue3 接入
• 集成示例组件

9. 目录结构

jszn-im-sdk/
├── components/
│   ├── chat-header.vue
│   ├── session-list.vue
│   ├── chat-input-bar.vue
│   ├── emoji-panel.vue
│   └── chat-room.vue
├── core/
│   ├── config/
│   │   ├── index.js
│   │   └── resolver.js
│   ├── tools/
│   │   ├── error.js
│   │   ├── logger.js
│   │   ├── storage.js
│   │   └── helpers.js
│   ├── transport/
│   │   ├── request.js
│   │   └── ws/
│   │       ├── client.js
│   │       └── event.js
│   ├── services/
│   │   ├── auth.js
│   │   ├── message.js
│   │   └── session.js
│   └── im-sdk.js
├── index.js
├── page/
│   └── index.vue
└── docs/

10. 联系我们

开源不易，维护与迭代需要持续投入。 如果此项目对你有帮助，欢迎赞赏支持，你的鼓励是我持续更新的动力！

11. License

MIT