React 컴포넌트

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

속성

컴포넌트는 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 사용

<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 사용자 지정 속성으로 색상, 크기, 레이아웃을 맞춤 설정하세요.