> 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 支持 WebGL 上的语音对话、口型同步、动作、动态上下文、情感、视觉和长期记忆。浏览器引入了三个在原生平台上不存在的限制：麦克风访问必须使用 HTTPS 来源、音频播放或麦克风捕获开始前必须先进行用户手势操作，以及基于画布的视觉捕获路径，而不是 Unity `RenderTexture`. 这三项都在本页中有所说明。

{% embed url="<https://youtu.be/SbQ-Kfi7yg4>" %}
由 Convai 驱动的 Unity 6 Web 项目（以前称为 WebGL 构建）
{% endembed %}

### 功能支持

| 功能                     | WebGL               |
| ---------------------- | ------------------- |
| 语音对话                   | ✅ 完整                |
| 口型同步                   | ✅ 完整（请参见故障排除中的已知问题） |
| 动作                     | ✅ 完整                |
| 动态上下文                  | ✅ 完整                |
| 情感                     | ✅ 完整                |
| 视觉                     | ✅ 画布捕获（浏览器游戏视图）     |
| 长期记忆                   | ✅ 完整                |
| 空间音频                   | ❌ 不支持               |
| 屏幕共享                   | ❌ 不支持               |
| 麦克风设备选择                | ❌ 不可用 — 设备选择由浏览器控制  |
| Unity `AudioSource` 播放 | ❌ 不支持 — 仅支持浏览器音频路径  |
| 麦克风测试 / 预检查            | ❌ 不支持               |

### 浏览器要求

{% hint style="danger" %}
**访问麦克风需要 HTTPS。** 浏览器会阻止在非安全来源上进行麦克风捕获。请通过 HTTPS 提供你的 WebGL 构建。唯一的例外是 `localhost`，浏览器会将其视为安全来源。部署到 `http://` 会导致浏览器静默拒绝麦克风权限——用户不会看到任何错误，语音对话也不会启动。
{% endhint %}

**iframe 嵌入：** 当将你的 WebGL 构建嵌入到 iframe 中时，父页面必须在 `allow="microphone"` 添加到 `<iframe>` 元素上。否则，无论 HTTPS 状态如何，浏览器都会阻止麦克风访问。

```html
<iframe src="https://your-host.com/build/" allow="microphone" width="960" height="600"></iframe>
```

**麦克风设备选择：** 浏览器控制所有麦克风设备的选择。对话开始时，浏览器会显示自己的权限提示，并允许用户选择麦克风设备。SDK 在 WebGL 上返回空设备列表——设置面板中的麦克风下拉菜单不会显示任何条目。这是预期行为，不是错误。原生平台上可用的麦克风测试功能在 WebGL 上不受支持。

#### 示例：LMS iframe 嵌入

某制造公司在其学习管理系统中嵌入了一个安全合规演练。LMS iframe 从 `https://sim.company.com/safety-drill`加载 WebGL 构建。Convai 角色扮演一名现场安全官，测试操作员对场景内危险情况的响应。

**设置：**

1. LMS 页面在 `allow="microphone"` 属性中包含 `<iframe>` 元素：

   ```html
   <iframe src="https://sim.company.com/safety-drill/" allow="microphone" width="1280" height="720"></iframe>
   ```
2. WebGL 构建通过 HTTPS 提供。
3. 一个明确的 **开始演练** 按钮放置在场景加载界面上，并连接到 `ConvaiManager.EnableAudioAndStartListening()`.

**结果：** 操作员点击 **开始演练**，在浏览器提示中授予麦克风权限，然后开始口头合规评估。

### 音频手势处理

浏览器要求在允许音频播放或麦克风捕获之前必须先有用户交互。SDK 通过两种方式处理这一点：

**自动手势检测：** 连接后，SDK 会监听第一个落在 UI 元素之外的点击或触摸，并自动调用 `EnableAudioAndStartListening()` 于 `ConvaiManager` 。这适用于用户直接与 3D 视图交互的场景。

**显式开始按钮（推荐用于 UI 较多的场景）：** 对于带有全屏遮罩、加载界面或加载时任何覆盖视图的 UI 的场景，自动检测可能不会可靠触发。请添加一个显式的开始按钮并将其连接到 `ConvaiManager.EnableAudioAndStartListening()`.

自动手势检测和显式开始按钮并不互斥——二者可以同时启用。当 UI 在加载时覆盖场景时，开始按钮方式通常更可靠。

{% tabs %}
{% tab title="检查器" %}

1. 添加一个 **Button** 组件到一个 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. 一个 **开始对话** 按钮按照上面的检查器方式放置在欢迎界面上。 `ConvaiManager.EnableAudioAndStartListening()` 连接到按钮的 **On Click ()** 事件。
3. 标准 SDK 配置——无需额外的 WebGL 特定步骤。

**结果：** 员工在欢迎界面上点击 **开始对话** 。浏览器会显示麦克风权限提示。授予权限后，Convai 角色开始入职对话。欢迎界面会在按钮被点击后自动隐藏。

### WebGL 上的视觉

在 WebGL 上，Vision 会捕获浏览器画布中渲染的 Unity 游戏视图。SDK 使用内部的 `WebGLCanvasVideoSource` 将浏览器画布发布为视觉帧源——标准的 `CameraVisionFrameSource` 组件在此平台上不使用。

与原生 Vision 的主要区别：

| 行为                 | 原生                                                    | WebGL      |
| ------------------ | ----------------------------------------------------- | ---------- |
| 帧源                 | `CameraVisionFrameSource` 或 `WebcamVisionFrameSource` | 浏览器画布      |
| 最大帧率               | 可配置                                                   | 15 fps（固定） |
| 摄像头访问              | 支持                                                    | SDK 无法提供   |
| `RenderTexture` 发布 | 支持                                                    | 未使用        |

WebGL Vision 捕获的是玩家在浏览器中看到的内容——游戏视图。对于角色需要通过摄像头查看学习者物理环境的场景，请改用桌面或移动端构建，并使用 `WebcamVisionFrameSource` 。

### 构建验证清单

在发布 WebGL 构建之前，请确认每一项：

* [ ] 构建通过 HTTPS 提供（或在 `localhost`)
* [ ] 如果嵌入在 iframe 中：父页面包含 `allow="microphone"` 添加到 `<iframe>` 元素
* [ ] 已存在显式开始按钮（尤其适用于 UI 较多的场景）
* [ ] 已在 Chrome、Firefox 和 Safari 中测试麦克风权限提示
* [ ] 已确认角色音频正在播放（浏览器音频路径——不是 `AudioSource`)
* [ ] 设置面板中的麦克风下拉菜单为空——确认这是预期行为，而不是错误
* [ ] 在浏览器中跨完整对话轮次，目视评估口型同步时序
* [ ] 如果启用了 Vision，则已验证视觉响应（画布捕获路径）

### 故障排除

| 症状                      | 可能原因                                      | 修复                                                              |
| ----------------------- | ----------------------------------------- | --------------------------------------------------------------- |
| 麦克风从未激活；角色听不到输入         | 构建通过 HTTP 而不是 HTTPS 提供                    | 通过 HTTPS 提供构建。 `localhost` 可免除。                                 |
| iframe 中麦克风被阻止；权限提示从未出现 | 缺少 `allow="microphone"` 添加到 `<iframe>` 元素 | 添加 `allow="microphone"` 到嵌入页面上的 iframe 标签中。                     |
| 角色音频静音；没有播放             | 在尝试音频播放前没有收到用户手势                          | 添加一个显式的开始按钮并连接到 `ConvaiManager.EnableAudioAndStartListening()`. |
| 设置面板中的麦克风下拉菜单为空         | 预期如此——浏览器在 WebGL 上控制设备选择                  | 无需修复。浏览器权限提示会处理设备选择。                                            |
| 麦克风测试失败或不可用             | WebGL 上不支持                                | 预期行为——告知用户浏览器构建不支持麦克风测试。                                        |
| 没有空间音频；声音缺乏 3D 定位       | WebGL 不支持空间音频                             | 预期如此。可以考虑在 UI 中说明这一点（例如耳机提示）。                                   |

#### 口型同步时序漂移

{% hint style="warning" %}
**口型同步时序漂移是 WebGL 上的一个已知缺陷。** 目前没有可行的解决方法。发布前请在浏览器中目视验证你的 WebGL 构建，并在生产时间表中考虑这一限制。
{% endhint %}

**症状：** 语音音频与嘴部动画之间出现明显不同步，尤其是在较长的语句中。

**原因：** 在 WebGL 上，SDK 使用 `RealtimePlaybackClock` （基于 `Time.realtimeSinceStartupAsDouble`）而不是原生平台使用的硬件 DSP 时钟。DSP 时钟与音频硬件绑定，并提供采样级精度的计时。 `Time.realtimeSinceStartupAsDouble` 独立于音频管线运行，这会导致漂移随时间累积。

**修复：** 目前没有可行的解决方法。

**验证：** 发布前，请在浏览器中跨完整对话轮次目视评估口型同步时序。

### 后续步骤

一旦确认 HTTPS、处理好手势要求并通过验证清单，你的 WebGL 构建就可以就绪了。如果你还要部署到 iOS、Android 或 XR 头显，这些平台有各自的权限要求。

{% content-ref url="/pages/a05c31e79a2f905396785b4f77b4554fc046528d" %}
[iOS 和 Android](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/platform-guides/ios-and-android.md)
{% endcontent-ref %}

{% content-ref url="/pages/eaa8f2e135526b94c0bfa16f39b4e7f1cc91ca79" %}
[XR 头显](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/platform-guides/xr-headsets.md)
{% endcontent-ref %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/platform-guides/webgl.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.