> ## Documentation Index
> Fetch the complete documentation index at: https://docs.thunderphone.com/llms.txt
> Use this file to discover all available pages before exploring further.

# React 컴포넌트

> React 애플리케이션에 ThunderPhone 음성 위젯을 임베드합니다

`ThunderPhoneWidget` 컴포넌트는 음소거, 통화 종료, 연결 상태 표시를 위한 기본 제공 컨트롤이 포함된 글래스모피즘 통화 바를 렌더링합니다. React 앱에 음성 AI를 추가하는 가장 빠른 방법입니다.

## 설치

```bash theme={null}
npm install @thunderphone/widget
```

## 기본 사용법

```tsx theme={null}
import { ThunderPhoneWidget } from '@thunderphone/widget'
import '@thunderphone/widget/style.css'

function App() {
  return (
    <ThunderPhoneWidget
      publishableKey="pk_live_your_publishable_key"
    />
  )
}
```

<Warning>
  위젯이 올바르게 렌더링되도록 CSS 파일을 **반드시** 가져와야 합니다. 가져오지 않으면 위젯에 스타일이 적용되지 않습니다.
</Warning>

***

## 속성

컴포넌트는 `ThunderPhoneWidgetProps`를 통해 다음 속성을 받습니다.

| 속성               | 유형                                                             | 필수  | 기본값                                  | 설명                                                                                       |
| ---------------- | -------------------------------------------------------------- | --- | ------------------------------------ | ---------------------------------------------------------------------------------------- |
| `publishableKey` | `string`                                                       | 예   | --                                   | 개발자 설정의 공개 API 키(`pk_live_...`)입니다. 키의 위젯 구성에 따라 에이전트가 자동으로 확인됩니다.                       |
| `theme`          | `'light' \| 'dark'`                                            | 아니요 | `'light'`                            | 색상 구성표입니다. 위젯 루트에 `tp--light` 또는 `tp--dark` 클래스를 적용합니다.                                  |
| `primaryColor`   | `string`                                                       | 아니요 | `'#000000'` (라이트) / `'#ffffff'` (다크) | 강조 색상으로 사용되는 CSS 색상 문자열입니다(통화 버튼, 파형, 활성 표시기).                                           |
| `title`          | `string`                                                       | 아니요 | `'Voice assistant'`                  | 위젯 바에 표시되는 텍스트입니다.                                                                       |
| `position`       | `'bottom-right' \| 'bottom-left' \| 'top-right' \| 'top-left'` | 아니요 | `'bottom-right'`                     | 위젯의 고정 뷰포트 위치입니다.                                                                        |
| `apiBase`        | `string`                                                       | 아니요 | `'https://api.thunderphone.com/v1'`  | API 기본 URL을 재정의합니다.                                                                      |
| `language`       | `string`                                                       | 아니요 | --                                   | 세션별 언어 재정의입니다. `en`, `es`, `fr-FR`과 같은 언어 코드 또는 로캘을 사용합니다. 설정하지 않으면 에이전트에 구성된 언어가 적용됩니다. |
| `voice`          | `string`                                                       | 아니요 | --                                   | 세션별 음성 재정의입니다. `maria`와 같은 음성 이름을 사용합니다. 설정하지 않으면 에이전트에 구성된 음성이 적용됩니다.                   |
| `context`        | `string`                                                       | 아니요 | --                                   | 에이전트에 전달되는 세션별 사실 기반 페이지 또는 사이트 컨텍스트입니다(예: 방문자가 보고 있는 페이지의 세부 정보). 서버 측에서 12,000자로 잘립니다. |
| `onConnect`      | `() => void`                                                   | 아니요 | --                                   | 음성 세션이 성공적으로 연결되면 호출됩니다.                                                                 |
| `onDisconnect`   | `() => void`                                                   | 아니요 | --                                   | 세션이 종료되면 호출됩니다.                                                                          |
| `onError`        | `(error) => void`                                              | 아니요 | --                                   | 오류 발생 시 호출됩니다. `error` 객체에는 `error`(코드) 및 `message` 필드가 있습니다.                            |
| `className`      | `string`                                                       | 아니요 | --                                   | 위젯 컨테이너에 적용되는 추가 CSS 클래스 이름입니다.                                                          |
| `ringtone`       | `boolean \| string`                                            | 아니요 | `false`                              | 연결하는 동안 벨소리를 재생합니다. 기본 벨소리는 `true`를 사용하고, 사용자 지정 오디오는 URL 문자열을 사용합니다.                    |

***

## 예시

### 사용자 지정 색상이 적용된 다크 테마

```tsx theme={null}
import { ThunderPhoneWidget } from '@thunderphone/widget'
import '@thunderphone/widget/style.css'

function App() {
  return (
    <ThunderPhoneWidget
      publishableKey="pk_live_your_publishable_key"
      theme="dark"
      primaryColor="#8b5cf6"
      title="Talk to our AI"
    />
  )
}
```

### 사용자 지정 위치

```tsx theme={null}
import { ThunderPhoneWidget } from '@thunderphone/widget'
import '@thunderphone/widget/style.css'

function App() {
  return (
    <ThunderPhoneWidget
      publishableKey="pk_live_your_publishable_key"
      position="bottom-left"
    />
  )
}
```

### 세션별 언어, 음성 및 컨텍스트

통화가 시작되면 `language`, `voice`, `context` prop이 세션 요청(`POST /widget/session`)으로 전달되며, 해당 세션에 대해 에이전트에 구성된 기본값을 재정의합니다.

```tsx theme={null}
import { ThunderPhoneWidget } from '@thunderphone/widget'
import '@thunderphone/widget/style.css'

function PricingPageWidget() {
  return (
    <ThunderPhoneWidget
      publishableKey="pk_live_your_publishable_key"
      language="es"
      voice="maria"
      context="Page: Pricing. Plans: Starter $29/mo, Pro $99/mo. Annual billing saves 20%."
    />
  )
}
```

`context`를 사용하여 방문자가 보고 있는 페이지에 대한 사실 기반 정보를 에이전트에 제공합니다. 여기에는 제품 세부 정보, 가격 또는 페이지별 FAQ가 포함될 수 있습니다. 서버 측에서 최대 12,000자로 잘립니다.

### 이벤트 콜백 사용

```tsx theme={null}
import { ThunderPhoneWidget } from '@thunderphone/widget'
import '@thunderphone/widget/style.css'

function SupportWidget() {
  return (
    <ThunderPhoneWidget
      publishableKey="pk_live_your_publishable_key"
      onConnect={() => {
        console.log('Voice session connected')
        analytics.track('widget_call_started')
      }}
      onDisconnect={() => {
        console.log('Voice session ended')
        analytics.track('widget_call_ended')
      }}
      onError={(error) => {
        console.error(`Widget error: ${error.error} - ${error.message}`)
      }}
    />
  )
}
```

### 사용자 지정 스타일 적용

```tsx theme={null}
import { ThunderPhoneWidget } from '@thunderphone/widget'
import '@thunderphone/widget/style.css'

function BrandedWidget() {
  return (
    <ThunderPhoneWidget
      publishableKey="pk_live_your_publishable_key"
      primaryColor="#4a90d9"
      className="my-custom-widget"
    />
  )
}
```

```css theme={null}
.my-custom-widget .tp-button--end {
  background-color: #e74c3c;
}
```

사용 가능한 모든 CSS 클래스와 사용자 지정 속성은 [스타일링 가이드](/ko/widget/styling)를 참조하십시오.

### 벨소리 사용

연결이 설정되는 동안 전화 벨소리를 재생합니다.

```tsx theme={null}
import { ThunderPhoneWidget } from '@thunderphone/widget'
import '@thunderphone/widget/style.css'

function PhoneWidget() {
  return (
    <ThunderPhoneWidget
      publishableKey="pk_live_your_publishable_key"
      ringtone={true}
    />
  )
}
```

오디오 파일 URL을 전달하여 사용자 지정 벨소리를 사용합니다.

```tsx theme={null}
<ThunderPhoneWidget
  publishableKey="pk_live_your_publishable_key"
  ringtone="https://example.com/my-ringtone.mp3"
/>
```

위젯이 `connecting` 상태인 동안 벨소리가 반복 재생되며, 에이전트가 연결되면 부드럽게 페이드아웃됩니다.

### 사용자 지정 API Base 사용

<Tip>
  자체 호스팅 또는 프록시 API 엔드포인트를 사용하는 경우에만 `apiBase`를 설정하면 됩니다. 기본값은 `https://api.thunderphone.com/v1`을 가리킵니다.
</Tip>

```tsx theme={null}
<ThunderPhoneWidget
  publishableKey="pk_live_your_publishable_key"
  apiBase="https://your-proxy.example.com/v1"
/>
```

***

## 오류 처리

`onError` 콜백이 실행되면 두 개의 필드가 포함된 오류 객체를 수신합니다.

| 필드        | 유형       | 설명                |
| --------- | -------- | ----------------- |
| `error`   | `string` | 기계가 읽을 수 있는 오류 코드 |
| `message` | `string` | 사람이 읽을 수 있는 오류 설명 |

일반적인 오류 코드에는 허용되지 않는 도메인, 에이전트를 찾을 수 없음, 유효하지 않은 API 키가 포함됩니다.

***

## 다음 단계

<CardGroup cols={2}>
  <Card title="헤드리스 Hook" icon="code" href="/ko/widget/headless-hook">
    UI를 완전히 제어해야 하나요? 대신 `useThunderPhone` Hook을 사용하세요.
  </Card>

  <Card title="스타일링" icon="palette" href="/ko/widget/styling">
    CSS 사용자 지정 속성으로 색상, 크기, 레이아웃을 맞춤 설정하세요.
  </Card>
</CardGroup>