hubdox-chat-sdk

v1.5.0

Published

4 months ago

SDK de JavaScript para integrar chatbots flotantes en sitios web con soporte para registro de usuarios y APIs personalizables

0High
0Medium
0Low

bemtorres

chat sdk hubdox chatbot widget floating javascript api registration

Hubdox Chat SDK

Desarrollado por Bemtorres

Un SDK de JavaScript ligero y fácil de usar para integrar un chatbot flotante en cualquier sitio web. El widget de chat es altamente personalizable y se integra a la perfección con las API de chat existentes.

🚀 Características

Widget flotante: Un botón flotante que se expande en un panel de chat completo.
Diseño adaptable: Se adapta automáticamente a diferentes tamaños de pantalla.
Modo de pantalla completa en móviles: Expansión automática a pantalla completa en dispositivos móviles.
Pantalla de registro separada: Una pantalla de bienvenida independiente donde el bot saluda y solicita el nombre del usuario antes de iniciar el chat.
Altamente personalizable: Colores, textos, imágenes y estilos configurables.
Integración sencilla: Una sola línea de código para implementarlo.
Shadow DOM: Aislamiento total de CSS para evitar conflictos con frameworks existentes
Modales propios: Sistema de modales independiente sin dependencias externas
Bootstrap opcional: Soporte para Bootstrap 5 con opción de deshabilitar
Soporte para avatares: Imágenes de perfil para el usuario y el bot.
Indicador de escritura: Muestra cuándo el bot está procesando una respuesta.
Gestión de estado: Manejo automático de mensajes y sesiones, con caché opcional.
Diseño minimalista: Interfaz limpia y fácil de usar.
Sistema simplificado: Solo 2 API (registro y mensaje).
Configuración automática: El bot se configura automáticamente desde la API.
Actualización dinámica: La interfaz de usuario se actualiza automáticamente con la configuración del bot.
Modo de prueba: Un modo de prueba para el desarrollo y las pruebas sin una API en vivo.
Soporte Markdown: Renderizado automático de texto Markdown en las respuestas del bot.
Streaming simulado: Efecto de typing carácter por carácter para simular escritura en tiempo real.
Modo desarrollo: Sistema de logging configurable para desarrollo y producción.

📦 Instalación

CDN (Recomendado)

Última versión:

<script src="https://cdn.jsdelivr.net/npm/hubdox-chat-sdk"></script>

NPM

npm install hubdox-chat-sdk

import ChatBot from 'hubdox-chat-sdk';

🛠️ Uso Básico

const chat = new ChatBot({
  baseUrl: 'https://tu-api.com',
  apiKey: 'tu-api-key',
  tenant: 'tu-tenant',
  options: {
    register: true, // Opcional: solicita información del usuario al iniciar
  },
  user: {
    name: 'Usuario',
    email: '[email protected]',
    photo: 'https://ejemplo.com/avatar.jpg'
  },
  bot: {
    name: 'Asistente',
    img: 'https://ejemplo.com/bot-avatar.jpg'
  }
});

⚙️ Configuración

Opciones Requeridas

| Parámetro | Tipo | Descripción | |-----------|--------|----------------------------------------| | baseUrl | string | URL base de tu API de chat | | apiKey | string | Clave de API para autenticación (token Bearer) | | tenant | string | Identificador del tenant/organización |

Objeto `options` (Opcional)

| Parámetro | Tipo | Por defecto | Descripción | |------------|---------|-------------|-----------------------------------------------------------------------------| | register | boolean | false | Si es true, muestra una pantalla de registro donde el bot solicita el nombre del usuario antes de iniciar el chat. | | show | boolean | true | Muestra u oculta el widget de chat en la inicialización. | | cache | boolean | false | Habilita o deshabilita el almacenamiento en caché de la sesión de chat y los mensajes. | | cacheExpiration | number | 30 | Tiempo de expiración del cache en minutos. Por defecto 30 minutos. | | testMode | boolean | false | Habilita o deshabilita el modo de prueba. | | stream | boolean | false | Si es true, simula el efecto de typing mostrando el mensaje carácter por carácter. | | devMode | boolean | false | Habilita logs de desarrollo. En producción debe ser false. | | useShadowDOM | boolean | true | Si es true, usa Shadow DOM para aislamiento de CSS. Si es false, usa Bootstrap. | | maxQuestionLength | number | 50 | Límite máximo de caracteres para las preguntas del usuario. Incluye contador visual y validación en tiempo real. |

Objeto `user` (Opcional)

| Parámetro | Tipo | Por defecto | Descripción | |-----------|--------|------------------------------------------------------------------------------------------|--------------------------| | name | string | 'Usuario' | Nombre del usuario. | | email | string | '[email protected]' | Correo electrónico del usuario. | | photo | string | 'https://res.cloudinary.com/dienilw2p/image/upload/v1747635921/hubdox/lgvqg0648leq6meeusid.png' | URL de la foto de perfil del usuario. |

Objeto `bot` (Opcional)

| Parámetro | Tipo | Por defecto | Descripción | |-----------|--------|------------------------------------------------------------------------------------------|-----------------------| | name | string | 'Bot' | Nombre del bot. | | img | string | 'https://res.cloudinary.com/dienilw2p/image/upload/v1747635921/hubdox/xevgjbvb1ri3ytpletzk.png' | URL de la imagen del bot. |

Objeto `custom` (Opcional)

| Parámetro | Tipo | Por defecto | Descripción | |---------------------|---------|--------------------|--------------------------------------------------------------------------| | primaryColor | string | '#0d6efd' | El color principal del widget de chat. | | botName | string | 'Bot' | El nombre del bot que se muestra en el encabezado. | | headerBgColor | string | primaryColor | El color de fondo del encabezado del chat. | | headerTextColor | string | '#ffffff' | El color del texto del encabezado del chat. | | sendButtonText | string | null | El texto del botón de enviar. | | iconButton | string | null | La URL de un icono personalizado para el botón flotante. | | chatWidth | string | '400px' | El ancho del panel de chat en el escritorio. | | chatHeight | string | '60vh' | La altura del panel de chat en el escritorio. | | chatMaxWidth | string | '90vw' | El ancho máximo del panel de chat en móviles. | | chatMaxHeight | string | '60vh' | La altura máxima del panel de chat en móviles. | | messagesHeight | string | '350px' | La altura del contenedor de mensajes. | | buttonSize | string | '56px' | El tamaño del botón flotante. | | fullscreenEnabled | boolean | true | Habilita o deshabilita el modo de pantalla completa en móviles. | | showTime | boolean | true | Si es true, muestra la hora en cada mensaje del chat. | | position | object | { bottom: '24px', right: '24px' } | La posición del botón flotante con propiedades top, bottom, left, right y transform. |

📝 Ejemplos

Ejemplo Básico

<!DOCTYPE html>
<html>
<head>
  <title>Mi Sitio Web</title>
</head>
<body>
  <h1>Bienvenido a mi sitio</h1>
  
  <script src="https://cdn.jsdelivr.net/npm/[email protected]"></script>
  <script>
    const chat = new ChatBot({
      baseUrl: 'https://mi-api.com',
      apiKey: 'mi-api-key-123',
      tenant: 'mi-tenant',
      options: {
        register: true, // Habilita el registro conversacional
      },
      user: {
        name: 'Juan Pérez',
        email: '[email protected]',
        photo: 'https://ejemplo.com/juan-avatar.jpg'
      },
      bot: {
        name: 'Asistente Virtual',
        img: 'https://ejemplo.com/bot-avatar.jpg'
      }
    });
  </script>
</body>
</html>

Ejemplo con Pantalla de Registro

const chat = new ChatBot({
  baseUrl: 'https://api.miempresa.com',
  apiKey: 'sk-1234567890abcdef',
  tenant: 'miempresa-prod',
  options: {
    register: true, // Habilita la pantalla de registro
  },
  user: {
    name: 'Usuario', // Se mostrará pantalla de registro
    email: '[email protected]',
    photo: 'https://miempresa.com/avatars/default.jpg'
  },
  bot: {
    name: 'Asistente Virtual',
    img: 'https://miempresa.com/bots/asistente.jpg'
  },
  custom: {
    primaryColor: '#ff6b35',
    botName: 'Soporte IA',
    headerBgColor: '#2c3e50',
    headerTextColor: '#ecf0f1',
    sendButtonText: 'Enviar Mensaje',
    showTime: true
  }
});

Ejemplo Personalizado (Sin Registro)

const chat = new ChatBot({
  baseUrl: 'https://api.miempresa.com',
  apiKey: 'sk-1234567890abcdef',
  tenant: 'miempresa-prod',
  options: {
    register: false, // No muestra pantalla de registro
  },
  user: {
    name: 'María García', // Usuario ya registrado
    email: '[email protected]',
    photo: 'https://miempresa.com/avatars/maria.jpg'
  },
  bot: {
    name: 'Soporte Técnico',
    img: 'https://miempresa.com/bots/soporte.jpg'
  },
  custom: {
    primaryColor: '#ff6b35',
    botName: 'Soporte IA',
    headerBgColor: '#2c3e50',
    headerTextColor: '#ecf0f1',
    sendButtonText: 'Enviar Mensaje',
    showTime: true
  }
});

Ejemplo con Streaming

const chat = new ChatBot({
  baseUrl: 'https://api.miempresa.com',
  apiKey: 'sk-1234567890abcdef',
  tenant: 'miempresa-prod',
  options: {
    register: true,
    stream: true,      // Habilita el efecto de streaming
    devMode: true,     // Logs de desarrollo (solo para desarrollo)
  },
  user: {
    name: 'Usuario',
    email: '[email protected]',
    photo: 'https://miempresa.com/avatars/default.jpg'
  },
  bot: {
    name: 'Asistente IA',
    img: 'https://miempresa.com/bots/asistente.jpg'
  },
  custom: {
    primaryColor: '#6366f1',
    botName: 'Asistente Virtual',
    headerBgColor: '#4f46e5',
    headerTextColor: '#ffffff',
    showTime: true
  }
});

🔧 API del Servidor

El SDK está diseñado para comunicarse con dos puntos finales principales en su servidor backend.

1. Registro de Sesión (`/api/sdk/v1/register`)

Este punto final se llama cuando se inicializa el widget de chat. Su propósito es registrar una nueva sesión de chat y obtener la configuración inicial del bot y la licencia.

Método: POST
Encabezados:
- Authorization: Bearer {apiKey}
- Content-Type: application/json

Parámetros de Envío (Request Body)

| Parámetro | Tipo | Requerido | Descripción | |-----------|--------|-----------|---------------------------------------| | apiKey | string | Sí | La clave de API para la autenticación. | | tenant | string | Sí | El identificador del tenant/organización. |

Ejemplo de Envío:

{
  "apiKey": "sk-1234567890abcdef",
  "tenant": "mi-tenant"
}

Parámetros de Recibo (Response Body)

| Parámetro | Tipo | Descripción | |-----------|--------|---------------------------------------------------------------------------------------------------------| | session | string | Un identificador único para la sesión de chat. El SDK lo almacenará y lo enviará en las solicitudes de mensajes posteriores. | | license | object | Un objeto que contiene información sobre la licencia del cliente. | | chatbot | object | Un objeto que contiene la configuración del bot. |

Estructura del Objeto license:

| Parámetro | Tipo | Descripción | |--------------|---------|--------------------------------------------------------| | name | string | El nombre del titular de la licencia (por ejemplo, "Hubdox"). | | logo | string | La URL del logo del titular de la licencia. | | active | boolean | Indica si la licencia está activa. | | url | string | La URL a la que enlazará el pie de página de la licencia. | | showFooter | boolean | Si es true, se mostrará un pie de página "Powered by". |

Estructura del Objeto chatbot:

| Parámetro | Tipo | Descripción | |-------------------|--------|-------------------------------------------------------| | name | string | El nombre del bot (por ejemplo, "Asistente Virtual"). | | photo | string | La URL de la imagen de perfil del bot. | | initial_message | string | El primer mensaje que el bot enviará al usuario. |

Ejemplo de Recibo:

{
  "session": "sess_a1b2c3d4e5f6",
  "license": {
    "name": "Hubdox",
    "logo": "https://cdn.hubdox.com/logo.png",
    "active": true,
    "url": "https://hubdox.com",
    "showFooter": true
  },
  "chatbot": {
    "name": "Asistente de Ventas",
    "photo": "https://cdn.example.com/bot-avatar.png",
    "initial_message": "¡Hola! 👋 ¿Cómo puedo ayudarte a encontrar el producto perfecto hoy?"
  }
}

2. Envío de Mensajes (`/api/sdk/v1/message`)

Este punto final se llama cada vez que un usuario envía un mensaje a través del widget de chat.

Método: POST
Encabezados:
- Authorization: Bearer {apiKey}
- Content-Type: application/json

Parámetros de Envío (Request Body)

| Parámetro | Tipo | Requerido | Descripción | |-----------|--------|-----------|--------------------------------------------------| | apiKey | string | Sí | La clave de API para la autenticación. | | tenant | string | Sí | El identificador del tenant/organización. | | session | string | Sí | El ID de sesión obtenido del punto final de registro. | | message | string | Sí | El mensaje de texto del usuario. | | name | string | No | El nombre del usuario. | | stream | boolean| No | Si es true, indica que se debe usar streaming. |

Ejemplo de Envío:

{
  "apiKey": "sk-1234567890abcdef",
  "tenant": "mi-tenant",
  "session": "sess_a1b2c3d4e5f6",
  "message": "Hola, me gustaría saber más sobre el producto X.",
  "name": "Juan Pérez",
  "stream": false
}

Parámetros de Recibo (Response Body)

| Parámetro | Tipo | Descripción | |-----------|--------|---------------------------------| | answer | string | La respuesta de texto del bot. |

Nota sobre Streaming: Si stream: true se envía en la solicitud, el SDK simulará el efecto de streaming mostrando la respuesta carácter por carácter, independientemente de si el servidor soporta streaming real o no.

Ejemplo de Recibo:

{
  "answer": "¡Claro! El producto X es una de nuestras mejores opciones. ¿Qué te gustaría saber específicamente sobre él?"
}

🎯 Flujo del Menú

El chatbot implementa un flujo mejorado que incluye un menú inicial con opciones para el usuario, seguido de una captura del nombre y email antes de comenzar la conversación principal.

Flujo del Usuario

Mensaje Inicial: El bot muestra "Hola soy tu asistente ¿Qué gustaría hacer?" (solo si el usuario tiene información completa)
Registro Obligatorio: Si el usuario no tiene nombre o email válidos, se muestra automáticamente la pantalla de registro
Menú de Opciones: Se muestran tres botones:
- 🛍️ Producto: Muestra productos disponibles (si hay)
- ❓ Pregunta Frecuente: Muestra FAQs (si hay)
- 💬 Iniciar Conversación: Comienza el flujo de captura de datos
Captura de Datos:
- Primero pregunta usando this.saludoInicial o "¡Hola! Para comenzar, ¿cuál es tu nombre?"
- Luego pregunta "¡Excelente! Ahora ¿cuál es tu email?"
Saludo Personalizado: Después de capturar ambos datos, el bot dice ¡Hola ${nombre}! 👋 ¿En qué puedo ayudarte hoy?

Configuración

const chatbot = new ChatBot({
    baseUrl: 'https://api.hubdox.com',
    apiKey: 'your-api-key',
    tenant: 'your-tenant',
    options: {
        register: false,        // No requiere registro inicial
        testMode: true,         // Modo de prueba activado
        show: true,
        cache: false
    }
});

Para más detalles sobre el flujo del menú, consulta MENU_FLOW.md.

📊 Sistema de Estados de Conversación

El chatbot implementa un sistema de estados (status_conversation) que controla el flujo de la conversación de manera estructurada:

Estados Disponibles

PRESENTATION: Bot se presenta y muestra menú de opciones
ASKING_NAME: Bot solicita el nombre del usuario (solo si options.user.name == null)
CHAT_READY: Chat completamente funcional para conversación

Métodos Disponibles

getConversationStatus(): Obtiene el estado actual de la conversación
getRegistrationStatus(): Obtiene el estado del registro

Ejemplo de Uso

// Obtener estado actual
const status = chatbot.getConversationStatus();
console.log('Estado:', status.currentStatus);

// Verificar estado específico
if (status.isPresentation) {
    console.log('Bot en modo presentación');
} else if (status.isAskingName) {
    console.log('Bot preguntando por el nombre');
} else if (status.isChatReady) {
    console.log('Chat listo para conversación');
}

Para más detalles sobre los estados de conversación, consulta STATUS_CONVERSATION.md.

⚙️ Métodos Públicos

`toggleChatPanel()`

Alterna la visibilidad del panel de chat.

chat.toggleChatPanel();

`hideChatPanel()`

Oculta el panel de chat.

chat.hideChatPanel();

`sendMessage(message)`

Envía un mensaje al bot.

chat.sendMessage('Hola, necesito ayuda.');

`clearCache()`

Borra la sesión de chat y los mensajes almacenados en caché.

chat.clearCache();

`reloadFromCache()`

Recarga la sesión de chat y los mensajes desde la caché.

chat.reloadFromCache();

`getCacheStatus()`

Obtiene el estado de la caché.

const status = chat.getCacheStatus();
console.log(status);

`getRegistrationStatus()`

Obtiene el estado del registro del usuario.

const status = chat.getRegistrationStatus();
console.log(status);

`getConversationStatus()`

Obtiene el estado actual de la conversación.

const status = chat.getConversationStatus();
console.log('Estado actual:', status.currentStatus);
console.log('¿Es presentación?', status.isPresentation);
console.log('¿Está preguntando por nombre?', status.isAskingName);
console.log('¿Está listo para chat?', status.isChatReady);

`setMaxQuestionLength(length)`

Configura el límite máximo de caracteres para las preguntas del usuario.

chat.setMaxQuestionLength(300); // Establece límite de 300 caracteres

`getMaxQuestionLength()`

Obtiene el límite actual de caracteres para las preguntas.

const currentLimit = chat.getMaxQuestionLength();
console.log('Límite actual:', currentLimit); // 500 (por defecto)

🎯 Pantalla de Registro

La nueva funcionalidad de pantalla de registro separa claramente el proceso de registro del chat normal, evitando confusiones y mejorando la experiencia del usuario.

¿Cuándo se muestra la pantalla de registro?

La pantalla de registro se muestra automáticamente cuando se cumple alguna de estas condiciones:

Cuando register: true - La opción de registro está habilitada
Cuando el nombre del usuario no existe - El usuario no tiene un nombre válido
Cuando el usuario no está registrado - No se ha completado el proceso de registro

Flujo de la pantalla de registro

Bienvenida: El bot muestra una pantalla de bienvenida con su imagen
Solicitud de nombre: Solicita al usuario que escriba su nombre
Confirmación: Confirma el nombre y transiciona al chat
Chat normal: Inicia el chat con un mensaje personalizado

Ejemplo de configuración

const chat = new ChatBot({
  baseUrl: 'https://tu-api.com',
  apiKey: 'tu-api-key',
  tenant: 'tu-tenant',
  options: {
    register: true, // Habilita la pantalla de registro
    testMode: true  // Para pruebas sin API real
  },
  user: {
    name: "Usuario", // Se mostrará pantalla de registro
    email: '[email protected]'
  }
});

🧪 Modo de Prueba

Cuando testMode: true está habilitado, el widget de chat utiliza un conjunto predefinido de respuestas para fines de prueba, sin necesidad de una API en vivo.

Estados de Conversación en Modo de Prueba

El modo de prueba respeta completamente el sistema de estados de conversación:

PRESENTATION: Bot se presenta y muestra menú (funciona igual que en modo normal)
ASKING_NAME: Solicita nombre del usuario (procesa respuestas como registro)
CHAT_READY: Genera respuestas automáticas usando mensajes predefinidos

Archivos de Prueba para Modo de Prueba

1. Test Completo del Flujo

example/test-mode-status-flow.html - Test automático del flujo completo:

Verificación de que testMode: true esté activado
Test automático del flujo completo de estados
Simulación de interacciones del usuario
Log detallado de todas las transiciones de estado

2. Debug Detallado

example/debug-test-mode.html - Debug completo con interceptación de console:

Monitoreo en tiempo real de todos los estados
Interceptación de logs de console para debugging
Verificación detallada de la configuración
Diagnóstico de problemas del flujo

3. Flujo Simple Paso a Paso

example/simple-test-flow.html - Flujo simplificado para pruebas básicas:

Botones paso a paso para cada etapa del flujo
Verificación del estado después de cada acción
Log claro de cada operación
Ideal para debugging inicial

const chat = new ChatBot({
  // ... otras opciones
  options: {
    testMode: true,
  }
});

📝 Soporte Markdown

El ChatBot incluye soporte completo para renderizar texto Markdown en las respuestas del bot. Los siguientes formatos son soportados:

Formatos Soportados

| Formato | Sintaxis | Resultado | |---------|----------|-----------| | Negrita | **texto** | texto | | Cursiva | *texto* | texto | | Código inline | `código` | código | | Bloque de código | ```código``` | Bloque de código con resaltado | | Enlaces | [texto](url) | Enlaces externos | | Títulos | # Título, ## Subtítulo | Títulos con jerarquía | | Listas | - item o 1. item | Listas ordenadas y no ordenadas |

Ejemplo de Respuesta con Markdown

// El bot puede responder con Markdown
const respuesta = `# ¡Hola! 👋

Te ayudo con **formato Markdown**. Aquí tienes algunos ejemplos:

## Características principales:
- **Negrita** para énfasis
- *Cursiva* para detalles
- \`código inline\` para comandos
- [Enlaces](https://ejemplo.com) para recursos

## Ejemplo de código:
\`\`\`javascript
function saludar() {
    console.log("¡Hola mundo!");
}
\`\`\``;

Seguridad

El parser de Markdown incluye protección contra XSS (Cross-Site Scripting) al escapar automáticamente el HTML malicioso en el texto de entrada.

⚡ Streaming Simulado

El ChatBot SDK incluye una funcionalidad de streaming simulado que permite mostrar las respuestas del bot carácter por carácter, creando un efecto visual similar al de ChatGPT.

¿Cómo funciona?

Cuando stream: true está habilitado:

Indicador de typing: Se muestra el indicador "está escribiendo..." primero
Streaming de texto: El mensaje aparece progresivamente carácter por carácter
Cursor parpadeante: Un cursor animado indica que el bot está "escribiendo"
Velocidad variable: Diferentes velocidades para espacios, puntuación y caracteres normales

Configuración

const chat = new ChatBot({
  // ... otras opciones
  options: {
    stream: true,  // Habilita el streaming simulado
  }
});

Comportamiento

Con stream: true: Mensaje aparece carácter por carácter con cursor parpadeante
Con stream: false: Mensaje aparece completo de una vez

Personalización

El streaming incluye:

Cursor parpadeante con el color primario del chat
Borde izquierdo especial durante el streaming
Fondo degradado sutil para destacar el mensaje
Velocidad variable que simula typing humano

🔤 Límite de Caracteres para Preguntas

El ChatBot SDK incluye una funcionalidad para limitar la longitud de las preguntas del usuario, incluyendo validación en tiempo real y un contador visual.

Características

Límite configurable: Establecer un número máximo de caracteres (por defecto: 500)
Contador visual: Muestra cuántos caracteres se han usado (ej: 45/500)
Validación en tiempo real: El botón de envío se deshabilita cuando se excede el límite
Indicador visual: El input cambia de color cuando se excede el límite
Prevención de envío: No se pueden enviar mensajes que excedan el límite
Configuración dinámica: Cambiar el límite después de la inicialización

Configuración Inicial

const chat = new ChatBot({
  baseUrl: 'https://tu-api.com',
  apiKey: 'tu-api-key',
  tenant: 'tu-tenant',
  options: {
    maxQuestionLength: 300, // Límite de 300 caracteres
  }
});

Configuración Dinámica

// Cambiar límite después de la inicialización
chat.setMaxQuestionLength(200);

// Obtener límite actual
const currentLimit = chat.getMaxQuestionLength();
console.log('Límite actual:', currentLimit);

Casos de Uso

Control de costos: Limitar la longitud para reducir el consumo de tokens en APIs de IA
Mejora de UX: Forzar preguntas más concisas y directas
Prevención de spam: Evitar mensajes excesivamente largos
Optimización de rendimiento: Reducir el tiempo de procesamiento
Consistencia: Mantener un formato estándar en las consultas

Ejemplo Completo

const chat = new ChatBot({
  baseUrl: 'https://api.ejemplo.com',
  apiKey: 'mi-api-key',
  tenant: 'mi-tenant',
  options: {
    maxQuestionLength: 250, // Límite de 250 caracteres
    testMode: true
  }
});

// Inicializar el chat
chat.init();

// Cambiar límite dinámicamente
setTimeout(() => {
  chat.setMaxQuestionLength(150);
  console.log('Nuevo límite:', chat.getMaxQuestionLength());
}, 5000);

🔧 Modo Desarrollo

El SDK incluye un sistema de logging configurable para facilitar el desarrollo y debugging.

Configuración

const chat = new ChatBot({
  // ... otras opciones
  options: {
    devMode: true,  // Habilita logs de desarrollo
  }
});

Tipos de Logs

_log(): Logs informativos generales
_logError(): Errores (siempre visibles)
_logWarn(): Advertencias (solo en modo desarrollo)
_logInfo(): Información adicional (solo en modo desarrollo)
_logDebug(): Información de debugging (solo en modo desarrollo)

Uso en Producción

// Para producción, deshabilitar logs
options: {
  devMode: false,  // Deshabilita logs para mejor rendimiento
}

🔄 Almacenamiento en Caché

El widget de chat puede almacenar en caché la sesión de chat y los mensajes en el almacenamiento local del navegador para mantener la conversación a través de las recargas de la página.

Para deshabilitar el almacenamiento en caché, establece cache: false en el objeto options.

const chat = new ChatBot({
  // ... otras opciones
  options: {
    cache: false,
  }
});

🔒 Shadow DOM

¿Qué es Shadow DOM?

El Shadow DOM es una tecnología web que permite encapsular completamente el CSS y JavaScript de un componente, creando un "árbol DOM sombra" aislado del resto de la página. Esto significa que:

✅ Los estilos CSS no se filtran hacia afuera
✅ Los estilos externos no afectan al componente
✅ JavaScript completamente encapsulado
✅ ¡Perfecto para evitar conflictos de Bootstrap!

Configuración

Por defecto, el SDK usa Shadow DOM para evitar conflictos:

// Configuración por defecto (Shadow DOM activado)
const chatbot = new ChatBot({
    baseUrl: 'https://tu-api.com',
    apiKey: 'tu-api-key',
    tenant: 'tu-tenant',
    options: {
        useShadowDOM: true  // Activado por defecto
    }
});

Usar con Bootstrap (Legacy)

Si necesitas usar Bootstrap por alguna razón específica:

// Para usar con Bootstrap (comportamiento original)
const chatbot = new ChatBot({
    baseUrl: 'https://tu-api.com',
    apiKey: 'tu-api-key',
    tenant: 'tu-tenant',
    options: {
        useShadowDOM: false  // Desactivar Shadow DOM
    }
});

Ventajas del Shadow DOM

| Característica | Shadow DOM | Bootstrap | |----------------|------------|-----------| | Aislamiento CSS | ✅ Total | ❌ Conflictos | | Dependencias | ✅ Ninguna | ❌ Bootstrap 5.3.0 | | Performance | ✅ Mejor | ❌ Más peso | | Conflictos | ✅ Ninguno | ❌ Posibles | | Personalización | ✅ Fácil | ❌ Limitada |

🎨 Personalización

Colores

Puedes personalizar completamente la apariencia del widget:

const chat = new ChatBot({
  // ... otras opciones
  custom: {
    primaryColor: '#e74c3c',      // Color principal
    headerBgColor: '#2c3e50',     // Fondo del encabezado
    headerTextColor: '#ffffff',   // Texto del encabezado
  }
});

Textos

Personaliza los textos que aparecen en el widget:

const chat = new ChatBot({
  // ... otras opciones
  custom: {
    botName: 'Mi Asistente Personal',
    sendButtonText: 'Enviar Mensaje'
  }
});

🔧 Métodos de Cache

El SDK incluye métodos para gestionar el cache de sesión:

Configuración de Cache

// Habilitar/deshabilitar cache
chat.setCacheEnabled(true);

// Configurar tiempo de expiración (en minutos)
chat.setCacheExpiration(60); // 1 hora

// Obtener estado del cache
const cacheStatus = chat.getCacheStatus();
console.log('Cache habilitado:', cacheStatus.enabled);
console.log('Expira en:', cacheStatus.expiration, 'minutos');
console.log('¿Es válido?', cacheStatus.isValid);

Métodos Disponibles

| Método | Descripción | |--------|-------------| | setCacheEnabled(enabled) | Habilita o deshabilita el cache | | setCacheExpiration(minutes) | Configura el tiempo de expiración en minutos | | getCacheStatus() | Obtiene el estado completo del cache | | getCacheExpiration() | Obtiene el tiempo de expiración actual |

Características del Cache

Guardado Automático: Se guarda después de cada mensaje
Expiración Configurable: Por defecto 30 minutos
Limpieza Automática: Se elimina automáticamente al expirar
Recuperación de Estado: Restaura mensajes, usuario y configuración
Persistencia Local: Almacenado en localStorage del navegador

📁 Archivos de Ejemplo

El SDK incluye varios archivos de ejemplo para diferentes casos de uso:

Archivos Principales

example/text.html: Ejemplo básico con todas las funcionalidades
example/streaming-test.html: Prueba específica del streaming simulado
example/shadow-dom-example.html: Ejemplo completo con Shadow DOM
example/options-menu.html: Configurador visual con Bootstrap
example/options-menu-tailwind.html: Configurador visual con Tailwind CSS
example/registration-screen-example.html: Ejemplo de pantalla de registro
example/session-cache.html: Ejemplo completo de cache de sesión por 30 minutos
index.html: 30 ejemplos diferentes de configuración

Pruebas

tests/: Suite completa de pruebas unitarias
tests/RegistrationScreen.test.js: Pruebas específicas para pantalla de registro
tests/streaming.test.js: Pruebas para funcionalidad de streaming

🚀 Despliegue

Desarrollo Local

Clona el repositorio.
Abre example/streaming-test.html para probar el streaming.
Abre example/text.html para ver todas las funcionalidades.
Modifica la configuración según tus necesidades.

Producción

Incluye el script desde CDN.
Configura tu punto final de la API.
Personaliza la apariencia según tu marca.

🤝 Contribuir

Haz un fork del proyecto.
Crea una rama para tu característica (git checkout -b feature/AmazingFeature).
Confirma tus cambios (git commit -m 'Add some AmazingFeature').
Empuja a la rama (git push origin feature/AmazingFeature).
Abre una Pull Request.

📄 Licencia

Este proyecto está bajo la Licencia ISC. Consulta el archivo LICENSE para más detalles.

👨‍💻 Autor

Bemtorres

GitHub: @bemtorres

🙏 Agradecimientos

Bootstrap por el framework CSS.
Cloudinary por el alojamiento de imágenes predeterminado.

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

Hubdox Chat SDK

🚀 Características

📦 Instalación

CDN (Recomendado)

NPM

🛠️ Uso Básico

⚙️ Configuración

Opciones Requeridas

Objeto options (Opcional)

Objeto user (Opcional)

Objeto bot (Opcional)

Objeto custom (Opcional)

📝 Ejemplos

Ejemplo Básico

Ejemplo con Pantalla de Registro

Ejemplo Personalizado (Sin Registro)

Ejemplo con Streaming

🔧 API del Servidor

1. Registro de Sesión (/api/sdk/v1/register)

Parámetros de Envío (Request Body)

Parámetros de Recibo (Response Body)

2. Envío de Mensajes (/api/sdk/v1/message)

Parámetros de Envío (Request Body)

Parámetros de Recibo (Response Body)

🎯 Flujo del Menú

Flujo del Usuario

Configuración

📊 Sistema de Estados de Conversación

Estados Disponibles

Métodos Disponibles

Ejemplo de Uso

⚙️ Métodos Públicos

toggleChatPanel()

hideChatPanel()

sendMessage(message)

clearCache()

reloadFromCache()

getCacheStatus()

getRegistrationStatus()

getConversationStatus()

setMaxQuestionLength(length)

getMaxQuestionLength()

🎯 Pantalla de Registro

¿Cuándo se muestra la pantalla de registro?

Flujo de la pantalla de registro

Ejemplo de configuración

🧪 Modo de Prueba

Estados de Conversación en Modo de Prueba

Archivos de Prueba para Modo de Prueba

1. Test Completo del Flujo

2. Debug Detallado

3. Flujo Simple Paso a Paso

📝 Soporte Markdown

Formatos Soportados

Ejemplo de Respuesta con Markdown

Seguridad

⚡ Streaming Simulado

¿Cómo funciona?

Configuración

Comportamiento

Personalización

🔤 Límite de Caracteres para Preguntas

Características

Configuración Inicial

Configuración Dinámica

Casos de Uso

Ejemplo Completo

🔧 Modo Desarrollo

Configuración

Tipos de Logs

Uso en Producción

🔄 Almacenamiento en Caché

🔒 Shadow DOM

¿Qué es Shadow DOM?

Objeto `options` (Opcional)

Objeto `user` (Opcional)

Objeto `bot` (Opcional)

Objeto `custom` (Opcional)

1. Registro de Sesión (`/api/sdk/v1/register`)

2. Envío de Mensajes (`/api/sdk/v1/message`)

`toggleChatPanel()`

`hideChatPanel()`

`sendMessage(message)`

`clearCache()`

`reloadFromCache()`

`getCacheStatus()`

`getRegistrationStatus()`

`getConversationStatus()`

`setMaxQuestionLength(length)`

`getMaxQuestionLength()`