Saltar al contenido principal
Esta guía muestra cómo integrar SofIA SDK en aplicaciones que utilizan JavaScript nativo sin frameworks adicionales.

​
Configuración inicial

​
1. Instalación

npm install @omniloy/sofia-sdk

​
2. Importación del componente

<!DOCTYPE html>
<html lang="es">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>SofIA SDK - Vanilla JS</title>
    
    <!-- Importar el componente -->
    <script type="module">
        import '@omniloy/sofia-sdk';
    </script>
</head>
<body>
    <!-- El componente estará disponible aquí -->
</body>
</html>

​
Implementación básica

​
Estructura HTML

<div id="sofia-container">
    <!-- language="es" es el valor por defecto (español) -->
    <sofia-sdk
        id="sofia"
        baseurl="https://api.example.com/v1"
        wssurl="wss://ws.example.com"
        apikey="sk-your-api-key-here"
        userid="user_12345"
        patientid="patient_67890"
        templateid="clinical-notes-v1"
        language="es"
        isopen="false"
        showconsentindicator="true"
        template='{
            "$schema": "http://json-schema.org/draft-07/schema#",
            "title": "clinical_notes",
            "type": "object",
            "required": ["diagnosis"],
            "properties": {
                "diagnosis": {"type": "string", "description": "Diagnóstico principal"}
            }
        }'
    ></sofia-sdk>
    
    <button id="toggle-sofia">Abrir/Cerrar SofIA</button>
</div>

​
Configuración JavaScript

// Esperar a que el componente esté definido
customElements.whenDefined('sofia-sdk').then(() => {
    const sofiaComponent = document.getElementById('sofia');
    const toggleButton = document.getElementById('toggle-sofia');
    
    // Configurar callback para recibir reportes
    sofiaComponent.handleReport = (report) => {
        console.log('Reporte clínico recibido:', report);
        
        // Procesar el reporte según sus necesidades
        displayReport(report);
        sendToEHR(report);
    };
    
    // Configurar callback para cambios de visibilidad
    sofiaComponent.setIsOpen = (isOpen) => {
        console.log('Estado del componente:', isOpen ? 'Abierto' : 'Cerrado');
        sofiaComponent.isopen = isOpen;
        toggleButton.textContent = isOpen ? 'Cerrar SofIA' : 'Abrir SofIA';
    };
    
    // Manejar click del botón
    toggleButton.addEventListener('click', () => {
        const currentState = sofiaComponent.getAttribute('isopen') === 'true';
        sofiaComponent.setAttribute('isopen', String(!currentState));
    });
});

// Función para mostrar el reporte en la interfaz
function displayReport(report) {
    const reportContainer = document.getElementById('report-display');
    if (reportContainer) {
        const heading = document.createElement('h3');
        heading.textContent = 'Reporte Clínico';
        const pre = document.createElement('pre');
        pre.textContent = JSON.stringify(report, null, 2);
        reportContainer.replaceChildren(heading, pre);
    }
}

// Función para enviar al sistema EHR/HIS
function sendToEHR(report) {
    // Implementar integración con su sistema
    fetch('/api/clinical-reports', {
        method: 'POST',
        headers: {
            'Content-Type': 'application/json',
        },
        body: JSON.stringify(report)
    }).then(response => {
        console.log('Reporte enviado al EHR:', response.status);
    }).catch(error => {
        console.error('Error enviando reporte:', error);
    });
}

​
Obtener el último reporte

Use el callback set-get-last-report para acceder al último reporte generado para la sesión actual de paciente/usuario. El SDK proporciona una función que retorna una Promise que resuelve al reporte almacenado (o undefined si no existe). 
sofiaComponent.setGetLastReport = (getLastReportFn) => {
    // Guardar la función para uso posterior
    window.getLastSofiaReport = getLastReportFn;
};

// Después, obtener el último reporte
async function fetchLastReport() {
    const report = await window.getLastSofiaReport();
    if (report) {
        console.log('Último reporte:', report);
    }
}
Añada debug="true" al elemento <sofia-sdk> para habilitar logging detallado en consola. Esto es útil durante el desarrollo para rastrear eventos del ciclo de vida del SDK, estado de conexión y validación de configuración.
<sofia-sdk debug="true" ...></sofia-sdk>

​
Gestión de estados

​
Control de visibilidad

const sofiaComponent = document.querySelector('sofia-sdk');

// Abrir programáticamente
function openSofia() {
    sofiaComponent.isopen = true;
}

// Cerrar programáticamente  
function closeSofia() {
    sofiaComponent.isopen = false;
}

// Alternar estado
function toggleSofia() {
    const isCurrentlyOpen = sofiaComponent.getAttribute('isopen') === 'true';
    sofiaComponent.setAttribute('isopen', String(!isCurrentlyOpen));
}

​
Actualización de datos del paciente

// Actualizar información del paciente
function updatePatientData(newPatientId, patientInfo) {
    sofiaComponent.patientid = newPatientId;
    sofiaComponent.patientdata = JSON.stringify(patientInfo);
}

// Ejemplo de uso
updatePatientData('patient_98765', {
    fullName: 'María García',
    birthDate: '1979-03-15',
    extraData: {
        medical_practice: 'Medicina Interna',
        allergies: ['Penicilina'],
        chronic_conditions: ['Diabetes tipo 2', 'Hipertensión']
    }
});
Consulta Datos del paciente para la referencia completa de la estructura de datos.

​
Manejo de errores

El SDK registra todos los errores en la consola del navegador con el prefijo [Sofia SDK]. Habilita debug="true" para ver la salida detallada de errores. Maneja los errores en tus callbacks con try/catch estándar: 
sofiaComponent.handleReport = (report) => {
    try {
        // Procesar el reporte
        sendToEHR(report);
    } catch (error) {
        console.error('Error procesando reporte:', error);
        // Mostrar UI de fallback al usuario
    }
};
Para la lista completa de mensajes de error y sus pasos de resolución, consulta la Referencia de errores.

​
Ejemplo completo

Para ver una implementación completa y funcional, consulte nuestro ejemplo en GitHub: Ver ejemplo completo de Vanilla TypeScript → El ejemplo incluye:
  • Configuración completa del proyecto
  • Manejo avanzado de estados
  • Integración con APIs mockadas
  • Gestión de errores robusta
  • Estilado CSS personalizado

​
Ciclo de vida del componente

​
Añadir el componente

Espera a que el custom element esté definido antes de configurar los callbacks: 
customElements.whenDefined('sofia-sdk').then(() => {
  const sofia = document.querySelector('sofia-sdk');
  sofia.handleReport = handleReport;
});

​
Eliminar el componente (limpieza en SPAs)

Si tu aplicación añade y elimina SofIA dinámicamente (por ejemplo, enrutamiento del lado del cliente), elimina el elemento del DOM al navegar fuera: 
function destroySofia() {
  const sofia = document.querySelector('sofia-sdk');
  if (sofia) {
    sofia.remove();
  }
}
El SDK limpia los recursos internos (conexiones WebSocket, streams de audio) automáticamente cuando el elemento se desconecta del DOM.

​
Consideraciones adicionales

​
Rendimiento

  • El componente se inicializa de forma lazy para optimizar el tiempo de carga
  • Use customElements.whenDefined() para evitar condiciones de carrera

​
Seguridad

  • Nunca exponga su apikey en el código del cliente en producción
  • Implemente validación del lado del servidor para todos los reportes
  • Utilice siempre HTTPS para todas las comunicaciones

​
Próximos pasos

  1. Integración con React
  2. Integración con Angular
  3. Referencia de propiedades requeridas
  4. Referencia de propiedades opcionales