SDK 接入指南

网站端可一行代码接入 JS SDK；小程序与 uni-app 端请通过 web-view 嵌入已集成 SDK 的 H5 页面（需配置业务域名）。下方按场景分别说明。

1
引入 SDK 脚本
2
调用 XmIM.init() 配置参数
3
完成！客服功能自动就绪

方式一：悬浮客服图标

页面右下角显示客服按钮，用户点击后打开聊天窗口

最常用的接入方式，适合电商、SaaS 后台、企业官网等任何页面。用户按需点击，不打扰浏览。

HTML 
<!-- 1. 引入 SDK -->
<script src="https://erp.demo.starmin.cn/sdk/xm-im-sdk.js"></script>

<!-- 2. 初始化 -->
<script>
  XmIM.init({
    server:    'https://erp.demo.starmin.cn/api/admin',
    entryCode: 'YOUR_ENTRY_CODE',  // IM 入口管理中的入口编码（GUID）
    mode:      'fab'   // 悬浮按钮模式
  });
</script>

方式二：主动弹窗问候

页面加载后自动弹出聊天窗口，AI 主动向客户打招呼

适合营销落地页、活动页、促销页面。自动弹出 + AI 问候，提升转化率。可通过 popupDelay 控制弹出延时。

HTML 
<!-- 1. 引入 SDK -->
<script src="https://erp.demo.starmin.cn/sdk/xm-im-sdk.js"></script>

<!-- 2. 初始化 -->
<script>
  XmIM.init({
    server:     'https://erp.demo.starmin.cn/api/admin',
    entryCode:  'YOUR_ENTRY_CODE',
    mode:       'auto-popup',  // 自动弹窗模式
    popupDelay: 3000,          // 3 秒后弹出
    // greeting 可选；未传则使用入口管理后台配置的欢迎语
    greeting:   '欢迎光临！有什么可以帮您的吗？'
  });
</script>

方式三：编程调用

隐藏默认 UI，通过 JS API 手动控制客服窗口的打开/关闭

适合需要深度定制的场景：自定义触发按钮、根据业务逻辑判断是否显示、集成到已有系统等。

HTML 
<!-- 1. 引入 SDK -->
<script src="https://erp.demo.starmin.cn/sdk/xm-im-sdk.js"></script>

<!-- 2. 初始化（隐藏模式，不显示默认 FAB） -->
<script>
  XmIM.init({
    server:    'https://erp.demo.starmin.cn/api/admin',
    entryCode: 'YOUR_ENTRY_CODE',
    mode:      'hidden'   // 隐藏模式
  });
</script>

<!-- 3. 通过自定义按钮触发 -->
<button onclick="XmIM.open()">联系客服</button>

<!-- 也可在 JS 中手动控制 -->
<script>
  // 打开聊天窗口
  XmIM.open();

  // 关闭聊天窗口
  XmIM.close();

  // 销毁实例，清理所有 DOM 和连接
  XmIM.destroy();
</script>
📱

方式四：uni-app / 小程序原生（web-view）

在微信、支付宝等小程序环境中，无法像网页一样直接引入 xm-im-sdk.js，请用内置浏览器打开已接入 SDK 的 H5

思路：先部署或复用一套带 XmIM.init 的 H5 页面（与方式一至三相同），再把该页面的 HTTPS 地址 作为 web-view 的 src。请在各平台后台将 H5 域名加入「业务域名 / 安全域名」白名单，并确保证书有效。

uni-app：在页面中使用 <web-view> 组件，src 指向您的客服 H5（可带查询参数区分入口）。示例：

Vue / uni-app 
<!-- pages/im/webview.vue 片段 -->
<template>
  <web-view :src="imH5Url" />
</template>

<script>
export default {
  data() {
    return {
      // 替换为您的 H5（需已嵌入 XmIM SDK 并完成 init）
      imH5Url: 'https://your-domain.com/im-customer.html?entryCode=YOUR_ENTRY_CODE'
    };
  }
};
</script>

微信小程序原生：在页面 wxml 中放置 web-view，需在小程序管理后台配置「业务域名」。

微信小程序 
<!-- xxx.wxml -->
<web-view src="{{imUrl}}"></web-view>

// xxx.js
Page({
  data: {
    imUrl: 'https://your-domain.com/im-customer.html?entryCode=YOUR_ENTRY_CODE'
  }
});

备选：REST + WebSocket 接口对接（自研会话界面）

若需完全原生 UI、不走 H5，可与官网 JS SDK 使用同一套后端协议：访客登录换取 JWT，经 WebSocket 收发消息；须自行实现消息列表、心跳、断线重连及上传附件等。开发与联调成本通常高于 web-view。

步骤 说明
1. API 根路径 与 XmIM.init({ server }) 相同，形如 https://你的域名/api/admin。本页「在线体验」使用当前站点同源：location.origin + '/api/admin'。
2. 入口信息（可选） GET …/v1/im/public/entry/{entryCode}，公开接口，可查欢迎语等（无需 Bearer）。
3. 访客登录 POST …/v1/im/auth/customer-login，Content-Type: application/json，Body 包含 entryCode、稳定唯一的 openid（建议映射业务用户 id）、platform（如 wechat_mp）、locale 等。成功返回 data.token、data.sessionId。
4. WebSocket 将 API 根的 http/https 改为 ws/wss，路径：/ws/im?token=（token 须 URL 编码）&tokenType=im_customer。uni-app / 微信小程序请使用各端 connectSocket，并配置合法的 WSS 域名。
5. 发消息 连接建立后发送 JSON：{ "type": "message", "data": { "sessionId": 会话ID, "msgType": "text", "content": "用户文本", "mediaUrl": "", "timestamp": 毫秒时间戳 } }。下行 message、ai_typing、ai_error 等与官方 SDK 行为一致；约每 30s 发送 { "type": "heartbeat", "data": {} }。
6. 历史记录 GET …/v1/im/message/customer-history?pageNum=1&pageSize=500&sessionId=…，请求头 Authorization: Bearer {token}；多租户场景按需加 X-Tenant-Id（与登录返回值一致）。
7. 附件（可选） POST …/v1/im/file/upload（multipart/form-data），再经 WebSocket 发送 msgType 为 file 等信息，可参考仓库内 demo-website/public/sdk/xm-im-sdk.js 实现。

字段与路径以部署版本为准；接口升级时请以上述 SDK 源码中的实际请求为准做联调。CORS、证书与网关策略取决于您的环境。

注意项 说明
协议与域名 web-view 仅能以 HTTPS 打开 H5，域名需加入各小程序「业务域名」。纯接口方案还需为 API 与 WSS 配置合法域名与证书。
H5 与 SDK H5 页面内接入方式仍与上文「方式一～三」一致（引入 xm-im-sdk.js 并调用 XmIM.init）。
与 App 共用 同一套 H5 可同时被 uni-app 编译到各端 web-view，减少重复开发与配置。
📖

完整配置项

XmIM.init(options) 支持的全部参数
参数 类型 默认值 说明
server string — API 服务地址（必填），如 https://erp.demo.starmin.cn/api/admin
entryCode string 'default' 客服入口编码（必填，来自 IM 入口管理，保存后自动生成的 GUID）
tenantId string — 租户 ID（可选；不传时由 entryCode 自动解析）
mode string 'fab' 'fab' 悬浮按钮 | 'auto-popup' 自动弹窗 | 'hidden' 隐藏
popupDelay number 3000 auto-popup 模式下弹出延时（毫秒）
greeting string 内置默认 首屏问候语；init 传入则优先于入口管理后台的欢迎语
quickActions array 4 个默认快捷 快捷回复按钮，每项 { icon, label, text }
theme.primary string '#2563eb' 主题色
theme.title string '星敏数字员工' 聊天窗口标题
position string 'right' 'right' 右下角 | 'left' 左下角
zIndex number 99990 组件层级
🔧

JS API

可在任何时候调用这些方法控制客服组件
方法 说明
XmIM.init(options) 初始化 SDK，注入 DOM 和样式，根据 mode 自动启动
XmIM.open() 打开聊天窗口并播放问候动画
XmIM.close() 关闭聊天窗口并断开连接
XmIM.destroy() 销毁实例，移除所有 DOM 元素和事件，释放资源
🎨

进阶示例：自定义主题 + 快捷操作

完全自定义外观和行为
HTML 
<script src="https://erp.demo.starmin.cn/sdk/xm-im-sdk.js"></script>
<script>
  XmIM.init({
    server:    'https://erp.demo.starmin.cn/api/admin',
    entryCode: 'YOUR_ENTRY_CODE',
    mode:      'fab',
    position: 'left',       // 左下角显示
    greeting: 'Hi！需要什么帮助吗？',

    // 自定义主题
    theme: {
      primary: '#2563eb',   // 蓝色主题
      title:   '在线顾问'
    },

    // 自定义快捷操作
    quickActions: [
      { icon: '🛒', label: '购物咨询', text: '我想咨询购物相关问题' },
      { icon: '🔄', label: '退换货',   text: '我想退换货' },
      { icon: '📱', label: '技术支持', text: '我需要技术支持' }
    ]
  });
</script>