@deeprocket/deep-service-desk-widget

v1.4.5

Published

7 months ago

Widget Vue.js para integração com o sistema Deep Service Desk - Controle de visibilidade por URLs - Compatível com Vue 2.7.16 e Vue 3 - Com botão flutuante automático

Deep Service Desk Widget

Widget Vue.js para integração com o sistema Deep Service Desk. Compatível com Vue 2.7.16 e Vue 3, oferece uma interface moderna e responsiva para criação de tickets de suporte com API fixa e cores personalizáveis.

📋 Índice

✨ Características

🎯 Compatibilidade: Vue 2.7.16 e Vue 3
🎨 Interface Moderna: Design responsivo e intuitivo
🔄 Botão Flutuante: Botão automático para abertura de tickets
📱 Responsivo: Funciona perfeitamente em desktop e mobile
🔧 Configurável: Múltiplas opções de configuração
🌐 Independente: Funciona mesmo sem Vue (fallback HTML)
🔔 Notificações: Sistema de notificações toast integrado
🔒 Seguro: Validação de dados e tratamento de erros
🌈 Personalizável: Cores customizáveis via brandColor
🔗 API Fixa: Conecta automaticamente a https://servicedesk.deeprocket.com.br/api

📦 Instalação

Via NPM (Recomendado)

npm install @deeprocket/deep-service-desk-widget

Via Yarn

yarn add @deeprocket/deep-service-desk-widget

Via CDN

<!-- CSS -->
<link rel="stylesheet" href="https://unpkg.com/@deeprocket/deep-service-desk-widget/dist/deep-service-desk-widget.css">

<!-- JavaScript -->
<script src="https://unpkg.com/@deeprocket/deep-service-desk-widget/dist/deep-service-desk-widget.umd.min.js"></script>

⚙️ Configuração

Vue 3

import { createApp } from 'vue'
import App from './App.vue'
import DeepServiceDeskPlugin from '@deeprocket/deep-service-desk-widget'

const app = createApp(App)

// Configuração do plugin
app.use(DeepServiceDeskPlugin, {
  clientUuid: 'seu-client-uuid-aqui', // OBRIGATÓRIO
  brandColor: '#3b82f6', // Opcional, cor personalizada (hex)
  showFloatingButton: true, // Opcional, padrão: true
  hiddenUrls: ['/admin', '/config', new RegExp('/private/.*')] // Opcional, URLs onde o botão não deve aparecer
})

app.mount('#app')

Vue 2.7.16

import Vue from 'vue'
import App from './App.vue'
import DeepServiceDeskPlugin from '@deeprocket/deep-service-desk-widget'

// Configuração do plugin
Vue.use(DeepServiceDeskPlugin, {
  clientUuid: 'seu-client-uuid-aqui', // OBRIGATÓRIO
  brandColor: '#3b82f6', // Opcional, cor personalizada (hex)
  showFloatingButton: true, // Opcional, padrão: true
  hiddenUrls: ['/admin', '/config', new RegExp('/private/.*')] // Opcional, URLs onde o botão não deve aparecer
})

new Vue({
  render: h => h(App)
}).$mount('#app')

Configuração via CDN

<!DOCTYPE html>
<html>
<head>
  <link rel="stylesheet" href="https://unpkg.com/@deeprocket/deep-service-desk-widget/dist/deep-service-desk-widget.css">
</head>
<body>
  <div id="app"></div>
  
  <script src="https://unpkg.com/vue@3/dist/vue.global.js"></script>
  <script src="https://unpkg.com/@deeprocket/deep-service-desk-widget/dist/deep-service-desk-widget.umd.min.js"></script>
  
  <script>
    const { createApp } = Vue
    
    createApp({}).use(DeepServiceDeskPlugin, {
      clientUuid: 'seu-client-uuid-aqui',
      brandColor: '#10b981', // Verde personalizado
      hiddenUrls: ['/admin', '/config'] // URLs onde o botão não deve aparecer
    }).mount('#app')
  </script>
</body>
</html>

🚀 Uso Básico

Configuração Automática (Recomendado)

Após instalar o plugin, um botão flutuante aparecerá automaticamente no canto inferior direito da página. Os usuários podem clicar nele para abrir o formulário de criação de tickets.

Uso Manual dos Componentes

<template>
  <div>
    <!-- Widget completo de tickets -->
    <TicketWidget 
      :client-uuid="clientUuid"
      :brand-color="brandColor"
      @ticket-created="onTicketCreated"
      @ticket-error="onTicketError"
    />
    
    <!-- Ou use o widget flutuante -->
    <FloatingTicketWidget :brand-color="brandColor" />
    
    <!-- Botão personalizado para abrir o widget -->
    <button @click="openTicket">Abrir Suporte</button>
  </div>
</template>

<script>
export default {
  data() {
    return {
      clientUuid: 'seu-client-uuid-aqui',
      brandColor: '#8b5cf6' // Roxo personalizado
    }
  },
  methods: {
    openTicket() {
      // Dispara o evento para abrir o widget
      this.$deepServiceDeskButton.openTicket()
    },
    onTicketCreated(ticketData) {
      console.log('Ticket criado:', ticketData)
    },
    onTicketError(error) {
      console.error('Erro ao criar ticket:', error)
    }
  }
}
</script>

🧩 Componentes Disponíveis

TicketWidget

Componente principal que exibe o formulário de criação de tickets em um modal.

Props:

clientUuid (String): UUID do cliente (obrigatório)
brandColor (String): Cor personalizada em hexadecimal (opcional, padrão: '#3b82f6')

Eventos:

@ticket-created: Emitido quando um ticket é criado com sucesso
@ticket-error: Emitido quando ocorre um erro na criação

API:

URL fixa: https://servicedesk.deeprocket.com.br/api

FloatingTicketWidget

Componente que gerencia o widget de ticket de forma invisível, usado internamente pelo botão flutuante.

Props:

brandColor (String): Cor personalizada em hexadecimal (opcional, padrão: '#3b82f6')

🔧 API e Métodos

Métodos Globais

Após instalar o plugin, os seguintes métodos ficam disponíveis:

// Vue 3
this.$deepServiceDeskButton.showFloatingButton()
this.$deepServiceDeskButton.hideFloatingButton()
this.$deepServiceDeskButton.openTicket()
this.$deepServiceDeskButton.updateUrlVisibility() // Verificar visibilidade baseada na URL atual

// Vue 2
this.$deepServiceDeskButton.showFloatingButton()
this.$deepServiceDeskButton.hideFloatingButton()
this.$deepServiceDeskButton.openTicket()
this.$deepServiceDeskButton.updateUrlVisibility() // Verificar visibilidade baseada na URL atual

Configuração Global

// Acessar configuração global
console.log(this.$deepServiceDesk)

// Vue 3 - via inject
export default {
  inject: ['deepServiceDeskConfig'],
  mounted() {
    console.log(this.deepServiceDeskConfig)
  }
}

📡 Eventos

Eventos do Window

O widget emite eventos globais que podem ser escutados:

// Evento disparado quando um ticket é criado
window.addEventListener('ticket-created', (event) => {
  console.log('Ticket criado:', event.detail)
})

// Evento disparado quando ocorre erro
window.addEventListener('ticket-error', (event) => {
  console.log('Erro:', event.detail)
})

// Evento para abrir o widget programaticamente
window.dispatchEvent(new CustomEvent('new-ticket'))

🎨 Personalização

Personalização de Cores (brandColor)

O widget permite personalizar a cor principal através da propriedade brandColor:

// Configuração global
app.use(DeepServiceDeskPlugin, {
  clientUuid: 'seu-client-uuid-aqui',
  brandColor: '#10b981' // Verde
})

// Exemplos de cores
brandColor: '#3b82f6' // Azul (padrão)
brandColor: '#ef4444' // Vermelho  
brandColor: '#8b5cf6' // Roxo
brandColor: '#f59e0b' // Laranja
brandColor: '#10b981' // Verde

Onde a cor é aplicada:

✅ Botão flutuante de fundo
✅ Botões de submit do formulário
✅ Campos de input quando em foco (borda e shadow)
✅ Elementos de destaque na interface

Variáveis de Ambiente

O widget suporta configuração via variáveis de ambiente:

# .env
VITE_CLIENT_UUID=seu-client-uuid-aqui

# Para Vue CLI  
VUE_APP_CLIENT_UUID=seu-client-uuid-aqui

⚠️ Mudança importante: A URL da API agora é fixa (https://servicedesk.deeprocket.com.br/api) e não precisa mais ser configurada.

Configuração via Window

// Definir configurações globais
window.DEEP_SERVICE_DESK_CLIENT_UUID = 'seu-client-uuid-aqui'

Nota: A configuração DEEP_SERVICE_DESK_API_URL foi removida pois a API agora é fixa.

Estilos CSS

O widget inclui estilos padrão, mas você pode personalizá-los:

/* Personalizar o botão flutuante (além do brandColor) */
#deep-service-desk-floating-btn {
  bottom: 30px !important;
  right: 30px !important;
  width: 70px !important;
  height: 70px !important;
  border-radius: 20px !important; /* Menos arredondado */
}

/* Personalizar o modal */
.popup-overlay {
  background-color: rgba(0, 0, 0, 0.8) !important;
}

.popup-content {
  border-radius: 12px !important;
  box-shadow: 0 20px 40px rgba(0, 0, 0, 0.3) !important;
}

⚠️ Recomendação: Use a propriedade brandColor para personalizar cores ao invés de CSS, pois ela garante consistência em todos os elementos.

Controle de Visibilidade por URL

O widget permite definir URLs específicas onde o botão flutuante não deve aparecer usando o parâmetro hiddenUrls:

app.use(DeepServiceDeskPlugin, {
  clientUuid: 'seu-client-uuid-aqui',
  brandColor: '#10b981', // Verde personalizado
  hiddenUrls: [
    '/admin',              // Ocultar em páginas de admin
    '/configuracoes',      // Ocultar em configurações
    '/checkout',           // Ocultar no checkout
    new RegExp('/private/.*'), // Usar regex para padrões complexos
    'login',               // Ocultar em qualquer URL que contenha "login"
  ]
})

Tipos de padrões suportados:

String simples: Verifica se a string está contida na URL atual
```
hiddenUrls: ['/admin', 'login', 'checkout']
```

Expressões regulares: Para padrões mais complexos

hiddenUrls: [
  new RegExp('/admin/.*'),      // Qualquer rota que comece com /admin/
  new RegExp('\\?debug=true'),  // URLs com parâmetro debug=true
  new RegExp('/user/\\d+/edit') // URLs como /user/123/edit
]

Monitoramento automático: O widget monitora automaticamente mudanças de URL (incluindo SPAs) e atualiza a visibilidade do botão em tempo real.

Controle manual:

// Forçar verificação da visibilidade baseada na URL atual
this.$deepServiceDeskButton.updateUrlVisibility()

// Ou usar a função global (disponível em qualquer lugar)
window.deepServiceDeskUpdateVisibility()

⚠️ Correção de Problema - Login/SPA: Se você teve o problema onde o botão só aparecia após F5 em SPAs (especialmente após login), este foi corrigido na versão 1.4.1 com múltiplas estratégias de monitoramento:

✅ MutationObserver - Detecta mudanças no DOM
✅ Interceptação de History API - Monitora pushState/replaceState
✅ Verificação periódica - Fallback a cada 2 segundos
✅ Detecção de frameworks - Vue Router, React Router
✅ Interceptação de AJAX - Monitora requests fetch/XHR
✅ Função global - window.deepServiceDeskUpdateVisibility()

📚 Exemplos

Exemplo Completo - Vue 3

<template>
  <div id="app">
    <h1>Minha Aplicação</h1>
    
    <!-- O botão flutuante aparece automaticamente -->
    
    <!-- Botão personalizado opcional -->
    <button @click="abrirSuporte" class="btn-suporte">
      Precisa de Ajuda?
    </button>
  </div>
</template>

<script>
export default {
  name: 'App',
  mounted() {
    // Escutar eventos do widget
    window.addEventListener('ticket-created', this.onTicketCriado)
    window.addEventListener('ticket-error', this.onTicketErro)
  },
  beforeUnmount() {
    window.removeEventListener('ticket-created', this.onTicketCriado)
    window.removeEventListener('ticket-error', this.onTicketErro)
  },
  methods: {
    abrirSuporte() {
      this.$deepServiceDeskButton.openTicket()
    },
    onTicketCriado(event) {
      console.log('Ticket criado com sucesso:', event.detail)
      // Aqui você pode implementar lógica adicional
    },
    onTicketErro(event) {
      console.error('Erro ao criar ticket:', event.detail)
      // Aqui você pode implementar tratamento de erro
    }
  }
}
</script>

Exemplo com Configuração Dinâmica

<template>
  <div>
    <button @click="configurarWidget">Configurar Widget</button>
    <button @click="mostrarBotao">Mostrar Botão</button>
    <button @click="esconderBotao">Esconder Botão</button>
    <button @click="verificarVisibilidade">Verificar Visibilidade</button>
  </div>
</template>

<script>
export default {
  methods: {
    configurarWidget() {
      // Reconfigurar o widget dinamicamente
      this.$deepServiceDesk.clientUuid = 'novo-uuid'
      this.$deepServiceDesk.brandColor = '#ef4444' // Mudança para vermelho
    },
    mostrarBotao() {
      this.$deepServiceDeskButton.showFloatingButton()
    },
    esconderBotao() {
      this.$deepServiceDeskButton.hideFloatingButton()
    },
    verificarVisibilidade() {
      // Verificar visibilidade baseada nas URLs configuradas
      this.$deepServiceDeskButton.updateUrlVisibility()
    }
  }
}
</script>

Exemplo com URLs Ocultas

<template>
  <div id="app">
    <nav>
      <router-link to="/">Home</router-link>
      <router-link to="/admin">Admin</router-link>
      <router-link to="/checkout">Checkout</router-link>
      <router-link to="/suporte">Suporte</router-link>
    </nav>
    
    <router-view />
    
    <!-- O botão flutuante aparece automaticamente, 
         exceto nas páginas /admin e /checkout -->
  </div>
</template>

<script>
export default {
  name: 'App',
  mounted() {
    // Widget configurado com URLs ocultas no main.js:
    // hiddenUrls: ['/admin', '/checkout', new RegExp('/private/.*')]
    
    console.log('Widget configurado com URLs ocultas')
  }
}
</script>

Exemplo sem Vue (HTML Puro)

<!DOCTYPE html>
<html>
<head>
  <title>Widget sem Vue</title>
  <link rel="stylesheet" href="https://unpkg.com/@deeprocket/deep-service-desk-widget/dist/deep-service-desk-widget.css">
</head>
<body>
  <h1>Minha Página</h1>
  <button onclick="abrirTicket()">Abrir Suporte</button>
  
  <script src="https://unpkg.com/@deeprocket/deep-service-desk-widget/dist/deep-service-desk-widget.umd.min.js"></script>
  <script>
    // Configurar o widget
    window.DEEP_SERVICE_DESK_CLIENT_UUID = 'seu-client-uuid-aqui'
    
    // Função para abrir ticket
    function abrirTicket() {
      window.dispatchEvent(new CustomEvent('new-ticket'))
    }
    
    // Escutar eventos
    window.addEventListener('ticket-created', (event) => {
      alert('Ticket criado: ' + event.detail.id)
    })
  </script>
</body>
</html>

Nota: Para HTML puro, a cor do botão pode ser personalizada via CSS se necessário.

🔍 Troubleshooting

Problemas Comuns

1. "clientUuid é obrigatório"

Erro: Deep Service Desk Widget: clientUuid é obrigatório na configuração

Solução: Certifique-se de fornecer o clientUuid na configuração:

app.use(DeepServiceDeskPlugin, {
  clientUuid: 'seu-client-uuid-aqui' // OBRIGATÓRIO
})

2. Botão flutuante não aparece

Possíveis causas:

showFloatingButton está definido como false
Erro de JavaScript impedindo a inicialização
Conflito de CSS

Solução:

// Verificar configuração
console.log(this.$deepServiceDesk)

// Mostrar botão manualmente
this.$deepServiceDeskButton.showFloatingButton()

3. Formulário não envia

Possíveis causas:

Problemas de CORS
Cliente UUID inválido
Problemas de conectividade com https://servicedesk.deeprocket.com.br/api

Solução:

// Verificar configuração
console.log('Client UUID:', this.$deepServiceDesk.clientUuid)
console.log('Brand Color:', this.$deepServiceDesk.brandColor)

// Verificar console do navegador para erros de rede
// A API é sempre: https://servicedesk.deeprocket.com.br/api

4. Incompatibilidade com Vue 2

Erro: Plugin não funciona com Vue 2

Solução: Certifique-se de usar Vue 2.7.16 ou superior:

npm install vue@^2.7.16

Debug

Para ativar logs detalhados, abra o console do navegador. O widget emite logs informativos que ajudam no debug:

// Logs do widget começam com emojis:
// 🚀 Instalação do plugin
// 🔧 Configuração
// ✅ Sucesso
// ⚠️ Avisos
// ❌ Erros

📋 Changelog

v1.4.3 - Última versão

🆕 Novidades:

✅ brandColor: Nova propriedade para personalizar cores do widget
✅ API fixa: URL da API agora é fixa (https://servicedesk.deeprocket.com.br/api)
✅ Melhoria na UX: Cores consistentes em botões e campos de foco
✅ Arquivo de teste: Adicionado test-widget.html para demonstração

🔄 Mudanças:

❌ apiUrl removido: Não é mais necessário configurar a URL da API
⚡ Performance: Redução no tamanho do bundle ao remover lógica de URL dinâmica

⚠️ Breaking Changes:

A propriedade apiUrl foi removida - se você estava usando, simplesmente remova da configuração
Todos os tickets agora são enviados para https://servicedesk.deeprocket.com.br/api

📦 Configuração atualizada:

// ❌ ANTES (v1.4.2 e anteriores)
app.use(DeepServiceDeskPlugin, {
  apiUrl: 'https://sua-api.com/api',
  clientUuid: 'seu-uuid'
})

// ✅ DEPOIS (v1.4.3+)
app.use(DeepServiceDeskPlugin, {
  clientUuid: 'seu-uuid',
  brandColor: '#3b82f6' // Nova opção!
})

📄 Licença

MIT License - veja o arquivo LICENSE para detalhes.

🤝 Contribuição

Contribuições são bem-vindas! Por favor, abra uma issue ou pull request no repositório.

📞 Suporte

Para suporte técnico, abra uma issue no repositório GitHub.