Recursos avançados, personalizações e integrações para usuários avançados.
O widget expõe um objeto global CompaninWidget para controle programático. Isso permite que você integre o widget profundamente na experiência do usuário do seu aplicativo, acionando ações do widget com base no comportamento do usuário ou no estado do aplicativo.
A API é carregada de forma assíncrona, então sempre verifique se ela existe antes de chamar métodos. Você também pode ouvir um evento personalizado quando estiver pronta.
Esses métodos oferecem controle programático total sobre a visibilidade e o comportamento do widget.
<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>Ouça eventos do widget usando a API postMessage. Isso é perfeito para rastrear o engajamento do usuário, acionar lógica de aplicativo com base nas interações do widget ou sincronizar o estado do widget com seu aplicativo.
Casos de uso comuns:
<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>Enquanto a interface de configuração fornece opções de estilização extensas, você pode ir ainda mais longe com CSS personalizado para personalizações avançadas. Isso é útil quando você precisa de efeitos visuais únicos, animações ou estilos que não estão disponíveis na configuração padrão.
Considerações importantes:
!important com moderação — apenas quando necessário para substituir a isolação do iframeAlvo elementos do widget usando a classe do contêiner. Adicione seu CSS personalizado no campo de CSS personalizado da configuração do widget ou no stylesheet global do seu site:
/* 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;}Tematização avançada com propriedades 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; }}Entender como os usuários interagem com seu widget é crucial para otimização. Ao integrar com sua plataforma de análise, você pode rastrear métricas de engajamento, identificar tópicos populares e medir o impacto do widget na experiência do usuário e nas taxas de conversão.
Métricas-chave a serem rastreadas:
Rastreie interações do widget como eventos personalizados no Google Analytics. Isso se integra perfeitamente à sua configuração de análise existente:
// Track widget eventswindow.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 trackingconst 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; }});Nota: Webhooks de saída estão no roadmap e ainda não estão disponíveis de forma geral — não há campo de URL de webhook no painel hoje. As formas de payload e os nomes de eventos abaixo descrevem o design planejado. Para manipulação de eventos em tempo real, use os eventos postMessage na página (por exemplo, WIDGET_MESSAGE, WIDGET_RESPONSE) mostrados na seção de Escuta de Eventos acima, ou consulte a API.
Benefícios do Webhook:
Configure URLs de webhook em seu painel para receber solicitações HTTP POST quando eventos específicos ocorrerem. Cada carga útil de webhook inclui dados de evento e metadados:
{ "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_aberto - Usuário abriu o widgetwidget_fechado - Usuário fechou o widgetconversa_iniciada - Nova conversa iniciadamensagem_recebida - Usuário enviou uma mensagemmensagem_enviada - Agente enviou uma mensagemfluxo_ativado - Fluxo de conversa foi ativadosessão_encerrada - Sessão de conversa encerradaA segurança é primordial ao incorporar conteúdo de terceiros em seu site. Embora o widget siga as melhores práticas de segurança, existem etapas adicionais que você pode tomar para fortalecer sua integração.
Os cabeçalhos da Política de Segurança de Conteúdo ajudam a prevenir ataques XSS e outras vulnerabilidades de injeção de código. Configure sua CSP para permitir explicitamente o widget enquanto mantém a segurança rigorosa em outros lugares:
# nginx.confadd_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;Sempre valide e sane as entradas do usuário:
// Validate message contentfunction 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;}O widget é otimizado para desempenho desde o início, mas existem estratégias para torná-lo ainda mais rápido e eficiente, especialmente em sites de alto tráfego ou conexões mais lentas.
Em vez de carregar o widget imediatamente quando a página carrega, adie até que o usuário precise dele ou após o carregamento de conteúdo crítico. Isso melhora o tempo de carregamento inicial da sua página e as pontuações de Core Web Vitals:
// Load widget only when neededfunction 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 interactiondocument.addEventListener('click', () => { loadWidget();}, { once: true });// Or load after page loadwindow.addEventListener('load', () => { setTimeout(loadWidget, 2000);});Certifique-se de que suas escolhas de cores atendam às diretrizes WCAG: