@pedrohrs/deep-service-desk-widget

v1.3.8

Published

7 months ago

Widget Vue.js para integração com o sistema Deep Service Desk - Versão limpa sem console.logs - Compatível com Vue 2.7.16 e Vue 3 - Com botão flutuante automático

0High
0Medium
0Low

pedrohrs

vue vue2 vue3 widget service-desk tickets support help-desk customer-support ticket-system vue2.7 compatibility vite-fix package-json-fix

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