> 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-web-sdk/react.md).

# 开始使用 React

在 React 应用中安装 Convai Web SDK，并添加一个现成的聊天和语音小组件，还可为你的角色选择性启用摄像头和屏幕共享。

使用 `useConvaiClient` 钩子和 `ConvaiWidget` 组件将 Convai 角色添加到 React 应用中。首次设置 React 绑定时，请使用此页面。完成后，页面会显示一个小组件按钮，点击后即可与角色进行语音和文本对话。

### 前提条件

* 使用打包工具的 React 18 或 19 应用。 `react` 18 或 19 是 `@convai/web-sdk/react`; `@convai/web-widget` （预构建 UI）也需要 `react-dom`.
* 一个 Convai 账户，以及从 <code class="expression">space.vars.dashboard\_url</code>.
* 要连接的角色 ID。

### 安装软件包

React 绑定包含在 `@convai/web-sdk` 中，并从 `@convai/web-sdk/react` 子路径导入。无需单独安装 React 包。

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

```bash
npm install @convai/web-sdk @convai/web-widget
```

{% endtab %}

{% tab title="pnpm" %}

```bash
pnpm add @convai/web-sdk @convai/web-widget
```

{% endtab %}

{% tab title="yarn" %}

```bash
yarn add @convai/web-sdk @convai/web-widget
```

{% endtab %}
{% endtabs %}

### 添加小组件

`useConvaiClient` 为组件创建一个客户端并存储配置。 `ConvaiWidget` 用于呈现对话 UI，并在用户首次点击其按钮时使用已存储的配置建立连接，因此浏览器只会在用户操作后请求麦克风权限。

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

```tsx
import { useConvaiClient } from '@convai/web-sdk/react';
import { ConvaiWidget } from '@convai/web-widget/react';

export default function App() {
  const convaiClient = useConvaiClient({
    apiKey: 'YOUR_API_KEY',
    characterId: 'YOUR_CHARACTER_ID',
    endUserId: 'user-123',
  });

  return <ConvaiWidget convaiClient={convaiClient} />;
}
```

{% endcode %}

小组件会播放角色语音，在语音模式下采集麦克风音频，并在对话流式传输时显示对话内容。

`endUserId` 为可选参数。传入每位用户稳定且唯一的 ID（例如 UUID），即可启用长期记忆和按用户统计分析。不传入此参数时，会话为匿名会话。请参阅 [使用长期记忆](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/web-plugins/convai-web-sdk/long-term-memory.md).

{% hint style="danger" %}
客户端代码中的 API 密钥对任何打开页面的人都可见。对于公开页面，请在服务器上创建一个短时有效的身份验证令牌，并传入 `authToken` 而不是 `apiKey`。请参阅 [使用身份验证令牌连接](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/web-plugins/convai-web-sdk/auth-tokens.md).
{% endhint %}

### 启用摄像头和屏幕共享

将 `enableVideo: true` 设置为通过 `"video"` 连接类型进行连接，该类型支持音频、摄像头视频和屏幕共享。 `startWithVideoOn` 用于在连接时开启摄像头；默认值为 `false`。当连接类型为 `"video"`时，小组件会在设置栏中显示摄像头和屏幕共享按钮；可使用 `showVideo={false}` 隐藏其中任一按钮，或 `showScreenShare={false}`.

```tsx
const convaiClient = useConvaiClient({
  apiKey: 'YOUR_API_KEY',
  characterId: 'YOUR_CHARACTER_ID',
  enableVideo: true,
  startWithVideoOn: false,
});

return <ConvaiWidget convaiClient={convaiClient} showVideo showScreenShare />;
```

### 验证集成

启动开发服务器并打开页面。点击小组件按钮，允许访问麦克风，然后对角色说点什么。

{% hint style="success" %}
小组件会以语音模式打开，你说的话会显示为消息，角色则会以文字和语音作答。
{% endhint %}

### 后续步骤

<table data-view="cards"><thead><tr><th></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><strong>useConvaiClient Hook 参考</strong><br>此 Hook 返回的所有内容，包括仅适用于 React 的状态。</td><td><a href="https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/web-plugins/convai-web-sdk/react/useconvaiclient-hook.md">useConvaiClient Hook 参考</a></td></tr><tr><td><strong>ConvaiWidget 组件参考</strong><br>属性、默认值，以及该小组件会代你完成的操作。</td><td><a href="https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/web-plugins/convai-web-sdk/react/convaiwidget.md">ConvaiWidget 组件参考</a></td></tr><tr><td><strong>在 React 中添加口型同步</strong><br>在渲染循环中，使用混合形状流驱动 3D 面部。</td><td><a href="https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/web-plugins/convai-web-sdk/react/real-time-lipsync.md">在 React 中添加口型同步</a></td></tr><tr><td><strong>在 React 中构建自定义 UI</strong><br>用你自己的消息和控件替换小组件。</td><td><a href="https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/web-plugins/convai-web-sdk/react/custom-ui-and-advanced-usage.md">在 React 中构建自定义 UI</a></td></tr><tr><td><strong>在 React 中添加音频可视化器</strong><br>使用 Web Audio API 绘制角色的语音音量。</td><td><a href="https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/web-plugins/convai-web-sdk/react/audio-visualizer-optional.md">在 React 中添加音频可视化器</a></td></tr></tbody></table>


---

# 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-web-sdk/react.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.
