> 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/web-plugins/convai-embody/add-a-3d-character-to-a-react-app.md).

# 将 3D 角色添加到 React 应用

在 React 应用中安装 Convai Embody，并根据角色 ID 渲染一个带有口型同步、视线和眨眼效果的 Convai 角色。

在 React 应用中使用一个组件将 Convai 角色渲染为 3D 身体。首次将 Convai Embody 添加到项目时，请使用此页面。最后，角色会站在页面上，用眼睛跟随摄像机，并随着语音同步移动嘴巴。

### 前置条件

* 一个使用打包器的 React 18 或更高版本应用，以及 Node.js 18 或更高版本。
* 一个 Convai 账户、来自 <code class="expression">space.vars.dashboard\_url</code>的 API 密钥，以及一个角色 ID。
* 一个其头像已发布 Web 身体，或者已应用默认身体的角色。两者都没有的角色无法渲染。参见 [故障排除](#troubleshooting).

### 安装这些包

`@convai/web-sdk` 和 `three` 是同级依赖，因此请将它们与 `@convai/embody`一起安装。React 路径还需要 `react` 和 `@react-three/fiber`.

{% tabs %}
{% tab title="npm" %}

```bash
npm install @convai/embody @convai/web-sdk three @react-three/fiber
```

{% endtab %}

{% tab title="pnpm" %}

```bash
pnpm add @convai/embody @convai/web-sdk three @react-three/fiber
```

{% endtab %}

{% tab title="yarn" %}

```bash
yarn add @convai/embody @convai/web-sdk three @react-three/fiber
```

{% endtab %}
{% endtabs %}

### 渲染角色

`ConvaiCharacter` 自带画布、摄像机、灯光和轨道控制。它会解析角色的身体，打开 Convai Web SDK 连接，播放角色的音频，并驱动其面部。

{% code title="src/App.tsx" %}

```tsx
import ConvaiCharacter from '@convai/embody/react'

export default function App() {
  return (
    <ConvaiCharacter
      apiKey={import.meta.env.VITE_CONVAI_API_KEY}
      characterId="YOUR_CHARACTER_ID"
    />
  )
}
```

{% endcode %}

该组件会充满其父容器，并且高度至少与视口一样高。拖动可绕角色转身，滚动可移近。传入 `orbit={false}` 即可使用固定摄像机。

{% hint style="danger" %}
API 密钥是工作区范围的凭据。任何打开包含它的页面的人都可以读取它。对于公开页面，请在服务器上创建一个短期有效的身份验证令牌，并传入 `token` 而不是 `apiKey`。请参阅 [身份验证令牌](/api-docs/zh/cha-jian-yu-ji-cheng/web-plugins/convai-web-sdk/auth-tokens.md).
{% endhint %}

### 将角色放入你自己的场景中

当角色加入一个你已经用 `@react-three/fiber`，请使用 `CharacterModel` 在你的 `<Canvas>` 中构建的场景时，请改用它。它接受相同的凭据和角色属性，并且不会添加自己的画布、摄像机或灯光。

{% code title="src/Scene.tsx" %}

```tsx
import { Canvas } from '@react-three/fiber'
import { CharacterModel } from '@convai/embody/react'

export function Scene({ token }: { token: string }) {
  return (
    <Canvas camera={{ position: [0, 1.45, 3.6], fov: 35 }}>
      <ambientLight intensity={0.6} />
      <directionalLight position={[2, 3, 2]} />
      <CharacterModel token={token} characterId="YOUR_CHARACTER_ID" />
    </Canvas>
  )
}
```

{% endcode %}

### 验证角色

加载页面并等待模型下载。然后与角色交谈，例如通过中描述的小组件 [向角色添加聊天小组件](/api-docs/zh/cha-jian-yu-ji-cheng/web-plugins/convai-embody/add-a-chat-widget-to-a-character.md).

{% hint style="success" %}
角色会居中站立并播放待机动画，当你环绕视角时它的眼睛会跟随摄像机，而当它回答时嘴巴会随声音同步移动。
{% endhint %}

若要在代码中观察加载过程，请传入 `onReady`，它会在身体加载完成且连接已建立后接收角色句柄，以及 `onError`，它会接收导致其停止的错误。

### 故障排除

#### 角色从未出现

**症状：** `onError` 接收到一个错误，其消息末尾包含 Convai 给出的原因：

```
embodiment resolve failed for YOUR_CHARACTER_ID: HTTP 404 — Character has no 3D embodiment configured.
```

**原因：** 该角色的头像没有已发布的 Web 身体，也没有适用的默认身体。

**修复：** 选择一个头像已发布 Web 身体的角色。如果你的角色都没有，请联系 Convai 支持。

**验证：** 重新加载页面。角色会被渲染出来。

#### 在任何内容加载之前就抛出凭据错误

**症状：** 创建角色时抛出：

```
@convai/embody：需要凭据 — 请传入 `token`（浏览器推荐）或 `apiKey`。Convai 不提供匿名访问。
```

**原因：** 既没有 `token`, `authToken`，也没有 `apiKey` 被设置，或者在构建时应保存它的变量为空。

**修复：** 传入一个凭据。检查该环境变量是否已为你正在运行的构建定义。

**验证：** 错误不再出现，角色已加载。

#### 在具有严格内容安全策略的页面上模型加载失败

**症状：** 身体始终未渲染，浏览器控制台报告有被阻止的请求到 `https://www.gstatic.com/draco/`.

**原因：** 角色模型使用 Draco 压缩，Convai Embody 默认从 `https://www.gstatic.com/draco/versioned/decoders/1.5.7/` 加载 Draco 解码器。

**修复：** 在你的策略中允许该来源，或者自行托管解码器文件并将其 URL 作为 `dracoDecoderPath`.

**验证：** 角色已渲染，且控制台中没有被阻止的解码器请求。

### 下一步

{% content-ref url="/pages/2e94cc1e2d8d4d328ddd3855269d9e50f989aece" %}
[向角色添加聊天小部件](/api-docs/zh/cha-jian-yu-ji-cheng/web-plugins/convai-embody/add-a-chat-widget-to-a-character.md)
{% endcontent-ref %}

{% content-ref url="/pages/afcae56dd5bee11232aa7e5af42d7608c0a2f044" %}
[React API 参考](/api-docs/zh/cha-jian-yu-ji-cheng/web-plugins/convai-embody/react-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/web-plugins/convai-embody/add-a-3d-character-to-a-react-app.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.