🛍️ 客户业务网站 · 集成示例

模拟客户的产品落地页 —— 通过一行 <script> 接入 Leke 客服浮窗。右下角会出现客服图标，打开即可与 echo-bot 对话。

推荐零代码集成：data-* 属性

只需一行 <script>，不用写任何 JS：

<script src="http://localhost:18080/sdk/leke-chat.umd.js" data-site-key="demo-site-key" async></script>

更多可选字段（用户姓名 / 手机 / 邮箱 / 浮窗标题 / 显示语言 / 技能组等）请参考下方的 初始化参数说明，对应表中的 data-* 列。

声明式配置：window.LekeChatConfig

需要传 user.extra 这种复杂结构时：

<script>
  window.LekeChatConfig = {
    siteKey: 'demo-site-key',
    user: {
      externalUserId: 'biz-uid-12345',
      extra: { vipLevel: 'gold' }
    }
  };
</script>
<script src="http://localhost:18080/sdk/leke-chat.umd.js"></script>

配置必须在 SDK 脚本之前定义。data-* 和 LekeChatConfig 可以同时用，data-* 覆盖同名字段。

编程 API：LekeChat.init()

需要动态配置 / 在 SPA 中按需挂载时：

<script src="http://localhost:18080/sdk/leke-chat.umd.js" data-auto-init="false"></script>
<script>
  LekeChat.init({
    siteKey: 'demo-site-key',
    user: { externalUserId: 'biz-uid-12345', username: '张三' },
    title: '在线客服'
  });
</script>

SDK 启动时调用 /v1/visitor/auth 用 siteKey 换 JWT，后续 WebSocket 连接全部带 JWT。user.deviceFp 自动用 localStorage 兜底，实现回访客户归并。

实测链路

页面加载 → SDK fetch /v1/visitor/auth {siteKey, user}
biz-api 校验 siteKey + 域名白名单 → 合并 customer → 签发 JWT
SDK 用 ?token=<JWT> 连 im-gateway WebSocket
im-gateway 验签 → 提取 tenantId / customerId → 注册到 hub
发消息 → NATS → persist-worker 落库 → echo-agent 回复 → 浮窗显示

初始化参数说明

以下字段同时支持三种传入方式：data-* 属性（推荐）/ window.LekeChatConfig / LekeChat.init()。

JS 字段	data-* 属性	必填	说明
`siteKey`	`data-site-key`	是	客户 SDK Key
`user.externalUserId`	`data-external-user-id`	否	您系统中的用户 ID，跨设备合并时建议传
`user.username`	`data-username`	否	用户姓名
`user.phone`	`data-phone`	否	手机号
`user.email`	`data-email`	否	邮箱
`user.extra`	—	否	自定义键值对，仅 LekeChatConfig / init() 支持
`title`	`data-title`	否	浮窗标题
`locale`	`data-locale`	否	zh-CN / zh-TW / en / id / ms
`skillGroupId`	`data-skill-group-id`	否	指定技能组；留空走客户默认
（控制）	`data-auto-init="false"`	否	禁用自动 init，需自行调 LekeChat.init() 时使用

产物大小

leke-chat.umd.js: ~14 KB （gzip ~5 KB）
leke-chat.mjs: ~18 KB （gzip ~6 KB）
leke-chat.d.ts: TypeScript 类型

↘ 右下角是真实加载的客服浮窗（来自 /sdk/leke-chat.umd.js）