@deeprocket/deep-service-desk-widget
Version:
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
578 lines (451 loc) • 15.2 kB
Markdown
# 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.
## 📋 Índice
- [Características](#características)
- [Instalação](#instalação)
- [Configuração](#configuração)
- [Uso Básico](#uso-básico)
- [Componentes Disponíveis](#componentes-disponíveis)
- [API e Métodos](#api-e-métodos)
- [Eventos](#eventos)
- [Personalização](#personalização)
- [Exemplos](#exemplos)
- [Troubleshooting](#troubleshooting)
## ✨ 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
## 📦 Instalação
### Via NPM (Recomendado)
```bash
npm install @deeprocket/deep-service-desk-widget
```
### Via Yarn
```bash
yarn add @deeprocket/deep-service-desk-widget
```
### Via CDN
```html
<!-- 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
```javascript
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, {
apiUrl: 'https://sua-api.com/api',
clientUuid: 'seu-client-uuid-aqui', // OBRIGATÓRIO
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
```javascript
import Vue from 'vue'
import App from './App.vue'
import DeepServiceDeskPlugin from '@deeprocket/deep-service-desk-widget'
// Configuração do plugin
Vue.use(DeepServiceDeskPlugin, {
apiUrl: 'https://sua-api.com/api',
clientUuid: 'seu-client-uuid-aqui', // OBRIGATÓRIO
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
```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, {
apiUrl: 'https://sua-api.com/api',
clientUuid: 'seu-client-uuid-aqui',
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
```vue
<template>
<div>
<!-- Widget completo de tickets -->
<TicketWidget
:api-url="apiUrl"
:client-uuid="clientUuid"
@ticket-created="onTicketCreated"
@ticket-error="onTicketError"
/>
<!-- Ou use o widget flutuante -->
<FloatingTicketWidget />
<!-- Botão personalizado para abrir o widget -->
<button @click="openTicket">Abrir Suporte</button>
</div>
</template>
<script>
export default {
data() {
return {
apiUrl: 'https://sua-api.com/api',
clientUuid: 'seu-client-uuid-aqui'
}
},
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:**
- `apiUrl` (String): URL da API do Deep Service Desk
- `clientUuid` (String): UUID do cliente (obrigatório)
**Eventos:**
- `@ticket-created`: Emitido quando um ticket é criado com sucesso
- `@ticket-error`: Emitido quando ocorre um erro na criação
### FloatingTicketWidget
Componente que gerencia o widget de ticket de forma invisível, usado internamente pelo botão flutuante.
## 🔧 API e Métodos
### Métodos Globais
Após instalar o plugin, os seguintes métodos ficam disponíveis:
```javascript
// 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
```javascript
// 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:
```javascript
// 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
### Variáveis de Ambiente
O widget suporta configuração via variáveis de ambiente:
```bash
# .env
VITE_API_URL=https://sua-api.com/api
VITE_CLIENT_UUID=seu-client-uuid-aqui
# Para Vue CLI
VUE_APP_API_URL=https://sua-api.com/api
VUE_APP_CLIENT_UUID=seu-client-uuid-aqui
```
### Configuração via Window
```javascript
// Definir configurações globais
window.DEEP_SERVICE_DESK_API_URL = 'https://sua-api.com/api'
window.DEEP_SERVICE_DESK_CLIENT_UUID = 'seu-client-uuid-aqui'
```
### Estilos CSS
O widget inclui estilos padrão, mas você pode personalizá-los:
```css
/* Personalizar o botão flutuante */
#deep-service-desk-floating-btn {
background: linear-gradient(135deg, #your-color 0%, #your-color-2 100%) !important;
bottom: 30px !important;
right: 30px !important;
}
/* 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;
}
```
### 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`:
```javascript
app.use(DeepServiceDeskPlugin, {
apiUrl: 'https://sua-api.com/api',
clientUuid: 'seu-client-uuid-aqui',
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
```javascript
hiddenUrls: ['/admin', 'login', 'checkout']
```
- **Expressões regulares**: Para padrões mais complexos
```javascript
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:**
```javascript
// 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
```vue
<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
```vue
<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.apiUrl = 'https://nova-api.com/api'
},
mostrarBotao() {
this.$deepServiceDeskButton.showFloatingButton()
},
esconderBotao() {
this.$deepServiceDeskButton.hideFloatingButton()
},
verificarVisibilidade() {
// Verificar visibilidade baseada nas URLs configuradas
this.$deepServiceDeskButton.updateUrlVisibility()
}
}
}
</script>
```
### Exemplo com URLs Ocultas
```vue
<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)
```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_API_URL = 'https://sua-api.com/api'
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>
```
## 🔍 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:
```javascript
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:**
```javascript
// Verificar configuração
console.log(this.$deepServiceDesk)
// Mostrar botão manualmente
this.$deepServiceDeskButton.showFloatingButton()
```
#### 3. Formulário não envia
**Possíveis causas:**
- URL da API incorreta
- Problemas de CORS
- Cliente UUID inválido
**Solução:**
```javascript
// Verificar configuração
console.log('API URL:', this.$deepServiceDesk.apiUrl)
console.log('Client UUID:', this.$deepServiceDesk.clientUuid)
// Verificar console do navegador para erros de rede
```
#### 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:
```bash
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:
```javascript
// Logs do widget começam com emojis:
// 🚀 Instalação do plugin
// 🔧 Configuração
// ✅ Sucesso
// ⚠️ Avisos
// ❌ Erros
```
## 📄 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](https://github.com/deeprocket/deep-service-desk-widget/issues).