Skip to main content
This guide shows how to integrate SofIA SDK in applications using native JavaScript without additional frameworks.

​
Initial setup

​
1. Installation

npm install @omniloy/sofia-sdk

​
2. Component import

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>SofIA SDK - Vanilla JS</title>
    
    <!-- Import component -->
    <script type="module">
        import '@omniloy/sofia-sdk';
    </script>
</head>
<body>
    <!-- Component will be available here -->
</body>
</html>

​
Basic implementation

​
HTML Structure

<div id="sofia-container">
    <sofia-sdk
        id="sofia-component"
        baseurl="https://api.example.com/v1"
        wssurl="wss://ws.example.com"
        apikey="sk-your-api-key-here"
        userid="user_12345"
        patientid="patient_67890"
        isopen="false"
        toolsargs='{
            "$schema": "http://json-schema.org/draft-07/schema#",
            "title": "clinical_notes",
            "type": "object",
            "required": ["diagnosis"],
            "properties": {
                "diagnosis": {"type": "string", "description": "Main diagnosis"}
            }
        }'
    ></sofia-sdk>
    
    <button id="toggle-sofia">Open/Close SofIA</button>
</div>

​
JavaScript Configuration

// Wait for component to be defined
customElements.whenDefined('sofia-sdk').then(() => {
    const sofiaComponent = document.getElementById('sofia-component');
    const toggleButton = document.getElementById('toggle-sofia');
    
    // Configure callback to receive reports
    sofiaComponent.handleReport = (report) => {
        console.log('Clinical report received:', report);
        
        // Process report according to your needs
        displayReport(report);
        sendToEHR(report);
    };
    
    // Configure callback for visibility changes
    sofiaComponent.setIsOpen = (isOpen) => {
        console.log('Component state:', isOpen ? 'Open' : 'Closed');
        sofiaComponent.isopen = isOpen;
        toggleButton.textContent = isOpen ? 'Close SofIA' : 'Open SofIA';
    };
    
    // Handle button click
    toggleButton.addEventListener('click', () => {
        const currentState = sofiaComponent.isopen === 'true';
        sofiaComponent.isopen = !currentState;
    });
});

// Function to display report in interface
function displayReport(report) {
    const reportContainer = document.getElementById('report-display');
    if (reportContainer) {
        reportContainer.innerHTML = `
            <h3>Clinical Report</h3>
            <pre>${JSON.stringify(report, null, 2)}</pre>
        `;
    }
}

// Function to send to EHR/HIS system
function sendToEHR(report) {
    // Implement integration with your system
    fetch('/api/clinical-reports', {
        method: 'POST',
        headers: {
            'Content-Type': 'application/json',
        },
        body: JSON.stringify(report)
    }).then(response => {
        console.log('Report sent to EHR:', response.status);
    }).catch(error => {
        console.error('Error sending report:', error);
    });
}

​
State management

​
Visibility control

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

// Open programmatically
function openSofia() {
    sofiaComponent.isopen = true;
}

// Close programmatically  
function closeSofia() {
    sofiaComponent.isopen = false;
}

// Toggle state
function toggleSofia() {
    const isCurrentlyOpen = sofiaComponent.isopen === 'true';
    sofiaComponent.isopen = !isCurrentlyOpen;
}

​
Patient data update

// Update patient information
function updatePatientData(newPatientId, patientInfo) {
    sofiaComponent.patientid = newPatientId;
    sofiaComponent.patientdata = JSON.stringify(patientInfo);
}

// Usage example
updatePatientData('patient_98765', {
    age: 45,
    medical_history: 'Type 2 diabetes, Hypertension',
    allergies: 'Penicillin'
});

​
Error handling

// Listen for component errors
sofiaComponent.addEventListener('error', (event) => {
    console.error('SofIA SDK error:', event.detail);
    
    // Show message to user
    showErrorMessage(event.detail.message);
});

function showErrorMessage(message) {
    const errorDiv = document.createElement('div');
    errorDiv.className = 'error-message';
    errorDiv.textContent = `Error: ${message}`;
    document.body.appendChild(errorDiv);
    
    // Remove after 5 seconds
    setTimeout(() => {
        errorDiv.remove();
    }, 5000);
}

​
Complete example

For a complete and functional implementation, check our GitHub example: View complete Vanilla TypeScript example → The example includes:
  • Complete project setup
  • Advanced state management
  • Integration with mocked APIs
  • Robust error handling
  • Custom CSS styling

​
Additional considerations

​
Performance

  • The component initializes lazily to optimize loading time
  • Use customElements.whenDefined() to avoid race conditions

​
Security

  • Never expose your apikey in client code in production
  • Implement server-side validation for all reports
  • Use HTTPS mandatory for all communications