Uso Avançado

API Programática

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 pronto.

Métodos Disponíveis

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>

Escuta de Eventos

Ouça eventos do widget usando a API postMessage. Isso é perfeito para rastrear o engajamento do usuário, acionar a lógica do aplicativo com base nas interações do widget ou sincronizar o estado do widget com seu aplicativo.

Casos de uso comuns:

• Rastreie o engajamento do widget em sua plataforma de análise
• Mostre ajuda contextual com base nas conversas do widget
• Acione ações do aplicativo quando as conversas começam
• Atualize elementos da interface do usuário com base no estado do widget
• Registre interações de suporte ao cliente em seu CRM

<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>

Estilização Personalizada

Enquanto a interface de configuração fornece extensas opções de estilização, 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:

• Estilos personalizados substituem configurações de configuração
• Use !important com moderação — apenas quando necessário para substituir a isolação de iframe
• Teste minuciosamente em diferentes navegadores, pois o CSS personalizado pode se comportar de maneira diferente
• Atualizações do widget podem afetar seus estilos personalizados — revise após cada atualização

Substituições de CSS

Alvo 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;    }

Personalização de Tema

O widget vem com duas paletas — Claro e Escuro — configuradas no seu painel. Escolha qual delas os visitantes veem com o atributo de script data-theme="light|dark|system" (o sistema segue o dispositivo deles), ou altere em tempo de execução com CompaninWidget.setTheme('dark'). As variáveis CSS abaixo ainda se aplicam além da paleta ativa para substituições mais finas.

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;      }    }

Integração de Análise

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:

• Taxas de abertura/fechamento do widget
• Mensagens enviadas por sessão
• Duração média da conversa
• Tópicos de conversa populares (a partir de fluxos)
• Tempo para a primeira mensagem
• Taxas de conclusão para fluxos de conversa

Google Analytics

Acompanhe interações do widget como eventos personalizados no Google Analytics. Isso se integra perfeitamente à sua configuração de análise existente:

// 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;      }    });

Análise Personalizada

// 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;      }    });

Integração de Webhook

Nota: Webhooks de saída estão no roteiro 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:

• Sincronização em tempo real com seus sistemas
• Criação automática de tickets em sistemas de suporte
• Enriquecimento de dados do cliente em CRM
• Gatilhos de fluxo de trabalho automatizados
• Conformidade e registro de auditoria

Webhooks de Evento

Configure URLs de webhook em seu painel para receber solicitações HTTP POST quando eventos específicos ocorrerem. Cada carga útil do webhook inclui dados de eventos 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"        }      }    }

Eventos Disponíveis

• widget_opened - Usuário abriu o widget
• widget_closed - Usuário fechou o widget
• conversation_started - Nova conversa iniciada
• message_received - Usuário enviou uma mensagem
• message_sent - Agente enviou uma mensagem
• flow_triggered - Fluxo de conversa foi ativado
• session_ended - Sessão de conversa encerrada

Considerações de Segurança

A segurança é primordial ao incorporar conteúdo de terceiros em seu site. Embora o widget siga as melhores práticas de segurança, há etapas adicionais que você pode tomar para fortalecer sua integração.

Política de Segurança de Conteúdo (CSP)

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.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;

Validação de Entrada

Sempre valide e sane as entradas do usuário:

// 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;    }

Otimização de Desempenho

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.

Carregamento Preguiçoso

Em vez de carregar o widget imediatamente quando a página carrega, adie-o 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 do 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);    });

Minimize CSS e imagens personalizadosUse esquemas de cores eficientesLimite o histórico de mensagens (configure nas configurações do widget)Ative a compressão em seu servidorUse CDN para ativos estáticos

• Minimize CSS e imagens personalizados
• Use esquemas de cores eficientes
• Limite o histórico de mensagens (configure nas configurações do widget)
• Ative a compressão em seu servidor
• Use CDN para ativos estáticos

Recursos de Acessibilidade

Navegação por Teclado

• Aba - Navegar entre elementos
• Enter / Espaço - Ativar botões
• Esc - Fechar widget
• Teclas de seta - Navegar no histórico de mensagens

Suporte a Leitores de Tela

• Todos os elementos interativos têm rótulos ARIA adequados
• Anúncios de mensagens para leitores de tela
• Gerenciamento de foco ao abrir/fechar
• Suporte ao modo de alto contraste

Contraste de Cores

Certifique-se de que suas escolhas de cores atendam às diretrizes WCAG:

• Texto primário: 4.5:1 de razão de contraste mínima
• Texto grande: 3:1 de razão de contraste mínima
• Componentes de UI: 3:1 de razão de contraste mínima