> 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 采集路径基于 canvas，而不是 Unity `RenderTexture`。本页涵盖了这三项。

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

### 功能支持

| 功能                     | WebGL                |
| ---------------------- | -------------------- |
| 语音对话                   | ✅ 完全支持               |
| 口型同步                   | ✅ 完全支持（参见故障排除中的已知问题） |
| 动作                     | ✅ 完全支持               |
| 动态上下文                  | ✅ 完全支持               |
| 情绪                     | ✅ 完全支持               |
| 视觉                     | ✅ Canvas 采集（浏览器游戏视图） |
| 长期记忆                   | ✅ 完全支持               |
| 空间音频                   | ❌ 不支持                |
| 屏幕共享                   | ❌ 不支持                |
| 麦克风设备选择                | ❌ 不可用——由浏览器控制设备选择    |
| 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 视图交互的场景。

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

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

{% 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 %}

#### 示例：企业入职培训

一家企业 L\&D 团队在其公司内网上托管了一项公司政策培训模拟，地址为 `https://training.company.internal/onboarding`。Convai 角色扮演一位人力资源代表，带领新员工了解各类政策场景。

**设置：**

1. 构建通过公司内网服务器的 HTTPS 提供。
2. 某个 **Start Conversation** 按钮使用上面的 Inspector 方法放置在欢迎屏幕上。 `ConvaiManager.EnableAudioAndStartListening()` 连接到该按钮的 **On Click ()** 事件。
3. 标准 SDK 配置——无需额外的 WebGL 特定步骤。

**结果：** 员工点击 **Start Conversation** ，在欢迎屏幕上。浏览器会显示麦克风权限提示。授予权限后，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"` 组件上的 `<iframe>` 元素
* [ ] 存在显式 Start 按钮（尤其是 UI 较多的场景）
* [ ] 已在 Chrome、Firefox 和 Safari 中测试麦克风权限提示
* [ ] 已确认角色音频正在播放（浏览器音频路径——而非 `AudioSource`)
* [ ] 设置面板中的麦克风下拉列表为空——确认这是预期行为，而不是错误
* [ ] 在浏览器中跨完整对话轮次通过视觉方式评估了口型同步时序
* [ ] 如果启用了 Vision，则已验证 Vision 响应（canvas 采集路径）

### 故障排除

| 症状                       | 可能原因                                       | 修复方法                                                                  |
| ------------------------ | ------------------------------------------ | --------------------------------------------------------------------- |
| 麦克风从不激活；角色听不到输入          | 构建通过 HTTP 提供，而不是 HTTPS                     | 请通过 HTTPS 提供构建。 `localhost` 被豁免。                                      |
| iframe 中的麦克风被阻止；权限提示从未出现 | 缺少 `allow="microphone"` 组件上的 `<iframe>` 元素 | 添加 `allow="microphone"` 嵌入页面上的 iframe 标签中。                            |
| 角色音频静音；没有播放              | 在尝试音频播放之前未收到用户手势                           | 添加一个显式 Start 按钮并将其连接到 `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.