Skip to main content

​
介绍

Widget WebView 端点是一个交互式 HTML 包装器，允许您将 Lovi 聊天小部件安全地嵌入到网页或移动应用程序中。该端点不返回标准 JSON 响应，而是提供一个包含指向聊天界面的 iframe 的完整 HTML 文档。 此包装器充当安全桥梁，在服务器端获取必要的集成元数据（如代理的欢迎消息和语言设置），并使用标准的 postMessage 通信将其安全地注入到 Web 视图中。

​
🌐 获取 Widget WebView

方法：GET 格式：HTML

​
Endpoint

替代路径格式： GET https://cloud.lovi.ai/functions/v1/widgetWebView/{customer_id}/{widget_id}

​
查询参数

如果您不使用上述路径结构，则必须在查询字符串中传递必需参数。

​
工作原理

  1. 身份验证：服务器验证 customer_id（Access Key）并验证 widget_id 的所有权。
  2. 元数据获取：检索小部件配置，并可选地查询 Lovi 翻译后端将代理的欢迎消息翻译成请求的 lang。
  3. HTML 交付：服务器返回包含 <iframe src="https://widget.lovi.ai/?cw_id=..."> 的 HTML 页面。
  4. PostMessage 桥接：加载的 HTML 包含监听 iframe 触发的 get_widget 和 get_customer 事件的 JavaScript。它安全地使用小部件配置 (widgetData) 响应，并处理本地存储（例如生成唯一用户 ID）。

​
常见错误

如果小部件加载失败，您可能会收到以下 HTTP 状态代码之一，而不是 HTML 负载：
  • 400 Bad Request：缺少 customer_id 或 widget_id，或 widget_id 不是有效的 UUID。
  • 403 Forbidden：无效的 customer_id（Access Key 验证失败）。
  • 404 Not Found：找不到公司或指定的小部件。
  • 500 Internal Server Error：生成包装器时发生意外错误。
🧭 重要：如果小部件卡在“Loading Widget…”屏幕上，请检查浏览器控制台。确保您的环境允许跨源 iframe 并且不阻止 WebView 与 widget.lovi.ai 之间的 postMessage 通信。