React 컴포넌트 - ThunderPhone

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

설치

npm install @thunderphone/widget

기본 사용법

import { ThunderPhoneWidget } from '@thunderphone/widget'
import '@thunderphone/widget/style.css'

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

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

속성

컴포넌트는 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 문자열을 사용합니다.

예시

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

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

사용자 지정 위치

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)으로 전달되며, 해당 세션에 대해 에이전트에 구성된 기본값을 재정의합니다.

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자로 잘립니다.

이벤트 콜백 사용

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

사용자 지정 스타일 적용

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

.my-custom-widget .tp-button--end {
  background-color: #e74c3c;
}

사용 가능한 모든 CSS 클래스와 사용자 지정 속성은 스타일링 가이드를 참조하십시오.

벨소리 사용

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

import { ThunderPhoneWidget } from '@thunderphone/widget'
import '@thunderphone/widget/style.css'

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

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

<ThunderPhoneWidget
  publishableKey="pk_live_your_publishable_key"
  ringtone="https://example.com/my-ringtone.mp3"
/>

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

사용자 지정 API Base 사용

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

<ThunderPhoneWidget
  publishableKey="pk_live_your_publishable_key"
  apiBase="https://your-proxy.example.com/v1"
/>

오류 처리

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

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

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

다음 단계

헤드리스 Hook

UI를 완전히 제어해야 하나요? 대신 useThunderPhone Hook을 사용하세요.

스타일링

CSS 사용자 지정 속성으로 색상, 크기, 레이아웃을 맞춤 설정하세요.

​설치

​기본 사용법

​속성

​예시

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

​사용자 지정 위치

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

​이벤트 콜백 사용

​사용자 지정 스타일 적용

​벨소리 사용

​사용자 지정 API Base 사용

​오류 처리

​다음 단계

헤드리스 Hook

스타일링

설치

기본 사용법

속성

예시

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

사용자 지정 위치

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

이벤트 콜백 사용

사용자 지정 스타일 적용

벨소리 사용

사용자 지정 API Base 사용

오류 처리

다음 단계