> For the complete documentation index, see [llms.txt](https://docs.convai.com/api-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/platform-guides/webgl.md).
# WebGL
Convai Unity SDK 支持语音对话、口型同步、动作、动态上下文、情感、Vision 以及 WebGL 上的长期记忆。浏览器引入了三个在原生平台上不存在的限制：麦克风访问必须使用 HTTPS 源、音频播放或麦克风采集开始前必须有用户手势，以及 Vision 采集路径基于 canvas，而不是 Unity `RenderTexture`。本页涵盖这三项。
### 功能支持
| 功能 | WebGL |
| ---------------------- | --------------------- |
| 语音对话 | ✅ 完整支持 |
| 口型同步 | ✅ 完全支持（请参见故障排除中的已知问题） |
| 动作 | ✅ 完整支持 |
| 动态上下文 | ✅ 完整支持 |
| 情绪 | ✅ 完整支持 |
| 视觉 | ✅ Canvas 捕获（浏览器游戏视图） |
| 长期记忆 | ✅ 完整支持 |
| 空间音频 | ❌ 不支持 |
| 屏幕共享 | ❌ 不支持 |
| 麦克风设备选择 | ❌ 不可用——由浏览器控制设备选择 |
| Unity `AudioSource` 播放 | ❌ 不支持——仅限浏览器音频路径 |
| 麦克风测试 / 预检 | ❌ 不支持 |
### 浏览器要求
{% hint style="danger" %}
**麦克风访问需要 HTTPS。** 浏览器会阻止在非安全源上的麦克风捕获。请通过 HTTPS 提供您的 WebGL 构建版本。唯一的例外是 `localhost`，浏览器会将其视为安全源。部署到 `http://` 会导致浏览器静默拒绝麦克风权限——用户不会看到任何错误提示，语音对话也不会开始。
{% endhint %}
**iframe 嵌入：** 当将您的 WebGL 构建嵌入 iframe 时，父页面必须包含 `allow="microphone"` 在 `
```
**麦克风设备选择：** 浏览器控制所有麦克风设备选择。开始对话时，浏览器会显示自己的权限提示，并允许用户选择麦克风设备。SDK 在 WebGL 上返回空设备列表——设置面板中的麦克风下拉框将不显示任何条目。这是预期行为，不是错误。原生平台上可用的麦克风测试功能在 WebGL 上不受支持。
#### 示例：LMS iframe 嵌入
一家制造公司在其学习管理系统中嵌入了一个安全合规演练。LMS iframe 从 `https://sim.company.com/safety-drill`加载 WebGL 构建版本。Convai 角色扮演现场安全员，测试操作员对场景中危险情境的反应。
**设置：**
1. LMS 页面包含 `allow="microphone"` 该属性位于 `
```
2. WebGL 构建通过 HTTPS 提供。
3. 一个明确的 **开始演练** 按钮放置在场景加载界面上，并连接到 `ConvaiManager.EnableAudioAndStartListening()`.
**结果：** 操作员点击 **开始演练**，在浏览器提示中授予麦克风权限，然后开始口头合规评估。
### 音频手势处理
浏览器要求在允许音频播放或麦克风捕获之前进行用户交互。SDK 通过两种方式处理：
**自动手势检测：** 连接后，SDK 会监听落在 UI 元素外的首次点击或触摸，并调用 `EnableAudioAndStartListening()` on `ConvaiManager` 自动执行。此方式适用于用户直接与 3D 视图交互的场景。
**明确的开始按钮（推荐用于 UI 较多的场景）：** 对于带有全屏覆盖层、加载屏幕或任何在加载时遮挡视图的 UI 的场景，自动检测可能不会可靠触发。添加一个明确的开始按钮，并将其连接到 `ConvaiManager.EnableAudioAndStartListening()`.
自动手势检测和明确的开始按钮并不互斥——两者可以同时启用。当 UI 在加载时遮挡场景时，开始按钮方式更可靠。
{% tabs %}
{% tab title="检查器" %}
1. 添加一个 **按钮** 将组件添加到一个 UI GameObject。
2. 在 **On Click ()** 列表，点击 **+**.
3. 将你的 `ConvaiManager` 将 GameObject 拖入对象字段。
4. 在函数下拉菜单中选择 **ConvaiManager → EnableAudioAndStartListening**.
{% endtab %}
{% tab title="C#" %}
```csharp
using Convai.Runtime.Components;
using UnityEngine;
using UnityEngine.UI;
public class WebGLStartButton : MonoBehaviour
{
[SerializeField] private ConvaiManager _convaiManager;
[SerializeField] private Button _startButton;
private void Start()
{
_startButton.onClick.AddListener(OnStartClicked);
}
private void OnStartClicked()
{
_convaiManager.EnableAudioAndStartListening();
_startButton.gameObject.SetActive(false);
}
}
```
{% endtab %}
{% endtabs %}
#### 示例：企业入职培训
一支企业学习与发展团队在其公司内网上的 `https://training.company.internal/onboarding`部署公司政策培训模拟。Convai 角色扮演人力资源代表，带领新员工了解政策场景。
**设置：**
1. 构建版本通过公司内网服务器以 HTTPS 提供。
2. A **开始对话** 按钮通过上文的 Inspector 方法放置在欢迎界面上。 `ConvaiManager.EnableAudioAndStartListening()` 连接到按钮的 **On Click ()** 事件。
3. 标准 SDK 配置——无需额外的 WebGL 特定步骤。
**结果：** 员工点击 **开始对话** 在欢迎界面上。浏览器会显示麦克风权限提示。授予权限后，Convai 角色开始入职对话。点击按钮后，欢迎界面会自动隐藏。
### WebGL 上的 Vision
在 WebGL 上，Vision 会捕获在浏览器 canvas 中渲染的 Unity 游戏视图。SDK 使用内部的 `WebGLCanvasVideoSource` 将浏览器 canvas 发布为视觉帧源——标准的 `CameraVisionFrameSource` 组件在该平台上不使用。
与原生 Vision 的主要区别：
| 行为 | 原生 | WebGL |
| ------------------ | ----------------------------------------------------- | ---------- |
| 帧源 | `CameraVisionFrameSource` 或 `WebcamVisionFrameSource` | 浏览器 canvas |
| 最大帧率 | 可配置 | 15 fps（固定） |
| 摄像头访问 | 支持 | SDK 中不可用 |
| `RenderTexture` 发布 | 支持 | 不使用 |
WebGL Vision 捕获玩家在浏览器中看到的内容——即游戏视图。对于角色需要通过摄像头看到学习者的物理环境的场景，请使用桌面或移动端构建，并配合 `WebcamVisionFrameSource` 代替。
### 构建验证清单
在发布 WebGL 构建之前，请检查每一项：
* [ ] 构建通过 HTTPS 提供（或在 `localhost`)
* [ ] 如果嵌入在 iframe 中：父页面包含 `allow="microphone"` 在 `