Back to Details

rw-integrate-character-embed

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Embed Characters in React (Avatars React SDK)

在React中嵌入角色（Avatars React SDK）

PREREQUISITES:
  • +rw-check-compatibility
    — Project must have server-side capability (API key must never be exposed to the client)
  • +rw-fetch-api-reference
    — Load the latest API reference from https://docs.dev.runwayml.com/api/ before integrating
  • +rw-integrate-characters
    — Character (Avatar) must be created and session endpoint must exist
  • Project must use React (Next.js, Vite+React, Remix, etc.)
OPTIONAL:
  • +rw-integrate-documents
    — Add knowledge base before embedding
Embed real-time avatar video calls in React applications using the 
@runwayml/avatars-react
SDK.
前提条件：
  • +rw-check-compatibility
    — 项目必须具备服务器端能力（API密钥绝不能暴露给客户端）
  • +rw-fetch-api-reference
    — 集成前请从https://docs.dev.runwayml.com/api/加载最新的API参考文档
  • +rw-integrate-characters
    — 必须已创建角色（头像）且会话端点已存在
  • 项目必须使用React（Next.js、Vite+React、Remix等）
可选操作：
  • +rw-integrate-documents
    — 嵌入前添加知识库
使用
@runwayml/avatars-react
SDK在React应用中嵌入实时头像视频通话功能。

Installation

安装

bash
npm install @runwayml/avatars-react
This is a client-side package. The server-side 
@runwayml/sdk
should already be installed from 
+rw-integrate-characters
.
bash
npm install @runwayml/avatars-react
这是一个客户端包。服务器端的
@runwayml/sdk
应已通过
+rw-integrate-characters
完成安装。

Option A: Simple — 
AvatarCall
Component

选项A：简单实现 — 
AvatarCall
组件

The fastest way to embed a character. Handles WebRTC connection and renders a default UI automatically.
tsx
'use client';

import { AvatarCall } from '@runwayml/avatars-react';
import '@runwayml/avatars-react/styles.css';

export default function CharacterPage() {
  return (
    <AvatarCall
      avatarId="your-avatar-id-here"
      connectUrl="/api/avatar/session"
      onEnd={() => console.log('Call ended')}
      onError={(error) => console.error('Error:', error)}
    />
  );
}
嵌入角色的最快方式。自动处理WebRTC连接并渲染默认UI。
tsx
'use client';

import { AvatarCall } from '@runwayml/avatars-react';
import '@runwayml/avatars-react/styles.css';

export default function CharacterPage() {
  return (
    <AvatarCall
      avatarId="your-avatar-id-here"
      connectUrl="/api/avatar/session"
      onEnd={() => console.log('Call ended')}
      onError={(error) => console.error('Error:', error)}
    />
  );
}

AvatarCall
Props

AvatarCall
属性

PropTypeDescription
avatarId
string
The Avatar UUID from the Developer Portal or API
connectUrl
string
Your server-side session endpoint (e.g., 
/api/avatar/session
)
onEnd
() => void
Called when the call ends normally
onError
(error: Error) => void
Called on connection or runtime errors
For custom avatars created in the Developer Portal, use the Avatar UUID as 
avatarId
.
属性类型描述
avatarId
string
来自开发者门户或API的头像UUID
connectUrl
string
你的服务器端会话端点（例如：
/api/avatar/session
）
onEnd
() => void
通话正常结束时调用
onError
(error: Error) => void
连接或运行时出错时调用
对于在开发者门户中创建的自定义头像，请使用头像UUID作为
avatarId
。

Option B: Fully Custom — Hooks

选项B：完全自定义 — Hooks

For full control over the UI, use 
AvatarSession
with hooks.
如需完全控制UI，请结合Hooks使用
AvatarSession
。

Components & Hooks

组件与Hooks

ExportTypeDescription
AvatarSession
ComponentProvider that manages the WebRTC session
AvatarVideo
ComponentRenders the avatar's video stream
UserVideo
ComponentRenders the user's camera feed
useAvatarSession
HookAccess session state: 
state
, 
sessionId
, 
error
, 
end()
useLocalMedia
HookControl user's media: 
isMicEnabled
, 
toggleMic()
导出项类型描述
AvatarSession
组件管理WebRTC会话的提供者
AvatarVideo
组件渲染头像的视频流
UserVideo
组件渲染用户的摄像头画面
useAvatarSession
Hook访问会话状态：
state
、
sessionId
、
error
、
end()
useLocalMedia
Hook控制用户媒体：
isMicEnabled
、
toggleMic()

Custom UI Example

自定义UI示例

tsx
'use client';

import {
  AvatarSession,
  AvatarVideo,
  UserVideo,
  useAvatarSession,
  useLocalMedia,
} from '@runwayml/avatars-react';
import type { SessionCredentials } from '@runwayml/avatars-react';

function CallUI() {
  const { state, end } = useAvatarSession();
  const { isMicEnabled, toggleMic } = useLocalMedia();

  return (
    <div className="relative w-full h-screen">
      {/* Avatar video takes full screen */}
      <AvatarVideo className="w-full h-full object-cover" />

      {/* User's camera in a small overlay */}
      <UserVideo className="absolute bottom-4 right-4 w-48 rounded-lg" />

      {/* Controls */}
      <div className="absolute bottom-4 left-4 flex gap-2">
        <button onClick={toggleMic}>
          {isMicEnabled ? 'Mute' : 'Unmute'}
        </button>
        <button onClick={end}>End Call</button>
      </div>

      {/* Connection state */}
      {state === 'connecting' && (
        <div className="absolute inset-0 flex items-center justify-center bg-black/50">
          Connecting...
        </div>
      )}
    </div>
  );
}

export function CustomAvatar({ credentials }: { credentials: SessionCredentials }) {
  return (
    <AvatarSession credentials={credentials} audio video>
      <CallUI />
    </AvatarSession>
  );
}
tsx
'use client';

import {
  AvatarSession,
  AvatarVideo,
  UserVideo,
  useAvatarSession,
  useLocalMedia,
} from '@runwayml/avatars-react';
import type { SessionCredentials } from '@runwayml/avatars-react';

function CallUI() {
  const { state, end } = useAvatarSession();
  const { isMicEnabled, toggleMic } = useLocalMedia();

  return (
    <div className="relative w-full h-screen">
      {/* 头像视频占满全屏 */}
      <AvatarVideo className="w-full h-full object-cover" />

      {/* 用户摄像头画面以小窗口叠加显示 */}
      <UserVideo className="absolute bottom-4 right-4 w-48 rounded-lg" />

      {/* 控制按钮 */}
      <div className="absolute bottom-4 left-4 flex gap-2">
        <button onClick={toggleMic}>
          {isMicEnabled ? '静音' : '取消静音'}
        </button>
        <button onClick={end}>结束通话</button>
      </div>

      {/* 连接状态 */}
      {state === 'connecting' && (
        <div className="absolute inset-0 flex items-center justify-center bg-black/50">
          连接中...
        </div>
      )}
    </div>
  );
}

export function CustomAvatar({ credentials }: { credentials: SessionCredentials }) {
  return (
    <AvatarSession credentials={credentials} audio video>
      <CallUI />
    </AvatarSession>
  );
}

Fetching Credentials for Custom UI

为自定义UI获取凭证

When using the hooks approach, you need to fetch credentials from your server endpoint and pass them to 
AvatarSession
:
tsx
'use client';

import { useState, useCallback } from 'react';
import type { SessionCredentials } from '@runwayml/avatars-react';
import { CustomAvatar } from './CustomAvatar';

export default function CharacterPage() {
  const [credentials, setCredentials] = useState<SessionCredentials | null>(null);
  const [loading, setLoading] = useState(false);

  const startCall = useCallback(async () => {
    setLoading(true);
    try {
      const res = await fetch('/api/avatar/session', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({ avatarId: 'your-avatar-id-here' }),
      });
      const data = await res.json();
      setCredentials(data);
    } catch (error) {
      console.error('Failed to connect:', error);
    } finally {
      setLoading(false);
    }
  }, []);

  if (credentials) {
    return <CustomAvatar credentials={credentials} />;
  }

  return (
    <button onClick={startCall} disabled={loading}>
      {loading ? 'Connecting...' : 'Start Conversation'}
    </button>
  );
}
使用Hooks方式时，你需要从服务器端点获取凭证并传递给
AvatarSession
：
tsx
'use client';

import { useState, useCallback } from 'react';
import type { SessionCredentials } from '@runwayml/avatars-react';
import { CustomAvatar } from './CustomAvatar';

export default function CharacterPage() {
  const [credentials, setCredentials] = useState<SessionCredentials | null>(null);
  const [loading, setLoading] = useState(false);

  const startCall = useCallback(async () => {
    setLoading(true);
    try {
      const res = await fetch('/api/avatar/session', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({ avatarId: 'your-avatar-id-here' }),
      });
      const data = await res.json();
      setCredentials(data);
    } catch (error) {
      console.error('连接失败:', error);
    } finally {
      setLoading(false);
    }
  }, []);

  if (credentials) {
    return <CustomAvatar credentials={credentials} />;
  }

  return (
    <button onClick={startCall} disabled={loading}>
      {loading ? '连接中...' : '开始对话'}
    </button>
  );
}

Integration Patterns

集成模式

Next.js App Router (Full Example)

Next.js App Router（完整示例）

Server route (
app/api/avatar/session/route.ts
): See 
+rw-integrate-characters
for the complete server-side session creation code.
Client page (
app/character/page.tsx
):
tsx
'use client';

import { AvatarCall } from '@runwayml/avatars-react';
import '@runwayml/avatars-react/styles.css';

const AVATAR_ID = process.env.NEXT_PUBLIC_AVATAR_ID || 'your-avatar-id';

export default function CharacterPage() {
  return (
    <div className="flex items-center justify-center min-h-screen">
      <AvatarCall
        avatarId={AVATAR_ID}
        connectUrl="/api/avatar/session"
        onEnd={() => window.location.reload()}
        onError={(error) => {
          console.error('Avatar error:', error);
          alert('Connection failed. Please try again.');
        }}
      />
    </div>
  );
}
服务器路由 (
app/api/avatar/session/route.ts
): 请查看
+rw-integrate-characters
获取完整的服务器端会话创建代码。
客户端页面 (
app/character/page.tsx
):
tsx
'use client';

import { AvatarCall } from '@runwayml/avatars-react';
import '@runwayml/avatars-react/styles.css';

const AVATAR_ID = process.env.NEXT_PUBLIC_AVATAR_ID || 'your-avatar-id';

export default function CharacterPage() {
  return (
    <div className="flex items-center justify-center min-h-screen">
      <AvatarCall
        avatarId={AVATAR_ID}
        connectUrl="/api/avatar/session"
        onEnd={() => window.location.reload()}
        onError={(error) => {
          console.error('头像错误:', error);
          alert('连接失败，请重试。');
        }}
      />
    </div>
  );
}

Conditional Rendering (Show/Hide)

条件渲染（显示/隐藏）

tsx
'use client';

import { useState } from 'react';
import { AvatarCall } from '@runwayml/avatars-react';
import '@runwayml/avatars-react/styles.css';

export default function SupportPage() {
  const [showAvatar, setShowAvatar] = useState(false);

  return (
    <div>
      <h1>Customer Support</h1>

      {!showAvatar ? (
        <button onClick={() => setShowAvatar(true)}>
          Talk to an Agent
        </button>
      ) : (
        <AvatarCall
          avatarId="support-agent-id"
          connectUrl="/api/avatar/session"
          onEnd={() => setShowAvatar(false)}
          onError={(error) => {
            console.error(error);
            setShowAvatar(false);
          }}
        />
      )}
    </div>
  );
}
tsx
'use client';

import { useState } from 'react';
import { AvatarCall } from '@runwayml/avatars-react';
import '@runwayml/avatars-react/styles.css';

export default function SupportPage() {
  const [showAvatar, setShowAvatar] = useState(false);

  return (
    <div>
      <h1>客户支持</h1>

      {!showAvatar ? (
        <button onClick={() => setShowAvatar(true)}>
          与客服Agent对话
        </button>
      ) : (
        <AvatarCall
          avatarId="support-agent-id"
          connectUrl="/api/avatar/session"
          onEnd={() => setShowAvatar(false)}
          onError={(error) => {
            console.error(error);
            setShowAvatar(false);
          }}
        />
      )}
    </div>
  );
}

Error Handling

错误处理

Verbose Error Logging

详细错误日志

tsx
<AvatarCall
  avatarId="your-avatar-id"
  connectUrl="/api/avatar/session"
  onError={(error) => {
    console.error('Avatar error:', error);
    console.error('Error name:', error.name);
    console.error('Error message:', error.message);
    if (error.cause) {
      console.error('Cause:', error.cause);
    }
  }}
/>
tsx
<AvatarCall
  avatarId="your-avatar-id"
  connectUrl="/api/avatar/session"
  onError={(error) => {
    console.error('头像错误:', error);
    console.error('错误名称:', error.name);
    console.error('错误信息:', error.message);
    if (error.cause) {
      console.error('原因:', error.cause);
    }
  }}
/>

Debug Session State

调试会话状态

tsx
import { useAvatarSession } from '@runwayml/avatars-react';

function DebugPanel() {
  const { state, sessionId, error } = useAvatarSession();

  return (
    <pre style={{ fontSize: 12, position: 'fixed', top: 0, right: 0 }}>
      {JSON.stringify({ state, sessionId, error: error?.message }, null, 2)}
    </pre>
  );
}
tsx
import { useAvatarSession } from '@runwayml/avatars-react';

function DebugPanel() {
  const { state, sessionId, error } = useAvatarSession();

  return (
    <pre style={{ fontSize: 12, position: 'fixed', top: 0, right: 0 }}>
      {JSON.stringify({ state, sessionId, error: error?.message }, null, 2)}
    </pre>
  );
}

Browser Support

浏览器支持

BrowserMinimum Version
Chrome74+
Firefox78+
Safari14.1+
Edge79+
Users must grant microphone permissions when prompted. Camera permissions are needed if user video is enabled.
浏览器最低版本
Chrome74+
Firefox78+
Safari14.1+
Edge79+
用户必须在提示时授予麦克风权限。如果启用用户视频，则需要摄像头权限。

Tips

小贴士

  • Always import the styles: 
    import '@runwayml/avatars-react/styles.css'
    when using 
    AvatarCall
  • 'use client'
    directive     is required in Next.js App Router for all components using the React SDK
  • Session max duration is 5 minutes — handle the 
    onEnd
    callback to show a reconnect option
  • Credentials are one-time use — if connection fails, fetch new credentials (create a new session)
  • For the full SDK source, examples, and issue tracking: github.com/runwayml/avatars-sdk-react
  • 务必导入样式：使用
    AvatarCall
    时请导入
    import '@runwayml/avatars-react/styles.css'
  • 'use client'
    指令    ：在Next.js App Router中，所有使用React SDK的组件都需要该指令
  • 会话最长持续时间为5分钟 — 处理
    onEnd
    回调以显示重新连接选项
  • 凭证仅可使用一次 — 如果连接失败，请获取新凭证（创建新会话）
  • 如需完整的SDK源码、示例和问题追踪，请访问：github.com/runwayml/avatars-sdk-react