> 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、浏览器音频手势、视觉画布捕获以及已知的唇形同步漂移问题。

Convai Unity SDK 支持在 WebGL 上进行语音对话、口型同步、动作、动态上下文、情感、Vision 和长期记忆。浏览器引入了三个在原生平台上不存在的限制：麦克风访问必须使用 HTTPS 来源，音频播放或麦克风采集开始前必须先有用户手势，以及使用基于画布的 Vision 采集路径而不是 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 从以下地址加载 WebGL 构建： `https://sim.company.com/safety-drill`。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="Inspector" %}

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 角色扮演一名 HR 代表，引导新员工完成政策情景。

**设置：**

1. 构建通过公司内网服务器的 HTTPS 提供。
2. 一个 **“开始对话”** 按钮放置在欢迎屏幕上，使用上面的 Inspector 方法。 `ConvaiManager.EnableAudioAndStartListening()` 已绑定到按钮的 **On Click ()** 事件。
3. 标准 SDK 配置——无需额外的 WebGL 特定步骤。

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

### WebGL 上的 Vision

在 WebGL 上，Vision 会采集在浏览器画布中渲染的 Unity 游戏视图。SDK 使用内部的 `WebGLCanvasVideoSource` 将浏览器画布作为 Vision 帧源发布——标准的 `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，则验证 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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

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

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.