VisuGuide Chat SDK

在线 Demo

本页已按下方「方式一」加载 SDK，右下角为聊天入口（Demo 默认 siteKey=main）：

OSS 静态资源

SDK 已部署在 VisuGuide 官方 OSS（传输加速），第三方无需自行构建，直接使用以下 URL：

官方基址

https://visuscience.oss-accelerate.aliyuncs.com/visuchatsdk/latest/

文件清单（须保持相对路径）

visuchatsdk/latest/
├── visu-chat.iife.min.js    ← Script 标签接入（推荐）
├── visu-chat.css            ← 必须引入
├── index.mjs                ← Vue / React 等 ESM 接入
└── fonts/
    └── material-symbols-outlined.woff2

路径自动推断（IIFE 模式）

使用 <script src=".../visu-chat.iife.min.js"> 时，SDK 会根据脚本 URL 自动加载同目录下的 visu-chat.css 与 fonts/material-symbols-outlined.woff2， 一般无需设置 assetsBaseUrl。

集成方式

方式一：Script 标签（IIFE）— 推荐

适用于 PHP、Java 模板、WordPress、静态 HTML 等无前端构建的项目。

<!-- 1. 样式 -->
<link rel="stylesheet"
  href="https://visuscience.oss-accelerate.aliyuncs.com/visuchatsdk/latest/visu-chat.css">

<!-- 2. 脚本 -->
<script
  src="https://visuscience.oss-accelerate.aliyuncs.com/visuchatsdk/latest/visu-chat.iife.min.js"></script>

<!-- 3. 初始化 -->
<script>
  var chat = VisuChat.init({
    apiBase: 'https://visuguide.visuscience.com',
    wsBase: 'https://ws.visuguide.visuscience.com',
    siteKey: 'your-site-key',   // 由 VisuGuide 分配
    locale: 'zh-CN',
    title: '在线客服',
  });
</script>

方式二：ES Module

适用于 Vue、React、Next.js、Vite、Webpack 等现代前端项目。

import { init, destroy } from 'https://visuscience.oss-accelerate.aliyuncs.com/visuchatsdk/latest/index.mjs'

const chat = init({
  apiBase: 'https://visuguide.visuscience.com',
  wsBase: 'https://ws.visuguide.visuscience.com',
  siteKey: 'your-site-key',
  locale: 'zh-CN',
  assetsBaseUrl: 'https://visuscience.oss-accelerate.aliyuncs.com/visuchatsdk/latest/',
})

// 组件卸载时
chat.destroy()

方式三：下载到自有 CDN / 服务器

可将 visuchatsdk/latest/ 整个目录下载后部署到您自己的 CDN，替换 URL 即可，目录结构不变。

<link rel="stylesheet" href="https://your-cdn.com/visu-chat/visu-chat.css">
<script src="https://your-cdn.com/visu-chat/visu-chat.iife.min.js"></script>
<script>
  VisuChat.init({
    apiBase: 'https://visuguide.visuscience.com',
    wsBase: 'https://ws.visuguide.visuscience.com',
    siteKey: 'your-site-key',
    assetsBaseUrl: 'https://your-cdn.com/visu-chat/',  // 仅当 JS/CSS 不同目录时需要
  });
</script>

siteKey 说明

siteKey 是 VisuGuide 平台为您分配的接入站点编号， 用于标识当前页面上的 SDK 挂载点。同一接入商若有多个站点（官网、产品页、网店等）， 应使用不同的 siteKey，以便区分来源。

常见取值示例

未传 siteKey 时 SDK 默认 main。生产环境请使用平台为您指定的值，勿自行编造。

全局对象与实例方法

window.VisuChat（IIFE 加载后）

实例方法（init 返回值）

var chat = VisuChat.init({ apiBase: 'https://visuguide.visuscience.com', siteKey: 'your-site-key' });

document.getElementById('help-btn').onclick = function () { chat.open(); };

// 外层站点语言切换时同步挂件（示例）
function onSiteLanguageChange(locale) {
  chat.setLanguage(locale);
}

window.addEventListener('beforeunload', function () { chat.destroy(); });

语言设置（setLanguage）

除 init({ locale }) 设置初始默认语言外，实例方法 setLanguage(locale) 可在运行时切换挂件 UI 与 AI 回复语言，适用于外层网站已有语言切换器的场景。

方法签名

chat.setLanguage(locale: string): void

参数

支持的语言

挂件 UI 与 AI 对话均支持以下 10 种语言（取主语言段，如 zh-CN → zh）：

en · zh · es · fr · de · pt · it · ja · ru · ar

不支持的语言码会被忽略（开发环境控制台会 warn）。

行为说明

• 同步更新挂件 UI 文案（欢迎页、按钮、连接状态、表单标签等）及语言菜单选中态。
• 同步 AI 回复语言：WebSocket 已连接时发送 { type: "set_language" }；尚未连接时会在连上后自动补推。
• 访客仍可在挂件内「语言」菜单手动切换；两种方式均会写入 Session。
• 通过 API 切换时不会在聊天区插入「语言已切换」系统提示（与面板内手动切换不同）。

init({ locale }) 与 setLanguage 的区别

接入示例

var chat = VisuChat.init({
  apiBase: 'https://visuguide.visuscience.com',
  wsBase: 'https://ws.visuguide.visuscience.com',
  siteKey: 'your-site-key',
  locale: 'zh-CN',  // 初始默认
});

// 外层站点语言切换（示例：下拉框、i18n 库回调）
document.getElementById('site-lang').addEventListener('change', function (e) {
  chat.setLanguage(e.target.value);  // 如 'en-US'、'de'、'ja'
});

// Vue / React：在 locale 变化时调用
// watch(locale, (val) => chat.setLanguage(val))

VisuChat.init(options) 参数详解

传入配置对象。第三方接入 VisuGuide 生产环境时，apiBase、siteKey、wsBase 均为必填。

基础参数

wsBase 配置说明

VisuGuide 生产环境 apiBase（visuguide.visuscience.com）经 CDN / DCDN 加速， WebSocket 无法经 CDN 转发，因此必须单独配置 wsBase 指向直连源站的子域名。

界面参数

布局参数

资源路径

panelSize 参数（面板尺寸）

控制聊天面板打开大小、放大尺寸、边界与本地记忆。所有字段可选。

VisuChat.init({
  apiBase: 'https://visuguide.visuscience.com',
  panelSize: {
    openWidthRatio: 0.35,
    openHeightRatio: 0.85,
    minWidthPx: 360,
    minHeightPx: 500,
    maxWidthPx: 600,
    persistLayout: true,
  },
});

打开尺寸

放大尺寸（用户点击放大按钮）

尺寸限制

记忆与存储

尺寸优先级：已保存的用户尺寸 → openWidthPx/openHeightPx → openWidthRatio/openHeightRatio × 视口 → min/max 约束。

nudge 参数（沉默跟进）

AI 回复后访客长时间未发言时，自动推送跟进话术。

VisuChat.init({
  apiBase: 'https://visuguide.visuscience.com',
  nudge: { enabled: false },  // 关闭跟进
});

服务地址与使用限制

聊天、会话、消息等功能均由 SDK 内部自动完成，第三方无需直接调用后端接口。 接入时只需正确配置 apiBase、wsBase 与 siteKey。

服务地址（VisuGuide 生产环境）

使用限制

• siteKey：须使用 VisuGuide 平台分配的编号，与页面域名无关。
• Origin 白名单：您的网站域名须在 VisuGuide 平台登记，否则 API / WebSocket 会被拒绝。
• HTTPS：生产页面须 HTTPS，apiBase / wsBase 也须 HTTPS / WSS。
• wsBase 与 CDN：apiBase 经 CDN / DCDN 时，wsBase 必填且须为未走 CDN 的子域名；仅当 API 直连源站、未加速时方可省略 wsBase。
• 单例：同一页面仅一个挂件实例；重复 init 会销毁前一个。
• 请勿绕过 SDK：鉴权由 SDK 内部处理，不支持第三方自行请求 API。

跨域与安全说明

您的页面域名与 OSS / API 域名不同，属于跨域访问：

常见问题

siteKey 和域名是什么关系？

siteKey 是 VisuGuide 分配的站点编号（如 main、product）， 用于标识 SDK 挂载点。页面域名（如 www.example.com）用于 Origin 白名单， 二者独立：先在平台登记域名，再使用分配的 siteKey 初始化 SDK。

同一域名多个页面怎么区分？

不同挂载点使用不同 siteKey 即可，会话相互隔离。

图标显示为英文文字而非图形？

字体未加载成功。检查 OSS 上 fonts/material-symbols-outlined.woff2 是否可访问，或联系 VisuGuide 确认 OSS CORS 配置。

控制台报 CORS error（API）？

您的站点 Origin 未在后端白名单中。请在 VisuGuide 平台登记域名后重试。

WebSocket 连不上？

VisuGuide 生产环境 apiBase 经 CDN 加速，wsBase 必须配置为 https://ws.visuguide.visuscience.com 等直连源站的子域名，不可与 CDN 加速域名相同。 同时检查 Origin 白名单是否已登记您的站点域名。

launcherSizePx 设置了没变化？

须在 VisuChat.init() 中传入，范围 16–96，修改后需刷新页面。

面板大小/位置异常？

可能受 localStorage 记忆影响。清除键名 visu_chat_widget_layout_v2 或 visu_chat_widget_layout_v2:您的siteKey，或设 panelSize.persistLayout: false。

聊天入口被全屏弹窗遮挡？

调大 zIndex（默认 2147483000）。

多站点共用域名，会话会串吗？

不会。使用不同 siteKey 即可隔离。

SPA 路由切换需要重新 init 吗？

一般不需要。用户登出等场景再调用 chat.destroy()。

外层网站有语言切换，如何同步挂件？

在站点切换语言时调用 chat.setLanguage(locale)，例如 chat.setLanguage('en-US') 或 chat.setLanguage('de')。 详见上方「语言设置」章节。

如何只用代码打开、隐藏默认按钮？

可用 CSS 隐藏 [data-visu-chat-widget]，再通过 chat.open() 程序化打开。

浏览器兼容性

不支持 IE。