React

了解如何安装、配置和集成 Convai Web SDK（@convai/web-sdk），以便将低延迟对话式 AI、语音交互和可选视频带入你的 Web 应用。

安装

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

npm install @convai/web-sdk

或者：

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

快速入门

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

你必须提供：

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

1. 最小组件设置

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

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

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

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

最终用户 ID

提供一个唯一 ID 以启用：

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

同行依赖：

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

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