Расширенные функции, настройки и интеграции для продвинутых пользователей.
Виджет предоставляет глобальный объект 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>Слушайте события виджета, используя API postMessage. Это идеально подходит для отслеживания вовлеченности пользователей, вызова логики приложения на основе взаимодействий с виджетом или синхронизации состояния виджета с вашим приложением.
Общие случаи использования:
<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; }Виджет поставляется с двумя палитрами — Светлой и Темной — настроенными в вашей панели управления. Выберите, какую из них увидят посетители, с помощью атрибута скрипта data-theme="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.
Преимущества вебхуков:
Настройте URL вебхуков в вашей панели управления, чтобы получать HTTP POST запросы, когда происходят определенные события. Каждый полезный нагрузка вебхука включает данные события и метаданные:
{ "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: