sia-chat-sdk

在宿主页面接入网关代理平台智能会话的 Web SDK。提供悬浮球 / 侧边面板 / 嵌入 iframe，以及鉴权、主题同步等能力。

依赖 sia-chat-protocol（安装本包时自动拉取）。

安装

npm

npm i sia-chat-sdk

CDN

可通过 jsDelivr 等 CDN 引用 npm 包内文件，例如：

<script src="https://cdn.jsdelivr.net/npm/sia-chat-sdk@latest/umd/sia-chat-widget.min.js"></script>

也可将 @latest 换成具体版本号，或将同文件上传至自有 CDN。引入后使用全局对象 SiaChat。

用法

npm

import { siaChat } from 'sia-chat-sdk'

await siaChat.init({
  base: {
    platform: 'your-platform',
    // iframeUrl: 'https://your-gateway-host/#/embed/chat', // 可选
  },
  auth: {
    token: 'YOUR_HOST_JWT',
  },
  ui: {
    theme: 'light',
    launcher: { show: true, right: 24, bottom: 24 },
    handle: { show: true },
    panel: { width: 380, height: '100vh' },
  },
  // user: { id: '10001', name: '张三' }, // 可选
})

const offExpired = siaChat.on('tokenExpired', ({ reason, code }) => {
  console.warn('token expired', reason, code)
  // await siaChat.setToken(await refreshJwt())
})

const offError = siaChat.on('error', ({ reason, message, error }) => {
  console.error('sia chat error', reason, message, error)
})
// 页面卸载时：offExpired(); offError()

CDN

<script src="https://cdn.jsdelivr.net/npm/sia-chat-sdk@latest/umd/sia-chat-widget.min.js"></script>
<script>
  SiaChat.init({
    base: { platform: 'your-platform' },
    auth: { token: 'YOUR_HOST_JWT' },
    ui: {
      theme: 'light',
      launcher: { show: true, right: 24, bottom: 24 },
      panel: { width: 380, height: '100vh' },
    },
  })

  SiaChat.on('tokenExpired', function (payload) {
    console.warn('token expired', payload)
  })

  SiaChat.on('error', function (payload) {
    console.error('sia chat error', payload.reason, payload.message)
  })
</script>

勿反复调用 init；运行期请使用下方 API 更新状态。

init 配置字段

| 参数 | 类型 | 是否必选项 | 示例 | 说明 | |------|------|------------|------|------| | base.platform | string | 否 | 'cxt' | 业务平台标识，随鉴权传给嵌入页 | | base.iframeUrl | string | 否 | 'https://host/#/embed/chat' | 嵌入页地址；不传则使用 SDK 内置默认（若已配置） | | auth.token | string | 是 | 'eyJhbGciOi...' | 网关代理平台登录返回的 JWT，勿写入 iframe URL | | ui.theme | 'light' \| 'dark' | 否 | 'dark' | 主题，建议与宿主页面同步 | | ui.launcher.show | boolean | 否 | true | 是否显示悬浮球；面板打开时仍保留（可被面板遮住）。为 false 时用 open / close | | ui.launcher.right | number | 否 | 24 | 悬浮球距右边距（px）；有 localStorage 记录时优先恢复 | | ui.launcher.bottom | number | 否 | 24 | 悬浮球距下边距（px）；有 localStorage 记录时优先恢复 | | ui.launcher.draggable | boolean | 否 | true | 悬浮球是否可拖拽，位置写入 localStorage | | ui.handle.show | boolean | 否 | true | 面板打开时是否显示左侧收起把手 | | ui.panel.width | number \| string | 否 | 380 | 面板宽度；有 localStorage 记录时优先恢复 | | ui.panel.height | number \| string | 否 | '100vh' | 面板高度 | | ui.panel.resizable | boolean | 否 | true | 是否允许左缘拖拽调宽，宽度写入 localStorage | | ui.panel.minWidth | number | 否 | 380 | 拖拽宽度下限（px） | | ui.panel.maxWidth | number | 否 | 680 | 拖拽宽度上限（px，且不超过 90vw） | | user.id | string | 否 | '10001' | 可选用户标识 | | user.name | string | 否 | '张三' | 可选用户名称 |

API

| API | 示例 | 说明 | |-----|------|------| | siaChat.version | siaChat.version | 当前 SDK 版本号 | | siaChat.init | await siaChat.init({ ... }) | 初始化并挂载 Widget；全局只应成功初始化一次 | | siaChat.update | await siaChat.update({ ui: { theme: 'dark' } }) | 批量更新，参数结构与 init 相同，按需传字段 | | siaChat.setToken | await siaChat.setToken(token) | 更新 JWT；与最近一次失效票相同则忽略（防 tokenExpired 回灌同一票） | | siaChat.setTheme | await siaChat.setTheme('dark') | 更新主题：'light' \| 'dark' | | siaChat.setUser | await siaChat.setUser({ id, name }) | 更新用户信息 | | siaChat.getConfig | siaChat.getConfig() | 返回当前生效配置的深拷贝（含 opened、拖拽后的宽高/位置等；auth.token 脱敏为前 5 + 10 个 * + 后 5，总长 ≤ 10 则为 10 个 *） | | siaChat.open | siaChat.open() | 打开会话面板 | | siaChat.close | siaChat.close() | 收起会话面板 | | siaChat.destroy | siaChat.destroy() | 销毁 Widget 与通信桥 | | siaChat.on | const off = siaChat.on('tokenExpired', fn) | 监听事件；返回取消监听函数 |

CDN 全局对象为 SiaChat（UMD；方法与上表相同）。

事件

| 事件 | 示例 | 说明 | |------|------|------| | ready | siaChat.on('ready', () => {}) | 嵌入页就绪 | | openUrl | siaChat.on('openUrl', ({ url, target }) => {}) | 嵌入页请求打开链接（SDK 默认会 window.open） | | tokenExpired | siaChat.on('tokenExpired', ({ reason, code }) => {}) | JWT 失效；SDK 对外约 10 秒内最多通知一次（协议日志仍可能连发）。收到后请换新票再 setToken；回灌同一张失效票会被 SDK 忽略 | | error | siaChat.on('error', ({ reason, message, error }) => {}) | 嵌入加载/握手失败（见下方） |

error 事件

iframeUrl 非法、嵌入页迟迟不发 ready、或 init 握手超时等场景会触发。此时：

• 等待 ready / 握手期间，面板内会显示 loading（转圈 +「正在连接对话服务…」）
• 失败后悬浮球与面板仍可打开，面板内展示错误说明与「重试」
• init() / update() 的 Promise 仍会 reject（便于宿主 try/catch）
• 点击「重试」会按当前配置重新加载 iframe 并握手（不重建 SDK 实例）

| 字段 | 类型 | 说明 | |------|------|------| | reason | 'invalid_url' \| 'ready_timeout' \| 'init_failed' \| 'unknown' | 错误分类 | | message | string | 面向用户的简短说明（与面板文案一致） | | error | unknown | 原始错误，便于排查 |

| reason | 含义 | |----------|------| | invalid_url | base.iframeUrl 无法解析为合法 URL | | ready_timeout | 等待嵌入页 control.ready 超时（默认 60s） | | init_failed | 其它握手/初始化超时或桥接在 ready 前被销毁 | | unknown | 未归类的加载失败 |