--- title: "CDN / 스크립트 태그" description: "번들러 없이 모든 웹사이트에 ThunderPhone 음성 위젯을 추가합니다" --- CDN 빌드는 React를 내부적으로 번들링하므로 정적 사이트, WordPress, Webflow 또는 HTML을 추가할 수 있는 모든 페이지에서 위젯을 사용할 수 있습니다. npm, 번들러, 프레임워크가 필요하지 않습니다. ## CDN URL ```html Latest (recommended) ``` ```html Pinned version ``` `latest` URL은 대시보드의 임베드 스니펫 생성기가 만드는 URL입니다. 5분간 캐시되며 새 안정 릴리스를 자동으로 반영합니다. 고정된 `/widget/vX.Y.Z/` 경로는 변경할 수 없으며 장기간 캐시됩니다. 고정하는 경우 개발에 사용하는 `@thunderphone/widget` npm 릴리스와 버전을 일치시키십시오. --- ## 기본 사용법 ```html

``` 위젯은 대상 요소에 마운트되며 **뷰포트 모서리에 고정 위치 바**로 렌더링됩니다(기본값은 `bottom-right`이며 `position` 옵션으로 제어됨). 마운트 요소는 React 루트일 뿐이며, 페이지 내 위치는 위젯이 표시되는 위치에 영향을 주지 않습니다. --- ## 마운트 옵션 `ThunderPhone.mount()`는 React 컴포넌트와 동일한 옵션에 `element` 속성을 추가하여 지원합니다. | 옵션 | 유형 | 필수 | 기본값 | 설명 | |--------|------|----------|---------|-------------| | `element` | `string \| HTMLElement` | 예 | -- | CSS 선택자(예: `'#thunderphone'`) 또는 DOM 요소 참조입니다. | | `publishableKey` | `string` | 예 | -- | 게시 가능 API 키(`pk_live_...`)입니다. 에이전트는 키의 위젯 구성에서 자동으로 확인됩니다. | | `theme` | `'light' \| 'dark'` | 아니요 | `'light'` | 색상 구성표입니다. | | `primaryColor` | `string` | 아니요 | `'#000000'` (light) / `'#ffffff'` (dark) | 강조 색상으로 사용되는 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` 등의 언어 코드 또는 로캘을 지정합니다. 설정하지 않으면 에이전트에 구성된 언어가 적용됩니다. 키의 [브라우저 재정의](/ko/guides/embed-web-widget)에서 `language`가 필요합니다. | | `voice` | `string` | 아니요 | -- | 세션별 음성 재정의입니다. `maria`와 같은 음성 이름을 지정합니다. 설정하지 않으면 에이전트에 구성된 음성이 적용됩니다. 키의 [브라우저 재정의](/ko/guides/embed-web-widget)에서 `voice`가 필요합니다. | | `context` | `string` | 아니요 | -- | 에이전트에 전달되는 세션별 사실 기반 페이지 또는 사이트 컨텍스트입니다. 서버 측에서 12,000자로 잘립니다. 키의 [브라우저 재정의](/ko/guides/embed-web-widget)에서 `context`가 필요합니다. | | `onConnect` | `() => void` | 아니요 | -- | 음성 세션이 연결되면 호출됩니다. | | `onDisconnect` | `() => void` | 아니요 | -- | 세션이 종료되면 호출됩니다. | | `onError` | `(error) => void` | 아니요 | -- | 오류 발생 시 호출됩니다. 오류에는 `error`(코드) 및 `message` 필드가 있습니다. | | `ringtone` | `boolean \| string` | 아니요 | `false` | 연결하는 동안 벨소리를 재생합니다. 기본 벨소리는 `true`를 사용하고, 사용자 지정 오디오는 URL 문자열을 사용합니다. | --- ## 정리 `ThunderPhone.mount()`는 정리 메서드를 포함하는 위젯 인스턴스를 반환합니다. ```html ``` `unmount()`와 `destroy()`는 동일하게 작동합니다. 활성 음성 세션의 연결을 해제하고 DOM에서 위젯을 제거합니다. 코드에서 더 자연스럽게 읽히는 메서드를 사용합니다. 단일 페이지 애플리케이션에서 다른 페이지로 이동하거나 포함 요소가 제거될 때는 항상 위젯을 정리합니다. 이렇게 하면 활성 음성 세션의 연결이 올바르게 해제됩니다. --- ## 예시 ### 사용자 지정 색상의 다크 테마 ```html

``` ### 사용자 지정 위치 ```html

``` ### 이벤트 콜백 사용 ```html

``` ### 벨소리 사용 ```html

``` ### DOM 요소 참조 사용 ```html

``` ### WordPress / CMS 통합 사용자 지정 HTML 블록 또는 테마의 푸터에 다음을 추가합니다. ```html ``` `

`는 어디에나 배치할 수 있으며 마운트 지점일 뿐입니다. 위젯 자체는 뷰포트 모서리에 고정 오버레이로 렌더링되며(`position` 옵션으로 설정), 주변 콘텐츠의 흐름에 영향을 받지 않습니다. --- ## 문제 해결 CSS 및 JS 파일이 모두 로드되었는지 확인합니다. 브라우저 콘솔에서 네트워크 오류를 확인합니다. `ThunderPhone.mount()`를 호출하기 전에 대상 요소가 DOM에 있는지 확인합니다. 스크립트가 아직 로드되지 않았습니다. `widget.js`의 `