rw-integrate-character-embed

React にキャラクターを埋め込む（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 アプリケーションにリアルタイムのアバタービデオ通話を埋め込みます。

インストール

npm install @runwayml/avatars-react

これはクライアントサイドのパッケージです。サーバーサイドの @runwayml/sdk は、+rw-integrate-characters でインストール済みである必要があります。

オプション A：シンプル — AvatarCall コンポーネント

キャラクターを埋め込む最も手軽な方法です。WebRTC 接続を処理し、デフォルトの UI を自動的に描画します。

'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

Prop	型	説明
avatarId	string	Developer Portal または API から取得したアバターの UUID
connectUrl	string	サーバーサイドのセッションエンドポイント（例：/api/avatar/session）
onEnd	() => void	通話が正常に終了したときに呼び出されます
onError	(error: Error) => void	接続エラーまたは実行時エラーが発生したときに呼び出されます

Developer Portal で作成したカスタムアバターには、アバターの UUID を avatarId として使用してください。

オプション B：完全カスタム — フック

UI を完全に制御するには、フックとともに AvatarSession を使用します。

コンポーネントとフック

エクスポート	型	説明
AvatarSession	コンポーネント	WebRTC セッションを管理するプロバイダー
AvatarVideo	コンポーネント	アバターのビデオストリームを描画します
UserVideo	コンポーネント	ユーザーのカメラ映像を描画します
useAvatarSession	フック	セッションの状態にアクセスします：state、sessionId、error、end()
useLocalMedia	フック	ユーザーのメディアを制御します：isMicEnabled、toggleMic()

カスタム UI の例

'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>
  );
}

カスタム UI 用の認証情報の取得

フックを使用する場合は、サーバーエンドポイントから認証情報を取得し、AvatarSession に渡す必要があります。

'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>
  );
}

統合パターン

Next.js App Router（完全な例）

サーバールート（app/api/avatar/session/route.ts）： サーバーサイドでのセッション作成コードの全体は、+rw-integrate-characters を参照してください。

クライアントページ（app/character/page.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>
  );
}

条件付きレンダリング（表示／非表示）

'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>
  );
}

エラー処理

詳細なエラーログ

<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);
    }
  }}
/>

セッション状態のデバッグ

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>
  );
}

ブラウザーのサポート

ブラウザー	最低バージョン
Chrome	74+
Firefox	78+
Safari	14.1+
Edge	79+

ユーザーは、求められたときにマイクの使用を許可する必要があります。ユーザーのビデオを有効にする場合は、カメラの使用許可も必要です。

ヒント

• 必ずスタイルをインポートしてください：AvatarCall を使用するときは、import '@runwayml/avatars-react/styles.css' を指定します
• Next.js App Router で React SDK を使用するすべてのコンポーネントには、'use client' ディレクティブが必要です
• セッションの最大時間は 5 分です — onEnd コールバックを処理し、再接続の選択肢を表示してください
• 認証情報は一度だけ使用できます — 接続に失敗した場合は、新しい認証情報を取得してください（新しいセッションを作成します）
• SDK の全ソース、サンプル、課題管理については、github.com/runwayml/avatars-sdk-react を参照してください