1.3.8 • Published 11 months ago

@pedrohrs/deep-service-desk-widget v1.3.8

Weekly downloads
-
License
MIT
Repository
github
Last release
11 months ago

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

  • 🎯 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)

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

Via Yarn

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

Via CDN

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

<!-- JavaScript -->
<script src="https://unpkg.com/@pedrohrs/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 '@pedrohrs/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
})

app.mount('#app')

Vue 2.7.16

import Vue from 'vue'
import App from './App.vue'
import DeepServiceDeskPlugin from '@pedrohrs/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
})

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

Configuração via CDN

<!DOCTYPE html>
<html>
<head>
  <link rel="stylesheet" href="https://unpkg.com/@pedrohrs/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/@pedrohrs/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'
    }).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 
      :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:

// Vue 3
this.$deepServiceDeskButton.showFloatingButton()
this.$deepServiceDeskButton.hideFloatingButton()
this.$deepServiceDeskButton.openTicket()

// Vue 2
this.$deepServiceDeskButton.showFloatingButton()
this.$deepServiceDeskButton.hideFloatingButton()
this.$deepServiceDeskButton.openTicket()

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

Variáveis de Ambiente

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

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

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

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

📚 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>
  </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()
    }
  }
}
</script>

Exemplo sem Vue (HTML Puro)

<!DOCTYPE html>
<html>
<head>
  <title>Widget sem Vue</title>
  <link rel="stylesheet" href="https://unpkg.com/@pedrohrs/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/@pedrohrs/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:

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:

  • URL da API incorreta
  • Problemas de CORS
  • Cliente UUID inválido

Solução:

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

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

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

vuevue2vue3widgetservice-deskticketssupporthelp-deskcustomer-supportticket-systemvue2.7compatibilityvite-fixpackage-json-fix
1.3.8

11 months ago

1.3.7

11 months ago

1.3.6

11 months ago

1.3.5

11 months ago

1.3.4

11 months ago

1.3.3

11 months ago

1.3.2

11 months ago

1.3.1

11 months ago

1.3.0

11 months ago

1.2.3

11 months ago

1.2.2

11 months ago

1.2.1

11 months ago

1.2.0

11 months ago

1.1.0

11 months ago

1.0.1

11 months ago

1.0.0

11 months ago