Widget 接入指南

ServiceGo Widget 是一个 9.3KB (gzip) 的超轻量嵌入式聊天组件，使用 Shadow DOM 隔离，不会与宿主网站的 CSS 产生冲突。

基础接入 (Script 标签)

最简单的接入方式，适用于任何网站：

<script src="https://your-domain.com/widget.iife.js"></script>
<script>
  ServiceGoWidget.init({
    tenantId: 'your-tenant-id',
    apiUrl: 'https://your-api-domain.com'
  });
</script>

配置选项

参数	类型	必填	说明
tenantId	string	是	租户 ID
apiUrl	string	是	API 服务地址
primaryColor	string	否	主题色，默认 #0066ff
lang	string	否	语言：zh / en / ja / ko
position	string	否	位置：bottom-right / bottom-left
userIdentity	object	否	用户身份信息（见下方）

用户身份关联

如果你的网站有登录系统，可以传入用户身份实现跨渠道对话关联：

ServiceGoWidget.init({
  tenantId: 'your-tenant-id',
  apiUrl: 'https://your-api-domain.com',
  userIdentity: {
    externalId: 'user-123',       // 你系统中的用户 ID
    phone: '13800138000',          // 手机号（用于跨渠道匹配）
    displayName: '张三',           // 显示名称
    metadata: {                // 自定义业务数据
      plan: 'premium',
      region: 'CN'
    }
  }
});

React 项目接入

import {useEffect} from 'react';

function App() {
  useEffect(() => {
    const script = document.createElement('script');
    script.src = 'https://your-domain.com/widget.iife.js';
    script.onload = () => {
      window.ServiceGoWidget.init({
        tenantId: 'your-tenant-id',
        apiUrl: 'https://your-api-domain.com'
      });
    };
    document.body.appendChild(script);
  }, []);

  return <div>Your App</div>;
}

Vue 项目接入

<script setup>
import {onMounted} from 'vue';

onMounted(() => {
  const script = document.createElement('script');
  script.src = 'https://your-domain.com/widget.iife.js';
  script.onload = () => {
    window.ServiceGoWidget.init({
      tenantId: 'your-tenant-id',
      apiUrl: 'https://your-api-domain.com'
    });
  };
  document.body.appendChild(script);
});
</script>

技术特性

• Shadow DOM — 完全样式隔离，不影响宿主页面
• 自动重连 — WebSocket 断线后自动指数退避重连（最多 10 次）
• 图片上传 — 支持 JPEG、PNG、GIF、WebP（最大 5MB）
• 流式输出 — SSE 实时展示 AI 回复过程
• CSAT 调查 — 人工转接结束后自动弹出满意度评价