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

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>
```

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

#### 示例：LMS iframe 嵌入

一家制造公司在其学习管理系统（LMS）中嵌入了一项安全合规演练。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="Inspector" %}

1. 添加一个 **按钮** 组件到 UI 游戏对象。
2. 在 **On Click ()** 列表中，点击 **+**.
3. 将你的 `ConvaiManager` 游戏对象拖到对象字段中。
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. 一个 **开始对话** 按钮通过上述 Inspector 方法放置在欢迎屏幕上。 `ConvaiManager.EnableAudioAndStartListening()` 已连接到按钮的 **On Click ()** 事件。
3. 标准 SDK 配置——无需额外的 WebGL 专用步骤。

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

### WebGL 上的视觉功能

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

与原生视觉功能的主要区别：

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

WebGL Vision 捕获玩家在浏览器中看到的内容——游戏画面。如果角色需要通过摄像头查看学习者的实际环境，请改用桌面版或移动版，并使用 `WebcamVisionFrameSource` 。

### 构建验证清单

发布 WebGL 构建版本之前，请确认以下各项：

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

### 故障排查

| 症状                       | 可能原因                                         | 解决方法                                                                 |
| ------------------------ | -------------------------------------------- | -------------------------------------------------------------------- |
| 麦克风始终无法启动；角色听不到输入        | 构建版本通过 HTTP 而非 HTTPS 提供                      | 通过 HTTPS 提供构建版本。 `localhost` 不受此限制。                                  |
| iframe 中的麦克风被阻止；权限提示从未出现 | 缺少 `allow="microphone"` 属性，位于 `<iframe>` 元素上 | 在嵌入页面的 iframe 标签中添加 `allow="microphone"` 。                           |
| 角色音频静音；没有声音播放            | 尝试播放音频之前未收到用户手势                              | 添加一个显式的“开始”按钮，并将其绑定到 `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](https://docs.convai.com/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 头显](https://docs.convai.com/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.
