--- type: how-to title: 클라이언트 측 연동 summary: CDN 스크립트 태그로든 npm 임포트로든 위젯을 페이지에 올리는 방법, 그리고 어느 쪽을 쓸지. --- 위젯은 작은 패키지 하나, `@caputchin/widget`이며, ``과 `` 커스텀 요소를 등록합니다. 그것을 페이지에 올리는 방법은 두 가지입니다. 당신의 사이트에 빌드 단계가 있는지로 고르세요. 키가 게임을 요구할 때 두 요소는 서로 바꿔 쓸 수 없습니다. 사이트 키가 게임 게이트를 켰다면(그 **검증에 게임 요구** 설정), 체크박스 ``은 그 위에서 통과하지 못하고 `gate-unavailable` 오류를 일으킵니다; 거기서는 ``만 동작합니다. 이것은 의도된 것으로, 게이트가 Caputchin 쪽에서 강제되기 때문입니다. [게임 게이트](/docs/site-keys/games)를 보세요. ## 스크립트 태그 (CDN) 빌드 단계가 없고, 순수 HTML 또는 서버에서 렌더링되는 페이지인가요? jsDelivr CDN에서 곧장 로드하세요: ```html ``` `@3`은 현재 메이저 버전을 고정하니, 놀랄 만한 브레이킹 체인지 없이 수정과 새 게임을 받습니다. 그 한 줄을 ``(또는 `` 바로 앞)에 넣으면 요소가 페이지 전체에 등록됩니다. ## npm (ESM) 번들러(Vite, webpack, Next.js 등)가 있나요? 패키지를 설치하고 시작할 때 한 번 임포트하세요: ```bash npm install @caputchin/widget ``` ```js import "@caputchin/widget"; ``` 임포트는 호출할 무언가를 내놓지 않습니다; 커스텀 요소를 등록하는 부수 효과를 위해 실행됩니다. 어떤 ``이 렌더링되기 전에 실행되도록, 앱 진입점에 두세요. ## 어느 쪽? - **빌드 단계 없음**(순수 HTML, 서버에서 렌더링되는 템플릿): **스크립트 태그**를 쓰세요. 한 줄로 끝나는 연동 전체입니다. - **번들된 앱**(React, Vue 등): **npm 임포트**를 쓰세요. 당신의 락파일과 함께 버전이 관리되고, 렌더링을 막는 외부 요청을 피합니다. 어느 쪽이든 요소와 그 아래의 모든 것(주입된 토큰, 당신의 서버 확인)은 동일합니다. 달라지는 단 하나는 패키지가 도착하는 방식뿐입니다. ## 함께 보기 - 각 프레임워크에서의 요소는 [프런트엔드 연동 예제](/docs/integration-guides/frontend-examples). - 전체 안내는 [당신의 사이트에 위젯 추가하기](/docs/getting-started/add-the-widget).