문의하기 (구버전) 로그인 로그인

웹 위젯 설치 가이드

최종 수정: 2026. 1. 12.

웹 위젯 설치 가이드

Cloudturing 챗봇을 웹사이트에 설치하는 방법을 단계별로 안내합니다.

1. 설치 코드 확인

설치 코드 위치

  1. 콘솔에서 해당 챗봇으로 이동합니다.
  2. 왼쪽 메뉴에서 [기본 설정] 을 선택합니다.
  3. 챗봇 설치 연결 섹션에서 [웹 챗봇 (위젯)] 탭을 클릭합니다.
  4. 표시된 JavaScript 코드를 복사합니다.

설치 코드 예시

<script>
    (function (d, s, id) {
        var js,
            fjs = d.getElementsByTagName(s)[0];
        if (d.getElementById(id)) return;
        js = d.createElement(s);
        js.id = id;
        js.src = "https://app.cloudturing.com/widget/code.js";
        js.onload = function () {
            CloudTuringChatbot.init({ chatbotId: "YOUR_CHATBOT_ID" });
        };
        fjs.parentNode.insertBefore(js, fjs);
    })(document, "script", "cloudturing-chatbot-sdk");
</script>

참고: YOUR_CHATBOT_ID 부분은 콘솔에서 복사한 코드에 해당 챗봇의 고유 ID가 자동으로 채워져 있습니다.

2. 설치 위치

권장 위치

스크립트 코드를 웹사이트 HTML의 </body> 태그 직전에 붙여넣습니다.

<!DOCTYPE html>
<html>
    <head>
        <title>내 웹사이트</title>
    </head>
    <body>
        <!-- 웹사이트 콘텐츠 -->

        <!-- 챗봇 설치 스크립트 (여기에 붙여넣기) -->
        <script>
            (function (d, s, id) {
                // ... 스크립트 코드 ...
            })(document, "script", "cloudturing-chatbot-sdk");
        </script>
    </body>
</html>

3. 설치 코드 동작 원리

기능 설명
비동기 로딩 페이지 로딩을 차단하지 않고 백그라운드에서 로드됩니다.
중복 방지 이미 로드된 경우 다시 로드하지 않습니다.
자동 초기화 스크립트 로드 완료 후 자동으로 챗봇 위젯이 표시됩니다.

성능: 비동기 로딩 방식이므로 웹사이트 성능에 영향을 주지 않습니다.

4. 초기화 옵션

CloudTuringChatbot.init() 함수에 전달되는 옵션입니다.

필수 옵션

옵션 타입 설명
chatbotId String 챗봇의 고유 식별자 (콘솔에서 자동 제공)

설치 확인 방법

  1. 스크립트를 삽입한 웹페이지를 브라우저에서 열어봅니다.
  2. 화면 우측 하단(또는 설정한 위치)에 챗봇 런처 버튼이 표시되면 성공입니다.
  3. 버튼을 클릭하여 챗봇이 정상적으로 동작하는지 확인합니다.

5. 플랫폼별 설치 가이드

WordPress

  1. 관리자 페이지에서 외모 > 테마 파일 편집기로 이동합니다.
  2. footer.php 파일을 선택합니다.
  3. </body> 태그 직전에 스크립트 코드를 붙여넣습니다.
  4. 파일 업데이트 버튼을 클릭합니다.

또는 플러그인 사용:

  • Insert Headers and Footers 플러그인 설치
  • Footer 영역에 스크립트 코드 붙여넣기

Shopify

  1. 관리자 페이지에서 온라인 스토어 > 테마로 이동합니다.
  2. 작업 > 코드 편집을 클릭합니다.
  3. theme.liquid 파일에서 </body> 태그를 찾습니다.
  4. 태그 직전에 스크립트 코드를 붙여넣습니다.

Wix

  1. 사이트 편집기에서 설정 > 사용자 지정 코드로 이동합니다.
  2. + 사용자 지정 코드 추가를 클릭합니다.
  3. 코드 유형: 본문 - 끝을 선택합니다.
  4. 스크립트 코드를 붙여넣고 적용합니다.

일반 HTML 사이트

위에서 설명한 대로 </body> 태그 직전에 스크립트 코드를 삽입합니다.

6. 문제 해결

챗봇이 표시되지 않는 경우

원인 해결 방법
스크립트 위치 오류 </body> 태그 직전에 정확히 삽입되었는지 확인
chatbotId 오류 콘솔에서 복사한 ID가 정확한지 확인
캐시 문제 브라우저 캐시를 삭제하고 새로고침
스크립트 충돌 다른 JavaScript와 충돌이 없는지 확인

브라우저 콘솔 확인

  1. 웹페이지에서 F12 키를 눌러 개발자 도구를 엽니다.
  2. Console 탭에서 오류 메시지가 있는지 확인합니다.
  3. 오류가 있다면 해당 내용을 고객센터에 문의해 주세요.

참고사항

  • 설치된 챗봇의 디자인과 기능은 콘솔의 [디자인 관리] 에서 언제든지 변경할 수 있습니다.
  • 변경 사항 적용 후 [디자인 저장하기] 를 클릭하면 웹사이트에 즉시 반영됩니다.
  • 별도의 코드 수정 없이 콘솔에서 모든 설정을 관리할 수 있습니다.

7. 고급 기능 (개발자용)

콘솔에서 제공하는 기본 설정 외에, 스크립트 초기화 시 추가 옵션을 전달하여 챗봇을 더욱 세밀하게 커스터마이징할 수 있습니다.

주의: 이 기능은 개발자를 위한 고급 옵션입니다. 대부분의 설정은 콘솔의 [디자인 관리]에서 GUI로 편리하게 변경할 수 있습니다.

고급 옵션 사용 예시

<script>
    (function (d, s, id) {
        var js,
            fjs = d.getElementsByTagName(s)[0];
        if (d.getElementById(id)) return;
        js = d.createElement(s);
        js.id = id;
        js.src = "https://app.cloudturing.com/widget/code.js";
        js.onload = function () {
            CloudTuringChatbot.init({
                chatbotId: "YOUR_CHATBOT_ID",
                // 고급 옵션 (선택)
                launcher: {
                    useLauncherPopup: false,
                    position: {
                        bottom: 50,
                        right: 50
                    }
                }
            });
        };
        fjs.parentNode.insertBefore(js, fjs);
    })(document, "script", "cloudturing-chatbot-sdk");
</script>

커스터마이징 가능한 옵션

런처 설정 (launcher)

옵션 타입 기본값 설명
useLauncherPopup Boolean true 시작 팝업 표시 여부
position.bottom Number 30 하단 여백 (px)
position.right Number 30 우측 여백 (px)
position.left Number - 좌측 여백 (px, right 대신 사용)
position.top Number - 상단 여백 (px, bottom 대신 사용)

시작 팝업 설정 (launcher.welcomePopup)

옵션 타입 기본값 설명
title String "안녕하세요. 무엇을 도와드릴까요?" 팝업 제목
subtitle String "아래 채팅 버튼을 눌러주세요 😊" 팝업 부제목
ctaText String - CTA 버튼 텍스트
ctaLink String - CTA 버튼 클릭 시 이동할 URL

챗봇 기본 정보 (chatbot)

옵션 타입 기본값 설명
chatHeaderTitle String "챗봇" 채팅창 헤더에 표시되는 이름

챗봇 목록 화면 (chatListScreen)

옵션 타입 기본값 설명
headerImageUrl String 기본 이미지 목록 화면 상단 헤더 이미지 URL
chatbots Array - 목록에 표시할 챗봇 배열

여러 챗봇 표시 (chatListScreen.chatbots)

하나의 런처에서 여러 챗봇(튜링봇, 카카오톡 등)을 함께 표시할 수 있습니다.

chatbots 배열 설정 예시
CloudTuringChatbot.init({
    chatbotId: "YOUR_CHATBOT_ID", // 기본 챗봇 ID
    chatListScreen: {
        chatbots: [
            // 튜링 AI 챗봇 1 - 제품 상담용
            {
                type: "turing",
                chatbotId: "PRODUCT_CHATBOT_ID", // 개별 챗봇 ID
                subtitle: "제품 문의 및 고객 상담"
            },
            // 튜링 AI 챗봇 2 - 기술 지원용
            {
                type: "turing",
                chatbotId: "SUPPORT_CHATBOT_ID", // 개별 챗봇 ID
                subtitle: "기술 지원 및 A/S 접수"
            },
            // 카카오톡 채널 1
            {
                type: "kakao",
                subtitle: "카카오톡 일반 상담",
                href: "https://pf.kakao.com/_general/chat"
            },
            // 카카오톡 채널 2 (다른 채널)
            {
                type: "kakao",
                subtitle: "카카오톡 VIP 전용 상담",
                href: "https://pf.kakao.com/_vip/chat"
            }
        ]
    }
});

참고: 같은 타입의 챗봇을 여러 개 추가할 수 있습니다. turing 타입은 각각 다른 chatbotId로 서로 다른 AI 챗봇을 연결하고, subtitle로 용도를 구분합니다.

chatbots 항목 옵션
옵션 타입 필수 설명
type String ✅ 챗봇 타입 (turing 또는 kakao)
chatbotId String ✅ (turing) 개별 챗봇 ID (turing 타입 필수)
subtitle String - 챗봇 카드 아래 표시되는 설명 문구
href String - 클릭 시 이동할 URL (kakao 타입에 필수)
지원 챗봇 타입
타입 설명 동작
turing Cloudturing AI 챗봇 채팅 화면으로 이동
kakao 카카오톡 채널 설정된 URL로 이동 (새 탭)

위치 설정 조합

런처 버튼의 위치는 position 객체의 속성 조합으로 결정됩니다:

위치 설정 예시
우측 하단 (기본값) { bottom: 30, right: 30 }
좌측 하단 { bottom: 30, left: 30 }
우측 상단 { top: 30, right: 30 }
좌측 상단 { top: 30, left: 30 }

옵션 우선순위

옵션은 다음 순서로 병합되며, 뒤에 오는 값이 우선 적용됩니다:

  1. 기본값 - 시스템 기본 설정
  2. 콘솔 설정 - 콘솔의 [디자인 관리]에서 저장한 값
  3. 스크립트 옵션 - init() 함수에 직접 전달한 값

팁: 대부분의 경우 콘솔에서 설정을 관리하는 것이 편리합니다. 스크립트 옵션은 특수한 요구사항이 있을 때만 사용하세요.