> 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

## 安装

使用你偏好的包管理器安装 SDK：

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

或者：

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

## 快速入门

React SDK 围绕一个单一的 `ConvaiClient` 实例，由 `useConvaiClient` Hook 创建。

你必须提供：

* `apiKey` — 你的 Convai API 密钥
* `characterId` — 要连接的角色 ID

#### 1. 最小组件设置

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

function App() {
  const convaiClient = useConvaiClient({
    apiKey: "your-api-key",
    characterId: "your-character-id",
    endUserId: "user-uuid", // 可选：启用记忆和分析
  });

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

这将为你提供一个 **完整的聊天 + 语音界面**。该组件：

* 在首次用户交互时自动连接（符合浏览器自动播放规则）
* 管理音频采集和机器人播放
* 显示输入、思考和说话状态

这会初始化一个完整的、可直接使用语音的聊天界面，无需额外配置。

### 启用视频和屏幕共享（概览）

React 视频和屏幕共享需要 **两项内容**:

1. `enableVideo: true` 在 `useConvaiClient` 配置
2. `showVideo` / `showScreenShare` 属性于 `<ConvaiWidget />` 或手动使用 `videoControls` / `screenShareControls`

```tsx
const convaiClient = useConvaiClient({
  apiKey: "your-api-key",
  characterId: "your-character-id",
  enableVideo: true,
  startWithVideoOn: false,
});

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

这会为组件添加摄像头和屏幕共享选项。

{% hint style="success" %}
最终用户 ID

**提供一个唯一 ID** 以启用：

* 长期记忆（基于上下文的过往对话回复）。
* 分析（最终用户跟踪）。
  {% endhint %}

**同行依赖：**

对于 React 使用，SDK 需要 React 18+：

```json
{
  "peerDependencies": {
    "react": "^18.0.0",
    "react-dom": "^18.0.0"
  }
}
```


---

# 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:

```
GET https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/web-plugins/convai-web-sdk/react.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.