> 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-pixel-streaming-embed/vanilla-javascript-es-modules.md).

# 使用 JavaScript 模块嵌入体验

无需 React，使用该包提供的无框架客户端，通过 JavaScript 模块脚本渲染已发布的 Pixel Streaming 体验。

从一个已发布的 Convai Pixel Streaming 体验渲染 `<script type="module">` 无需 React，使用无框架的 `PixelStreamClient` 类。最后，页面会显示该体验的开始屏幕。

### 先决条件

* 已发布体验的体验 ID，以及一种授权方式：返回 Convai 认证令牌的服务器路由，或已被 Convai 加入白名单的域名。参见 [发布并授权体验](/api-docs/zh/cha-jian-yu-ji-cheng/convai-pixel-streaming-embed/whitelisting-and-publishing-an-experience.md).
* 用于该页面的 Web 服务器，因为示例会从同一服务器上的一个路由获取令牌。

### 客户端的打包方式

`PixelStreamClient` 位于 `@convai/experience-embed/core` 入口点。根入口点 `@convai/experience-embed`，而是导出 React 组件。core 入口点不包含任何 React 代码，并且可解析为 ES 模块、CommonJS 以及 UMD 脚本：

| 你如何加载页面                            | 要导入什么                                                               |
| ---------------------------------- | ------------------------------------------------------------------- |
| 一个打包工具，例如 Vite、webpack 或 esbuild   | `import { PixelStreamClient } from '@convai/experience-embed/core'` |
| 一个 `<script type="module">` 无需打包工具 | 通过 URL 引入 ES 构建： `dist/core/convai-embed.es.js`                     |
| 一个普通的 `<script>` 标签                | UMD 构建， `dist/core/convai-embed.umd.js`，它定义全局 `PixelStreamCore`     |

浏览器无法解析裸标识符 `@convai/experience-embed/core` 本身，因此在没有打包工具的情况下，模块脚本会像下面这样通过 URL 导入该文件。

{% hint style="info" %}
0.7.1 之前发布的版本 `PixelStreamClient` 仅作为 UMD 构建，因此 `import { PixelStreamClient } from '@convai/experience-embed/core'` 在打包工具和 Node 中会失败。请升级到 0.7.1 或更高版本，或者仅为其副作用导入 UMD 文件，并读取 `globalThis.PixelStreamCore`.
{% endhint %}

### 创建客户端

{% code title="index.html" %}

```html
<div id="experience" style="width: 100%; height: 600px"></div>

<script type="module">
  import { PixelStreamClient } from 'https://unpkg.com/@convai/experience-embed/dist/core/convai-embed.es.js';

  const { token } = await fetch('/api/convai-token').then((response) => response.json());

  const experience = new PixelStreamClient({
    container: document.getElementById('experience'),
    expId: 'YOUR_EXPERIENCE_ID',
    authToken: token,
    onIframeLoaded: () => console.log('Experience loaded'),
  });
</script>
```

{% endcode %}

客户端会填充其容器，因此请为容器设置大小。如果 Convai 已将你的域名加入白名单，而不是使用令牌，则省略 `authToken` 以及 fetch。

若要自行提供该文件而不是从 unpkg 获取，请使用以下命令安装该包： `npm install @convai/experience-embed` 并从你的服务器公开该文件的位置导入同一文件 `node_modules/@convai/experience-embed/dist/core/convai-embed.es.js`。使用打包工具时，请导入 `@convai/experience-embed/core` 其名称，让打包工具自行解析。

### 控制体验

客户端会显示一个 **点击开始你的体验** 屏幕。若要改为从你自己的控件启动体验，请传入一个 `InitialScreen` 元素，并调用 `experience.initializeExperience()` 。从中即可。等到 `onIframeLoaded` 触发后，调用诸如 `experience.enableCamera()` 或 `experience.sendMessageToCharacter('Hello')`。当你从页面中移除体验时，请调用 `experience.destroy()` 并清空容器。

该 [Pixel Streaming Embed API 参考](/api-docs/zh/cha-jian-yu-ji-cheng/convai-pixel-streaming-embed/api-reference.md#pixelstreamclient-options) 列出了所有选项、方法和回调。

### 验证嵌入

通过你的 Web 服务器打开页面并点击开始屏幕。

{% hint style="success" %}
体验会替换开始屏幕，浏览器控制台会记录 `体验已加载`.
{% endhint %}

如果容器中显示的是错误消息，请参阅 [故障排除](/api-docs/zh/cha-jian-yu-ji-cheng/convai-pixel-streaming-embed/react-typescript.md#troubleshooting)；原因是相同的。

### 后续步骤

{% content-ref url="/pages/87b57936662c69d8802f20f500191b181163cf02" %}
[Pixel Streaming Embed API 参考](/api-docs/zh/cha-jian-yu-ji-cheng/convai-pixel-streaming-embed/api-reference.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-pixel-streaming-embed/vanilla-javascript-es-modules.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.