Ocular Widget SDK

Un SDK para integrar fácilmente el widget de Ocular Solution en aplicaciones web. Proporciona una interfaz moderna con soporte para promesas y eventos para una experiencia de integración fluida.

Instalación

npm install ocular-widget-sdk

Compatibilidad

✅ JavaScript puro - Sin configuración adicional
✅ TypeScript - Tipos incluidos automáticamente
✅ Vue 3 - Soporte completo para Composition API y Options API
✅ React - Compatible con todas las versiones
✅ Angular - Tipos TypeScript integrados
✅ Vite, Webpack, Rollup - Soporte para bundlers modernos
✅ Node.js - Detección automática del entorno

Uso en JavaScript (Vanilla/Sin TypeScript)

// ES Modules
import { initOcularWidget, ocularWidgetInstance } from 'ocular-widget-sdk';

// CommonJS
const { initOcularWidget, ocularWidgetInstance } = require('ocular-widget-sdk');

// Funciona igual, sin tipos pero con toda la funcionalidad
await initOcularWidget({ code: 'tu-codigo' });
ocularWidgetInstance.show();

Uso en TypeScript

import { 
  initOcularWidget, 
  ocularWidgetInstance, 
  type InitOptions 
} from 'ocular-widget-sdk';

// Con tipos automáticos e IntelliSense completo
const options: InitOptions = { code: 'tu-codigo' };
await initOcularWidget(options);

const customer = {
  id: '123',
  name: 'Juan Pérez',
  email: '[email protected]'
};

ocularWidgetInstance.setCustomer(customer);

Uso Básico

import { initOcularWidget, ocularWidgetInstance } from 'ocular-widget-sdk';

// IMPORTANTE: initOcularWidget debe ejecutarse UNA SOLA VEZ al cargar la app
// Generalmente en el archivo principal (main.js, index.js, App.js)
try {
  await initOcularWidget({ code: 'tu-codigo-widget' });
  console.log('Widget inicializado correctamente');

  // Mostrar el botón flotante del widget
  await ocularWidgetInstance.show();
} catch (error) {
  console.error('Error inicializando widget:', error);
}

// Después de la inicialización, puedes usar ocularWidgetInstance
// en cualquier componente sin volver a inicializar

API Reference

initOcularWidget(options)

Inicializa y carga el widget de Ocular Solution en la página.

Parámetros:

• options.code (string, requerido): El código único del widget proporcionado por Ocular Solution

Retorna: Promise<string>

• Se resuelve cuando el script del widget se ha cargado exitosamente
• Se rechaza si hay un error durante la carga

Ejemplo:

try {
  const result = await initOcularWidget({ code: 'mi-codigo-widget' });
  console.log(result); // "Script cargado exitosamente"
} catch (error) {
  console.error('Error:', error.message);
}

Casos especiales:

• Si ya se inicializó anteriormente, retorna "Ya inicializado"
• Si el script ya existe en el DOM, retorna "Script ya existe"
• Si no se proporciona código, rechaza con error

ocularWidgetInstance

Instancia principal del widget que proporciona métodos para controlar y escuchar eventos.

Métodos

show(opened = false)

Muestra el widget en la página.

⚠️ IMPORTANTE: Este método debe ejecutarse después de que se emita el evento is-ready.

Parámetros:

• opened (boolean, opcional):
  • false (por defecto): Muestra solo el botón flotante del widget
  • true: Abre completamente el widget mostrando su contenido

Retorna: Promise<string> - "success" cuando se completa

Ejemplos:

// Esperar a que el widget esté listo
ocularWidgetInstance.on('is-ready', async () => {
  // Mostrar solo el botón flotante (icono circular)
  await ocularWidgetInstance.show();
  
  // Abrir el widget completamente
  await ocularWidgetInstance.show(true);
});

hide()

Oculta el widget de la página.

⚠️ IMPORTANTE: Este método debe ejecutarse después de que se emita el evento is-ready.

Retorna: Promise<string> - "success" cuando se completa

Ejemplo:

ocularWidgetInstance.on('is-ready', async () => {
  await ocularWidgetInstance.hide();
});

toggle()

Alterna la visibilidad del widget (muestra si está oculto, oculta si está visible).

⚠️ IMPORTANTE: Este método debe ejecutarse después de que se emita el evento is-ready.

Retorna: Promise<string> - "success" cuando se completa

Ejemplo:

ocularWidgetInstance.on('is-ready', async () => {
  await ocularWidgetInstance.toggle();
});

setCustomer(customer)

Establece la información del cliente en el widget.

⚠️ IMPORTANTE: Este método debe ejecutarse después de que se emita el evento is-ready.

Parámetros:

• customer (object): Objeto con la información del cliente

Retorna: Promise<string> - "success" cuando se completa

Ejemplo:

ocularWidgetInstance.on('is-ready', async () => {
  await ocularWidgetInstance.setCustomer({
    id: '12345',
    name: 'Juan Pérez',
    email: '[email protected]',
    phone: '+1234567890'
  });
});

setLocale(locale)

Establece el idioma/localización del widget.

⚠️ IMPORTANTE: Este método debe ejecutarse después de que se emita el evento is-ready.

Parámetros:

• locale (string): Código de idioma (ej: 'es', 'en', 'fr')

Retorna: Promise<string> - "success" cuando se completa

Ejemplo:

ocularWidgetInstance.on('is-ready', async () => {
  await ocularWidgetInstance.setLocale('es');
});

Eventos

on(event, callback)

Registra un listener para eventos del widget.

Parámetros:

• event (string): Nombre del evento a escuchar
• callback (function): Función que se ejecuta cuando ocurre el evento

Ejemplo:

ocularWidgetInstance.on('is-ready', (eventData) => {
  console.log('Widget listo:', eventData);
});

off(event)

Remueve todos los listeners de un evento específico.

Parámetros:

• event (string): Nombre del evento

Ejemplo:

ocularWidgetInstance.off('is-ready');

Arquitectura de Uso

Patrón Recomendado

El SDK está diseñado con un patrón "Initialize Once, Use Everywhere" (Inicializar una vez, usar en todas partes):

1. Inicialización (Una sola vez):

   • Ejecuta initOcularWidget() en el archivo principal de tu aplicación
   • Esto carga el script del widget y lo prepara para uso global

2. Uso en componentes:

   • Importa solo ocularWidgetInstance en cualquier componente
   • IMPORTANTE: Espera a que se emita el evento is-ready antes de usar métodos como show(), hide(), toggle(), etc.
   • La instancia está disponible globalmente

Ejemplo Básico

// main.js (Inicialización única)
import { initOcularWidget, ocularWidgetInstance } from 'ocular-widget-sdk';

// Inicializar el widget una sola vez
await initOcularWidget({ code: 'tu-codigo-widget' });

// Esperar a que el widget esté listo
ocularWidgetInstance.on('is-ready', () => {
  console.log('✅ Widget listo para usar');
  // Ahora puedes usar todos los métodos
  ocularWidgetInstance.show();
});

// ===============================================
// cualquier-otro-archivo.js (Uso en componentes)
// ===============================================
import { ocularWidgetInstance } from 'ocular-widget-sdk';

// Asegurarse de que el widget esté listo antes de usar métodos
function useWidget() {
  ocularWidgetInstance.on('is-ready', () => {
    // Métodos disponibles después del evento is-ready
    ocularWidgetInstance.show(true); // Abrir widget
    ocularWidgetInstance.setCustomer({ name: 'Juan', email: '[email protected]' });
  });
}

Eventos Disponibles

El widget emite varios eventos durante su ciclo de vida que puedes escuchar:

Eventos del Sistema

| Evento | Descripción | |--------|-------------| | ready | El widget se ha inicializado y está listo para usar | | script-ready | El script del widget se ha cargado correctamente | | widget-event | Evento genérico que se dispara para todos los eventos del widget |

Eventos del Widget

| Evento | Descripción | |--------|-------------| | is-ready | El widget se creó correctamente y está montado | | minimized | El widget se minimizó | | hidden | El widget se ocultó | | opened | El widget se abrió | | button-displayed | El botón del widget se mostró | | closed | El widget se cerró | | call-started | El widget inició una llamada | | call-ended | El widget finalizó una llamada | | scheduled-success | El widget agendó una cita exitosamente |

Ejemplo Completo

// ============================================
// 📁 main.js o App.js (Inicialización única)
// ============================================
import { initOcularWidget, ocularWidgetInstance } from 'ocular-widget-sdk';

// IMPORTANTE: Esto se ejecuta UNA SOLA VEZ al cargar la app
async function initializeApp() {
  try {
    await initOcularWidget({ code: 'tu-codigo-widget' });
    console.log('✅ Widget inicializado globalmente');

    // Configuración inicial opcional
    await ocularWidgetInstance.show(); // Mostrar botón flotante
  } catch (error) {
    console.error('❌ Error inicializando widget:', error);
  }
}

initializeApp();

// ============================================
// 📁 cualquier-componente.js (Uso en componentes)
// ============================================
import { ocularWidgetInstance } from 'ocular-widget-sdk';

class WidgetManager {
  constructor() {
    this.setupEventListeners();
  }

  setupEventListeners() {
    // Eventos del sistema
    ocularWidgetInstance.on('ready', () => {
      console.log('🚀 Widget system ready');
    });

    // Eventos del widget
    ocularWidgetInstance.on('is-ready', () => {
      console.log('✨ Widget mounted successfully');
    });

    ocularWidgetInstance.on('opened', () => {
      console.log('👁️ Widget opened by user');
    });

    ocularWidgetInstance.on('closed', () => {
      console.log('❌ Widget closed by user');
    });

    ocularWidgetInstance.on('call-started', (eventData) => {
      console.log('📞 Call started:', eventData);
    });

    ocularWidgetInstance.on('call-ended', (eventData) => {
      console.log('📴 Call ended:', eventData);
    });

    ocularWidgetInstance.on('scheduled-success', (eventData) => {
      console.log('📅 Appointment scheduled:', eventData);
    });

    // Evento genérico para debugging
    ocularWidgetInstance.on('widget-event', (eventData) => {
      console.log('📡 Widget event:', eventData);
    });
  }

  // Métodos que pueden ser llamados desde cualquier componente
  async openWidget() {
    try {
      await ocularWidgetInstance.show(true); // Abrir completamente
    } catch (error) {
      console.error('Error opening widget:', error);
    }
  }

  async setCustomerInfo(customerData) {
    try {
      await ocularWidgetInstance.setCustomer(customerData);
      console.log('👤 Customer info updated');
    } catch (error) {
      console.error('Error setting customer:', error);
    }
  }

  async toggleWidget() {
    try {
      await ocularWidgetInstance.toggle();
    } catch (error) {
      console.error('Error toggling widget:', error);
    }
  }

  async changeLanguage(locale) {
    try {
      await ocularWidgetInstance.setLocale(locale);
      console.log(`🌍 Language changed to: ${locale}`);
    } catch (error) {
      console.error('Error changing language:', error);
    }
  }
}

// Uso en componente
const manager = new WidgetManager();

// Ejemplo de uso en eventos del componente
document.getElementById('contact-btn').addEventListener('click', () => {
  manager.openWidget();
});

document.getElementById('customer-form').addEventListener('submit', (e) => {
  const customerData = {
    id: e.target.customerId.value,
    name: e.target.customerName.value,
    email: e.target.customerEmail.value
  };
  manager.setCustomerInfo(customerData);
});

Compatibilidad

Lenguajes y Frameworks

• ✅ JavaScript (ES5+) - Sin configuración adicional necesaria
• ✅ TypeScript - Declaraciones de tipos incluidas automáticamente
• ✅ Vue 3 - Composition API y Options API
• ✅ React - Todas las versiones (16.8+)
• ✅ Angular - Soporte completo con tipos
• ✅ Svelte - Compatible con todos los frameworks modernos
• ✅ Vanilla JavaScript - Uso directo sin frameworks

Navegadores y Entornos

• Navegadores: Chrome, Firefox, Safari, Edge (versiones modernas)
• Entornos: Solo funciona en el cliente (navegador), no en servidor
• Bundlers: Vite, Webpack, Rollup, Parcel
• Module Systems: ES Modules, CommonJS

Configuración Cero

• JavaScript: Funciona inmediatamente sin configuración
• TypeScript: Los tipos se detectan automáticamente
• Bundlers: Compatible con tree-shaking y code splitting

Notas Importantes

1. Solo Cliente: El SDK solo funciona en entornos de navegador, no en servidor
2. Singleton: El widget se inicializa una sola vez por página
3. Inicialización única: initOcularWidget() debe ejecutarse UNA SOLA VEZ al cargar la aplicación (generalmente en main.js, index.js o App.js). Después de eso, ocularWidgetInstance puede ser usado en cualquier componente
4. Evento is-ready: CRÍTICO - Los métodos show(), hide(), toggle(), setCustomer(), setLocale() solo funcionan después de que se emita el evento is-ready
5. Async/Await: Todos los métodos del widget son asíncronos
6. Eventos: Los eventos se disparan automáticamente según las interacciones del usuario
7. Error Handling: Siempre maneja los errores en las promesas
8. Instancia global: Una vez inicializado, ocularWidgetInstance está disponible globalmente para toda la aplicación

Soporte

Para soporte técnico o reportar issues, contacta al equipo de Ocular Solution.