전문 사용자용 고급 기능, 사용자 정의 및 통합.
위젯은 프로그래밍 제어를 위한 전역 CompaninWidget 객체를 노출합니다. 이를 통해 사용자 행동이나 애플리케이션 상태에 따라 위젯 작업을 트리거하여 애플리케이션의 사용자 경험에 깊이 통합할 수 있습니다.
API는 비동기적으로 로드되므로 메서드를 호출하기 전에 항상 존재하는지 확인하세요. 준비가 되면 사용자 정의 이벤트를 수신할 수도 있습니다.
이 메서드는 위젯의 가시성과 동작에 대한 완전한 프로그래밍 제어를 제공합니다.
<script id="companin-widget-script-sales" src="https://widget.companin.tech/widget.js" data-widget-key="YOUR_WIDGET_KEY" data-instance-id="sales-widget"></script> <script> // Ensure the widget has loaded before calling methods window.addEventListener('load', () => { const salesWidget = window.CompaninWidgets?.get('sales-widget') || window.CompaninWidget; if (salesWidget) { salesWidget.show(); salesWidget.sendMessage && salesWidget.sendMessage('Hello from page'); } }); </script>postMessage API를 사용하여 위젯 이벤트를 수신하세요. 이는 사용자 참여를 추적하거나 위젯 상호작용에 따라 애플리케이션 논리를 트리거하거나 위젯 상태를 애플리케이션과 동기화하는 데 적합합니다.
일반적인 사용 사례:
<script> window.addEventListener('message', (event) => { if (event.origin !== 'https://widget.companin.tech') return; const { type, data } = event.data || {}; switch (type) { case 'WIDGET_INIT_CONFIG': console.log('Widget is ready'); break; case 'WIDGET_SHOW': console.log('Widget was opened'); break; case 'WIDGET_MESSAGE': console.log('User sent message:', data?.message); break; } }); </script>구성 인터페이스가 광범위한 스타일링 옵션을 제공하지만 고급 사용자 정의를 위해 사용자 정의 CSS로 더 나아갈 수 있습니다. 이는 고유한 시각 효과, 애니메이션 또는 표준 구성에서 사용할 수 없는 스타일이 필요할 때 유용합니다.
중요한 고려 사항:
!important를 드물게 사용하세요 — iframe 격리를 오버라이드할 필요가 있을 때만 사용하세요컨테이너 클래스를 사용하여 위젯 요소를 타겟팅하세요. 사용자 정의 CSS를 위젯 구성의 사용자 정의 CSS 필드에 추가하거나 사이트의 전역 스타일시트에 추가하세요:
/* Target the widget container */ .companin-widget-container { /* Custom styles */ } /* Style the collapsed button */ .companin-widget-container button { border-radius: 50% !important; box-shadow: 0 0 20px rgba(0, 0, 0, 0.3) !important; } /* Custom message bubble styles */ .companin-widget-container .message-bubble { background: linear-gradient(45deg, #667eea 0%, #764ba2 100%) !important; } /* Hide the default close button */ .companin-widget-container .close-button { display: none !important; }위젯은 대시보드에서 구성된 두 가지 팔레트 — 라이트 및 다크 — 와 함께 제공됩니다. 데이터-테마="light|dark|system" 스크립트 속성으로 방문자가 어떤 것을 볼지 선택하거나 CompaninWidget.setTheme('dark')로 런타임에 전환하세요. 아래의 CSS 변수는 활성 팔레트 위에 여전히 적용되어 세밀한 오버라이드를 제공합니다.
CSS 사용자 정의 속성을 통한 고급 테마 설정:
:root { /* Override widget theme variables */ --companin-primary: #ff6b6b; --companin-secondary: #4ecdc4; --companin-background: #2d3748; --companin-text: #e2e8f0; --companin-border-radius: 12px; } /* Dark theme variant */ @media (prefers-color-scheme: dark) { :root { --companin-background: #1a202c; --companin-text: #f7fafc; } }사용자가 위젯과 상호작용하는 방식을 이해하는 것은 최적화에 중요합니다. 분석 플랫폼과 통합하여 참여 지표를 추적하고 인기 있는 주제를 식별하며 위젯이 사용자 경험 및 전환율에 미치는 영향을 측정할 수 있습니다.
추적할 주요 지표:
Google Analytics에서 사용자 정의 이벤트로 위젯 상호작용을 추적합니다. 이는 기존 분석 설정과 원활하게 통합됩니다:
// Track widget events window.addEventListener('message', (event) => { if (event.origin !== 'https://widget.companin.tech') return; const { type, data } = event.data; switch (type) { case 'WIDGET_SHOW': gtag('event', 'widget_opened', { event_category: 'engagement', event_label: 'chat_widget' }); break; case 'WIDGET_MESSAGE': gtag('event', 'message_sent', { event_category: 'engagement', event_label: data.messageLength > 50 ? 'long_message' : 'short_message' }); break; case 'WIDGET_RESPONSE': gtag('event', 'conversation_started', { event_category: 'engagement', event_label: 'chat_widget' }); break; } });// Custom analytics tracking const trackWidgetEvent = (eventName, properties = {}) => { fetch('/api/analytics/track', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ event: eventName, properties: { widget: 'companin', ...properties } }) }); }; window.addEventListener('message', (event) => { if (event.origin !== 'https://widget.companin.tech') return; const { type, data } = event.data; switch (type) { case 'WIDGET_SHOW': trackWidgetEvent('widget_opened'); break; case 'WIDGET_MESSAGE': trackWidgetEvent('message_sent', { length: data.message?.length || 0 }); break; } });참고: 아웃바운드 웹훅은 로드맵에 있으며 아직 일반적으로 사용 가능하지 않습니다 — 현재 대시보드에 웹훅 URL 필드가 없습니다. 아래의 페이로드 형태와 이벤트 이름은 계획된 디자인을 설명합니다. 그동안 실시간 이벤트 처리를 위해 페이지 내 postMessage 이벤트(예: WIDGET_MESSAGE, WIDGET_RESPONSE)를 사용하거나 API를 폴링하세요.
웹훅 이점:
특정 이벤트가 발생할 때 HTTP POST 요청을 수신하도록 대시보드에서 웹후크 URL을 구성합니다. 각 웹후크 페이로드에는 이벤트 데이터 및 메타데이터가 포함됩니다:
{ "event": "message_received", "timestamp": "2024-01-09T10:30:00Z", "data": { "session_id": "sess_123456", "message": { "id": "msg_789", "content": "Hello, I need help", "sender": "user", "timestamp": "2024-01-09T10:30:00Z" }, "metadata": { "user_agent": "Mozilla/5.0...", "ip_address": "192.168.1.1", "locale": "en" } } }widget_opened - 사용자가 위젯을 열었습니다widget_closed - 사용자가 위젯을 닫았습니다conversation_started - 새 대화가 시작되었습니다message_received - 사용자가 메시지를 보냈습니다message_sent - 에이전트가 메시지를 보냈습니다flow_triggered - 대화 흐름이 활성화되었습니다session_ended - 대화 세션이 종료되었습니다타사 콘텐츠를 웹사이트에 삽입할 때 보안이 가장 중요합니다. 위젯이 보안 모범 사례를 따르지만 통합을 강화하기 위해 추가 조치를 취할 수 있습니다.
콘텐츠 보안 정책 헤더는 XSS 공격 및 기타 코드 주입 취약점을 방지하는 데 도움이 됩니다. 위젯을 명시적으로 허용하면서 다른 곳에서 엄격한 보안을 유지하도록 CSP를 구성하세요:
# nginx.conf add_header Content-Security-Policy " default-src 'self'; script-src 'self' https://widget.companin.tech; style-src 'self' 'unsafe-inline' https://widget.companin.tech; frame-src https://widget.companin.tech; connect-src 'self' https://app.companin.tech; " always;항상 사용자 입력을 검증하고 정리하세요:
// Validate message content function validateMessage(message) { if (message.length > 2000) { return { valid: false, error: 'Message too long' }; } const dangerousPatterns = [/<script/i, /javascript:/i, /onw+s*=/i]; for (const pattern of dangerousPatterns) { if (pattern.test(message)) { return { valid: false, error: 'Invalid content' }; } } return { valid: true }; } const validation = validateMessage(userInput); if (!validation.valid) { showError(validation.error); return; }위젯은 기본적으로 성능을 최적화하지만 특히 트래픽이 많은 사이트나 느린 연결에서 더 빠르고 효율적으로 만들기 위한 전략이 있습니다.
페이지가 로드될 때 위젯을 즉시 로드하는 대신 사용자가 필요할 때까지 또는 중요한 콘텐츠가 로드된 후까지 연기하세요. 이는 페이지의 초기 로드 시간과 Core Web Vitals 점수를 개선합니다:
// Load widget only when needed function loadWidget() { if (window.CompaninWidget) return; // Already loaded const script = document.createElement('script'); script.src = 'https://widget.companin.tech/widget.js'; script.setAttribute('data-widget-key', 'YOUR_WIDGET_KEY'); document.head.appendChild(script); } // Load on user interaction document.addEventListener('click', () => { loadWidget(); }, { once: true }); // Or load after page load window.addEventListener('load', () => { setTimeout(loadWidget, 2000); });색상 선택이 WCAG 지침을 충족하는지 확인하세요: