React Native SDK | ElevenLabs Documentation

ElevenAgents의 작동 방식을 알아보려면 ElevenAgents 개요를 참조하세요.

설치

React Native 프로젝트에 패키지와 종속성을 설치하세요.

npm install @elevenlabs/react-native @livekit/react-native @livekit/react-native-webrtc livekit-client

Expo와 함께 이 SDK를 사용하는 예제 앱은 여기에서 확인할 수 있습니다.

이전 버전에서 업그레이드하시나요? npx skills add elevenlabs/packages를 실행하여 AI 코딩 에이전트용 elevenlabs:sdk-migration 스킬을 설치하세요. 이 스킬은 import 변경, ConversationProvider 래핑, API 업데이트를 자동화합니다.

요구 사항

LiveKit 종속성이 포함된 React Native
플랫폼에 맞게 구성된 마이크 권한
Expo 호환성(개발 빌드 전용)
React Native 0.79.0 이상 또는 이전 버전에서 package.json의 "exports"를 확인하도록 구성된 Metro

이 SDK는 Expo 프레임워크에서 사용하도록 설계 및 개발되었습니다. LiveKit의 WebRTC 구현에 의존하므로 개발 빌드가 필요하며 Expo Go에서는 사용할 수 없습니다.

@elevenlabs/react-native는 package.json의 "exports" 필드를 통해 React Native 진입점을 확인합니다. Metro는 React Native 0.79.0(2025년 4월 8일 출시)에 포함된 Metro 0.82.0부터 기본적으로 "exports"를 확인합니다. React Native 버전이 0.79보다 이전이라면, 이 패키지가 올바르게 확인되도록 metro.config.js에서 resolver.unstable_enablePackageExports = true로 설정하세요.

const { getDefaultConfig } = require("metro-config");
const config = getDefaultConfig(__dirname);
config.resolver.unstable_enablePackageExports = true;
module.exports = config;

설정

Provider 설정

ConversationProvider로 앱을 감싸 ElevenAgents 기능을 활성화하세요.

import { ConversationProvider } from "@elevenlabs/react-native";
import React from "react";
function App() {
  return (
    <ConversationProvider>
      <YourAppComponents />
    </ConversationProvider>
  );
}

@elevenlabs/react-native는 @elevenlabs/react의 ConversationProvider와 모든 훅을 다시 내보냅니다. API는 웹 React SDK와 동일합니다. 전체 API 레퍼런스는 React SDK 문서를 참조하세요.

사용 방법

React SDK의 모든 훅은 @elevenlabs/react-native에서 사용할 수 있습니다.

useConversation — 모든 상태와 메서드를 결합한 편의 훅
useConversationControls — 작업 메서드(startSession, endSession 등)
useConversationStatus — 연결 상태
useConversationInput — 음소거 상태
useConversationMode — 말하기/듣기 상태
useConversationFeedback — 피드백 제공 가능 여부 및 제출
useConversationClientTool — 동적 클라이언트 도구 등록
useRawConversation — 원시 대화 인스턴스

대화 시작

import { useConversationControls, useConversationStatus } from "@elevenlabs/react-native";
import React from "react";
import { View, Text, Button } from "react-native";
function ConversationComponent() {
  const { startSession, endSession } = useConversationControls();
  const { status } = useConversationStatus();
  const handleStart = async () => {
    await startSession({
      agentId: "agent_7101k5zvyjhmfg983brhmhkd98n6",
    });
  };
  return (
    <View>
      <Text>Status: {status}</Text>
      <Button
        title={status === "connected" ? "End" : "Start"}
        onPress={status === "connected" ? endSession : handleStart}
      />
    </View>
  );
}

비공개 에이전트, 인증, 클라이언트 도구, 오버라이드 및 기타 모든 기능은 React SDK 문서를 참조하세요.

구현 예시

ElevenLabs Agents SDK를 사용하는 React Native 컴포넌트의 전체 예시입니다.

import { ConversationProvider, useConversation } from "@elevenlabs/react-native";
import React, { useState } from "react";
import { View, Text, TouchableOpacity, StyleSheet } from "react-native";
function ConversationScreen() {
  const [isConnected, setIsConnected] = useState(false);
  const conversation = useConversation({
    onConnect: () => {
      console.log("Connected to conversation");
      setIsConnected(true);
    },
    onDisconnect: () => {
      console.log("Disconnected from conversation");
      setIsConnected(false);
    },
    onMessage: (message) => {
      console.log("Message received:", message);
    },
    onError: (error) => {
      console.error("Conversation error:", error);
    },
  });
  const startConversation = async () => {
    try {
      await conversation.startSession({
        agentId: "agent_7101k5zvyjhmfg983brhmhkd98n6",
      });
    } catch (error) {
      console.error("Failed to start conversation:", error);
    }
  };
  const endConversation = async () => {
    try {
      await conversation.endSession();
    } catch (error) {
      console.error("Failed to end conversation:", error);
    }
  };
  return (
    <View style={styles.container}>
      <Text style={styles.status}>Status: {conversation.status}</Text>
      <Text style={styles.speaking}>
        Agent is {conversation.isSpeaking ? "speaking" : "not speaking"}
      </Text>
      <TouchableOpacity
        style={[styles.button, isConnected && styles.buttonActive]}
        onPress={isConnected ? endConversation : startConversation}
      >
        <Text style={styles.buttonText}>
          {isConnected ? "End Conversation" : "Start Conversation"}
        </Text>
      </TouchableOpacity>
      {conversation.canSendFeedback && (
        <View style={styles.feedbackContainer}>
          <TouchableOpacity
            style={styles.feedbackButton}
            onPress={() => conversation.sendFeedback(true)}
          >
            <Text>👍</Text>
          </TouchableOpacity>
          <TouchableOpacity
            style={styles.feedbackButton}
            onPress={() => conversation.sendFeedback(false)}
          >
            <Text>👎</Text>
          </TouchableOpacity>
        </View>
      )}
    </View>
  );
}
function App() {
  return (
    <ConversationProvider>
      <ConversationScreen />
    </ConversationProvider>
  );
}
const styles = StyleSheet.create({
  container: {
    flex: 1,
    justifyContent: "center",
    alignItems: "center",
    padding: 20,
  },
  status: {
    fontSize: 16,
    marginBottom: 10,
  },
  speaking: {
    fontSize: 14,
    marginBottom: 20,
    color: "#666",
  },
  button: {
    backgroundColor: "#007AFF",
    paddingHorizontal: 20,
    paddingVertical: 10,
    borderRadius: 8,
    marginBottom: 20,
  },
  buttonActive: {
    backgroundColor: "#FF3B30",
  },
  buttonText: {
    color: "white",
    fontSize: 16,
    fontWeight: "600",
  },
  feedbackContainer: {
    flexDirection: "row",
    gap: 10,
  },
  feedbackButton: {
    backgroundColor: "#F2F2F7",
    padding: 10,
    borderRadius: 8,
  },
});
export default App;

플랫폼별 고려 사항

iOS

Info.plist에서 마이크 권한이 올바르게 구성되었는지 확인하세요.

<key>NSMicrophoneUsageDescription</key>
<string>This app needs microphone access to enable voice conversations with AI agents.</string>

Android

android/app/src/main/AndroidManifest.xml에 마이크 권한을 추가하세요.

<uses-permission android:name="android.permission.RECORD_AUDIO" />

대화를 시작하기 전에 런타임 권한을 요청하는 것이 좋습니다.

import { PermissionsAndroid, Platform } from "react-native";
const requestMicrophonePermission = async () => {
  if (Platform.OS === "android") {
    const granted = await PermissionsAndroid.request(PermissionsAndroid.PERMISSIONS.RECORD_AUDIO, {
      title: "Microphone Permission",
      message: "This app needs microphone access to enable voice conversations.",
      buttonNeutral: "Ask Me Later",
      buttonNegative: "Cancel",
      buttonPositive: "OK",
    });
    return granted === PermissionsAndroid.RESULTS.GRANTED;
  }
  return true;
};