Quickstart

위젯 개요

위젯 앱은 widget.companin.tech에서 호스팅되며 고객 지원 AI 에이전트를 웹사이트에 포함하는 쉬운 방법을 제공합니다. 시작하려면 에이전트와 OAuth 애플리케이션을 생성해야 합니다.

위젯은 귀하의 웹사이트에서 격리된 iframe에서 실행되는 경량의 독립형 애플리케이션입니다. 이 아키텍처는 위젯이 기존 CSS 또는 JavaScript와 충돌하지 않도록 하면서 우수한 성능과 보안을 유지합니다.

1. 에이전트 생성

먼저 대시보드에서 고객 지원 AI 에이전트를 생성하세요:

귀하의 에이전트는 위젯 뒤에 있는 AI 두뇌입니다. 사용자의 메시지를 처리하고 대화 컨텍스트를 유지하며 지능적인 응답을 생성합니다. 각 에이전트는 특정 지침, 성격 특성 및 지식 기반으로 사용자 사례에 맞게 사용자 정의할 수 있습니다.

1. 대시보드로 이동하여 "데이터 소스" 페이지로 이동하세요.
2. 에이전트 섹션에서 "추가" 버튼을 클릭하세요.
3. 에이전트 세부정보(이름, 설명, 톤 등)를 입력하세요.
4. 에이전트를 저장하고 ID를 기록하세요.

팁: 귀하의 에이전트에게 역할과 제한 사항에 대한 명확하고 구체적인 지침을 제공하세요. 예: "귀하는 SaaS 제품에 대한 유용한 고객 지원 에이전트입니다. 기능, 가격 및 계정 관리에 대한 질문에 답변할 수 있습니다. 기술 문제에 대해서는 사용자가 지원 티켓을 생성하도록 안내하세요."

2. OAuth 애플리케이션 생성

위젯을 인증하기 위해 OAuth 애플리케이션을 생성하세요:

1. 대시보드에서 "OAuth" 페이지로 이동하세요.
2. "애플리케이션 생성"을 클릭하세요.
3. 애플리케이션 이름과 설명을 입력하세요.
4. 생성된 애플리케이션에서 client_id를 복사하세요.

3. Iframe을 통해 위젯 포함

위젯을 통합하는 가장 간단한 방법은 iframe을 사용하여 직접 포함하는 것입니다. 이 방법은 JavaScript 초기화가 필요 없으며 즉시 작동합니다. 하나의 페이지에 여러 iframe을 사용할 경우 각 포함을 고유한 컨테이너 및 매개변수로 제한하세요.

<iframe src="https://widget.companin.tech/embed/session?key=YOUR_WIDGET_KEY&locale=en" style="border:none; width:100%; height:600px; border-radius:8px;" title="Customer Support AI Agent Widget"></iframe>

YOUR_WIDGET_KEY를 위젯의 설치 키(대시보드의 위젯 페이지 또는 설치 페이지에서 복사한 wgt_… 값)로 교체하세요. locale 매개변수는 사이트의 언어와 일치하도록 설정할 수 있습니다.

고급: JavaScript 초기화

추천 통합 방법은 자동 크기 조정, 구성 관리 및 반응형 동작을 제공하는 JavaScript 위젯 로더를 사용하는 것입니다.

스크립트 통합

다음 스크립트 태그를 HTML 페이지에 추가하세요:

<script  src="https://widget.companin.tech/widget.js"  data-widget-key="YOUR_WIDGET_KEY"  data-instance-id="support-widget"  data-locale="en"  data-theme="system"  async></script>

스크립트 속성

각 속성은 위젯을 구성하는 특정 목적을 가지고 있습니다:

• data-widget-key: 귀하의 위젯의 위젯 ID - 대부분의 설치에 필요한 단일 값입니다. 클라이언트, 에이전트 및 구성 서버 측을 해결하므로 별도로 붙여넣지 않습니다.

아래 세 가지 속성은 data-widget-key의 고급 대안입니다 - 특정 클라이언트, 에이전트 또는 구성을 명시적으로 타겟팅해야 하는 다중 인스턴스 설정에 사용하세요:

• data-client-id: 귀하의 OAuth 클라이언트 ID - 이는 귀하의 애플리케이션을 우리의 API와 인증합니다. 귀하의 앱 비밀번호로 생각하세요.
• data-agent-id: 귀하의 에이전트의 UUID - 이는 어떤 고객 지원 AI 에이전트가 대화를 처리하는지를 식별합니다.
• data-config-id: 귀하의 위젯 구성의 UUID - 이는 귀하의 위젯이 어떻게 보이고 동작하는지를 결정합니다 (색상, 크기, 위치 등).
• data-instance-id: 위젯 인스턴스별 고유 ID - 동일한 페이지에 여러 위젯을 포함할 때 충돌을 피하고 인스턴스별 API 타겟팅을 가능하게 하려면 필요합니다.
• data-custom-css: 사용 중단됨. 이 속성을 설정하면 콘솔 경고가 기록되고 효과가 없습니다. 대신 대시보드에서 위젯 구성에 custom_css를 설정하세요 — 이는 구성에서 로드되어 iframe에 자동으로 주입됩니다.
• data-locale: 언어 코드 (예: "en", "es", "fr") - 위젯의 표시 언어를 설정합니다. 에이전트는 여전히 사용자가 작성하는 모든 언어로 응답합니다.
• data-theme: 테마 모드 - light, dark, 또는 system (방문자의 장치에 따름). 위젯이 표시할 색상 팔레트를 선택합니다 (대시보드에서 구성됨). 저장된 기본값을 사용하려면 생략하세요.
• data-dev: 개발 모드(로컬호스트)를 위해 "true"로 설정하세요 - 로컬에서 테스트할 때 사용하세요. 프로덕션에서는 제거하거나 "false"로 설정하세요.

위젯은 자동으로:

• 구성 ID에서 구성을 가져옵니다
• 구성의 위젯 치수에 따라 크기를 조정합니다
• 구성 설정에 따라 축소된 버튼의 위치를 설정합니다
• 구성의 start_open 설정에 따라 열리거나 닫히기 시작합니다

노트

• 위젯은 구성 설정에 따라 자동으로 크기를 관리합니다.
• 축소된 버튼 위치는 위젯 구성에서 사용자 정의할 수 있습니다.
• 위젯은 구성의 start_open 설정을 존중합니다.
• 모든 스타일(색상, 글꼴, 치수)은 위젯 구성을 통해 제어됩니다.
• 위젯은 반응형 동작을 위해 postMessage 통신을 사용합니다.
• 개발 모드는 로컬호스트 테스트를 위해 data-dev="true"로 활성화할 수 있습니다.
• 서버 측 토큰 교환을 위해 /api/v1/auth/widget-token을 사용하고 클라이언트 비밀은 서버에만 보관하세요.
• iframe에 위젯을 포함할 때 호스트 출처(예: http://localhost:3000)가 OAuth allowed_origins에 포함되어 있는지 확인하세요.