Skip to main content

​
免登录窗口接入指南

​
概述

LangChat 支持通过免登录方式将 Agent/Workflow 发布为独立的聊天界面，无需用户登录即可直接对话。提供三种接入方式：
  • 分享页：独立的网页链接，可直接分享给用户
  • iframe 嵌入：将聊天界面嵌入到现有网页中
  • 悬浮小组件：在任意网页右下角显示悬浮聊天按钮

​
1. 分享页 (Share Page)

分享页是 LangChat 提供的独立聊天页面，支持响应式设计，适配桌面端和移动端。

​
URL 格式

https://your-domain.com/share/{API_KEY}

​
布局特点

  • 桌面端：左侧会话历史列表，右侧聊天面板，支持手动收起/展开侧边栏
  • 移动端：侧边栏默认隐藏，顶部显示机器人信息及折叠按钮

​
使用方式

  1. 在 LangChat 后台创建「免登录窗口」类型的 API Key
  2. 复制生成的分享链接
  3. 将链接发送给用户或嵌入到其他系统中

​
2. iframe 嵌入

将聊天界面以 iframe 方式嵌入到现有网页中。

​
代码示例

<iframe
  src="https://your-domain.com/share/{API_KEY}"
  style="width: 100%; height: 100%; min-height: 600px;"
  frameborder="0"
  allow="*"
></iframe>

​
参数说明

属性说明
src分享页地址
widthiframe 宽度，建议 100% 或固定像素值
heightiframe 高度，建议至少 600px
frameborder设为 0 隐藏边框

​
响应式适配

<div style="width: 100%; height: 80vh; max-width: 800px; margin: 0 auto;">
  <iframe
    src="https://your-domain.com/share/{API_KEY}"
    style="width: 100%; height: 100%; border: none; border-radius: 12px;"
    allow="*"
  ></iframe>
</div>

​
3. 悬浮小组件 (Floating Widget)

通过引入一个轻量级脚本，在任意网页右下角显示悬浮聊天按钮。

​
引入方式

在 HTML 的 <head> 或 <body> 末尾添加以下代码： 
<script
  id="chatbot-iframe"
  src="https://your-domain.com/js/iframe.js"
  data-bot-src="https://your-domain.com/share/{API_KEY}"
  data-drag="true"
  data-button-size="60"
  data-default-open="false"
  defer
></script>

​
配置项 (data attributes)

属性必填默认值说明
id是chatbot-iframe必须固定为此 ID，脚本通过它读取配置
src是-指向 LangChat 部署目录下的 js/iframe.js
data-bot-src是-机器人分享页地址
data-drag否false是否允许拖拽按钮位置
data-button-size否60悬浮按钮大小（单位：px）
data-default-open否false页面加载后是否自动弹出聊天窗
data-open-icon否Logo按钮未展开时的图标（URL 地址）
data-close-icon否-按钮展开后的关闭图标（URL 地址）

​
完整示例

<!DOCTYPE html>
<html>
<head>
  <meta charset="UTF-8">
  <title>我的网站</title>
</head>
<body>
  <h1>欢迎访问</h1>
  <p>这是网站内容...</p>

  <!-- LangChat 聊天小组件 -->
  <script
    id="chatbot-iframe"
    src="https://chat.example.com/js/iframe.js"
    data-bot-src="https://chat.example.com/share/lc-xxxx"
    data-drag="true"
    data-button-size="60"
    data-default-open="false"
    defer
  ></script>
</body>
</html>

​
自定义按钮图标

<script
  id="chatbot-iframe"
  src="https://your-domain.com/js/iframe.js"
  data-bot-src="https://your-domain.com/share/{API_KEY}"
  data-open-icon="https://example.com/chat-icon.png"
  data-close-icon="https://example.com/close-icon.png"
  defer
></script>

​
嵌入模式优化 (Embed Mode)

当通过 iframe.js 加载时，URL 会自动带上 ?embed=true 参数，触发以下布局优化：
  • 移除外边距：去掉主界面的 padding 和外层圆角 border
  • 紧凑布局：自动隐藏不必要的空白区域，适配小窗口
  • 智能定位：弹窗根据按钮位置自动计算弹出方向，确保不超出屏幕
  • 边界约束：开启拖拽后，按钮被限制在距屏幕边缘 10px 的安全范围内

​
配置说明

在 LangChat 管理后台的「接入渠道」页面：
  1. 选择「免登录窗口」标签
  2. 点击「新增链接/秘钥」
  3. 填写配置信息：
配置项必填说明
渠道名称是自定义标识名称
限流 (QPM)是每分钟最大请求次数
过期时间是链接的有效期
开启历史记录否是否保存用户对话历史
  1. 创建成功后，点击「获取应用访问链接」按钮
  2. 选择接入方式（分享页/iframe/小组件）并复制对应代码

​
域名配置

​
开发环境

前端 .env 文件中的 VITE_GLOB_FRONT_URL 配置会影响生成的链接地址： 
# .env.development
VITE_GLOB_FRONT_URL=http://localhost:5888

​
生产环境

# .env.production
VITE_GLOB_FRONT_URL=https://your-domain.com
重要：生产环境必须将地址修改为公网可访问的域名或 IP

​
跨域配置

如果遇到跨域问题，确保服务端已配置 CORS： 
# application.yml
cors:
  allowed-origins:
    - "https://your-frontend-domain.com"
  allowed-methods:
    - GET
    - POST
    - OPTIONS

​
安全建议

  1. 设置过期时间：为链接设置合理的过期时间
  2. 限流配置：根据预期流量设置 QPM 限制
  3. 域名白名单：生产环境建议配置允许嵌入的域名白名单
  4. HTTPS：生产环境使用 HTTPS 协议

​
常见问题

​
Q: 小组件在某些网站上显示异常？

检查目标网站是否有 CSP（内容安全策略）限制，可能需要在 CSP 中添加 LangChat 域名。

​
Q: iframe 高度不够？

设置足够的高度值，建议至少 600px 或使用 vh 单位： 
<iframe style="height: 80vh;" ...></iframe>

​
Q: 移动端体验不佳？

使用分享页模式，它已针对移动端进行了优化。

​
相关文档