安装小组件

RolChat 小组件是一个浮动按钮，会根据您开启的模块自动调整：聊天、回电请求表单、会议预约、线索表单和知识库搜索都在其中。只需安装一次，显示哪些内容由仪表板决定。

1. 复制代码片段

在 设置 → 小组件 中选择站点并复制安装代码片段。它看起来像这样：

<!-- RolChat widget -->
<script>
  window.rolchatConfig = {
    "site_id": "ste_…",
    "account_id": "…",
    "widget_key": "wk1.<site>.<signature>",
    "modules": ["chat"]
  };
</script>
<script async src="https://widget.rolchat.com/stub.js"></script>

小组件密钥是公开的，可以安全地放在页面中。它标识您的站点并经过签名，因此任何人都无法将小组件的副本指向您的账户。当您更改小组件设置（问候语、标题、主题、工作时间、按视口的布局）时，仪表板会向对象中添加更多键；更改后请重新复制代码片段，或者保持对象精简，让小组件自行获取其余配置。

stub.js 只有几 KB，仅在访客需要时才加载其余部分：首次打开时加载聊天界面，获得同意后加载跟踪，在需要时加载同意横幅。

2. 将其粘贴到 `</body>` 之前

将代码片段添加到每个需要小组件的页面，最好通过网站模板或标签管理器添加，以便一次性在所有页面生效。脚本异步加载，不会阻塞渲染；首次加载的包刻意保持精简，以免影响您的 Core Web Vitals。

3. 检查是否生效

在隐私窗口中打开您的网站。按钮会出现在您选择的角落。在仪表板中，访客会实时显示新的匿名会话，从小组件发送的消息会作为新对话出现在收件箱中。

识别已登录用户

如果访客会登录您的产品，请告诉 RolChat 他们是谁，以便对话关联到正确的联系人：

window.rolchat.identify({
  email: "alice@example.com",
  first_name: "Alice",
  last_name: "Martin",
  phone: "+15551234567",
  external_id: "user_12345",
  custom_fields: { plan: "pro" },
});

接受的属性为 email、phone、first_name、last_name、external_id 以及一个扁平的 custom_fields 对象；其他内容会被忽略。RolChat 会在 CRM 中查找该电子邮件。如果联系人已存在，会话会关联到该联系人，客服可以看到其资料；如果不存在，信息会被保留，并在访客首次发消息时创建线索。

如需更高的可信度，您的后端可以对身份进行签名：将 RolChat 为该用户签发的签名与属性一起传入，只有签名验证通过时会话才会被提升。用户退出登录时请调用 window.rolchat.reset()，否则使用该浏览器的下一个人会看到之前的对话。

JavaScript API

stub 运行后即可使用 window.rolchat；在包加载之前发出的调用会进入队列并按顺序执行。

方法	作用
`show()` / `hide()`	显示或隐藏启动按钮
`open()` / `close()`	打开或关闭聊天面板
`identify(traits)`	将会话关联到某个人（见上文）
`reset()`	清除身份并开始新的匿名会话
`pushEvent(name, props)`	上报自定义事件，用于触发消息和自动化
`trackPageView(path?)`	在单页应用中上报页面浏览
`setLocale(code)`	切换小组件语言
`showConsentPreferences()`	打开同意偏好中心
`on(event, handler)` / `off(event, handler)`	订阅 `chat:opened`、`chat:closed`、`message:sent`、`message:received`、`session:started`

window.rolchat.pushEvent("cart_abandoned", { value: 129.9, currency: "EUR" });
window.rolchat.on("message:received", () => audio.play());

语言和文字方向

小组件使用您在 window.rolchatConfig 中通过 lang 指定的语言（例如 "lang": "de"）；未指定时，使用访客浏览器的语言，按浏览器的偏好顺序，从 RolChat 支持的 40 种语言中选择；都不匹配时使用英语。站点自身的语言设置不会被使用：若要让小组件使用您站点的语言，请设置 lang。阿拉伯语和希伯来语从右到左显示。小组件不会翻译客服的消息；客服端可以改用 AI 实时翻译。

在需要同意横幅的地区，小组件在获得同意前不会跟踪访客。如果您使用 RolChat 隐私模块，横幅和小组件共享同一个同意状态。如果您使用其他同意工具，小组件的分析事件会等待您在 设置 → 隐私 → 嵌入 中配置的信号。

小组件在哪里配置

内容	位置
颜色、位置、问候语、入口、安装代码片段	设置 → 小组件
小组件中显示哪些模块	设置 → 模块（按站点）
工作时间和离线消息	设置 → 站点 → 工作时间
在特定页面显示的触发消息	营销 → 触发器