> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lovi.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Widget WebView 集成

> 可嵌入的 Web 包装器，用于注入 Lovi 聊天小部件

## 介绍

Widget WebView 端点是一个交互式 HTML 包装器，允许您将 Lovi 聊天小部件安全地嵌入到网页或移动应用程序中。该端点不返回标准 JSON 响应，而是提供一个包含指向聊天界面的 `iframe` 的完整 HTML 文档。

此包装器充当安全桥梁，在服务器端获取必要的集成元数据（如代理的欢迎消息和语言设置），并使用标准的 `postMessage` 通信将其安全地注入到 Web 视图中。

***

## 🌐 获取 Widget WebView

> **方法**：GET **格式**：HTML

### Endpoint

```
GET https://cloud.lovi.ai/functions/v1/widgetWebView
```

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

### 查询参数

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

| 参数            | 必需 | 描述                                               |
| ------------- | -- | ------------------------------------------------ |
| `customer_id` | 是  | 您公司的 Access Key，用于验证权限。                          |
| `widget_id`   | 是  | 您希望加载的特定频道账户/小部件的 `uuid`。                        |
| `lang`        | 否  | 目标语言代码（例如 `es`、`en`、`pt`）。如果提供，欢迎消息将被翻译。         |
| `showClose`   | 否  | 布尔值字符串（`true` 或 `false`）。默认为 `true`。决定小部件是否可以关闭。 |

### 工作原理

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` 通信。