Instalación

Guía de instalación del SofIA SDK

SofIA SDK está disponible como un paquete npm que puede integrarse en proyectos web modernos. Elija el método de instalación que mejor se adapte a su entorno de desarrollo.

​

Métodos de instalación

​

Opción 1: NPM/Yarn (Recomendado)

Esta es la opción recomendada para la mayoría de proyectos que utilizan bundlers modernos como Webpack, Vite, o similares.

​

Instalación con NPM

npm install @omniloy/sofia-sdk

​

Instalación con Yarn

yarn add @omniloy/sofia-sdk

​

Importación en su proyecto

// En su archivo principal (main.js, app.js, index.js, etc.)
import '@omniloy/sofia-sdk';

Una vez importado, el componente <sofia-sdk> estará disponible globalmente en toda su aplicación.

​

Opción 2: CDN

Ideal para prototipado rápido, desarrollo sin bundler, o integración en sistemas legacy.

<script src="https://unpkg.com/@omniloy/sofia-sdk@latest/dist/webcomponents.umd.js"></script>

​

Para versión específica

<script src="https://unpkg.com/@omniloy/sofia-sdk@1.0.8/dist/webcomponents.umd.js"></script>

​

Opción 3: Build manual

Para proyectos con pipelines de build personalizados que ya tienen el paquete instalado vía npm.

<script src="/dist/webcomponents.umd.js"></script>

​

Verificación de instalación

Después de la instalación, puede verificar que el componente está disponible:

​

En el navegador

Abra las herramientas de desarrollador y ejecute:

console.log(customElements.get('sofia-sdk'));

Debería mostrar la definición del componente en lugar de undefined.

​

En su HTML

Pruebe añadir el componente básico:

<sofia-sdk></sofia-sdk>

Si la instalación fue exitosa, verá un mensaje indicando que faltan propiedades requeridas.

​

Compatibilidad

​

Navegadores soportados

• Chrome: 80+
• Firefox: 75+
• Safari: 13+
• Edge: 80+

​

Frameworks compatibles

• Vanilla JavaScript: Compatibilidad completa
• React: Soporte nativo para Web Components
• Angular: CUSTOM_ELEMENTS_SCHEMA requerido
• Svelte: Compilador compatible. Svelte funciona directamente — no se necesita una guia dedicada. Importa el SDK en la etiqueta <script> de tu componente y usa <sofia-sdk> directamente en tu template.

​

Frameworks SSR (Next.js, Nuxt)

SofIA SDK es un Web Component solo para el lado del cliente. Depende de APIs del navegador (customElements, WebSocket, getUserMedia, localStorage) que no existen en entornos de servidor. Debe deshabilitar el renderizado del lado del servidor para cualquier componente que importe el SDK.

Next.js — App Router

'use client';

import dynamic from 'next/dynamic';

const SofiaSDK = dynamic(() => import('@omniloy/sofia-sdk').then(() => {
  return { default: () => <sofia-sdk /* props */ /> };
}), { ssr: false });

export default function ConsultationPage() {
  return <SofiaSDK />;
}

Next.js — Pages Router

import dynamic from 'next/dynamic';

const SofiaSDK = dynamic(() => import('@omniloy/sofia-sdk').then(() => {
  return { default: () => <sofia-sdk /* props */ /> };
}), { ssr: false });

export default function ConsultationPage() {
  return <SofiaSDK />;
}

Nuxt 3

Template del componente:

<template>
  <ClientOnly>
    <sofia-sdk /* props */ ></sofia-sdk>
  </ClientOnly>
</template>

Crea el archivo de plugin a continuacion. El sufijo .client asegura que Nuxt solo lo cargue en el navegador:

plugins/sofia-sdk.client.ts

export default defineNuxtPlugin(() => {
  import('@omniloy/sofia-sdk');
});

​

Requisitos del entorno

​

Protocolo HTTPS

SofIA SDK requiere HTTPS para funcionalidades de audio y micrófono:

• Desarrollo local: https://localhost o use herramientas como local-ssl-proxy
• Producción: Certificado SSL válido obligatorio

​

Content Security Policy (CSP)

Si su aplicación usa CSP, añada las siguientes directivas:

connect-src 'self' https://*.omniloy.com wss://*.omniloy.com;
script-src 'self' 'unsafe-inline' https://unpkg.com;

​

Seguridad en Producción

El apikey es visible en el código fuente del lado del cliente. Dado que apikey se pasa como atributo HTML, cualquier persona puede verlo mediante las DevTools del navegador. Para despliegues en producción, usa un proxy en tu backend para mantener la clave en el servidor, y solicita allowlisting de IPs a Omniloy como capa adicional.

​

Recomendado: Proxy en Backend

Enruta el tráfico REST del SDK a través de tu propio backend para que la API key real nunca llegue al navegador. El proxy intercepta las peticiones del SDK, inyecta la API key en el servidor y las reenvía a Omniloy.

// server.js (Node.js / Express)
const express = require('express');
const { createProxyMiddleware } = require('http-proxy-middleware');

const app = express();

// Proxy de llamadas REST — el SDK envía peticiones a /sofia-api/*
// y el proxy las reenvía a Omniloy con la API key real
app.use('/sofia-api', createProxyMiddleware({
  target: process.env.SOFIA_BASE_URL,  // ej. https://api.omniloy.com
  changeOrigin: true,
  pathRewrite: { '^/sofia-api': '' },
  onProxyReq: (proxyReq) => {
    proxyReq.setHeader('x-api-key', process.env.SOFIA_API_KEY);
  },
}));

app.listen(3000);

Luego apunta el baseurl del SDK a tu proxy. El atributo apikey sigue siendo requerido por el SDK — usa un valor placeholder ya que el proxy inyecta la clave real:

<sofia-sdk
  baseurl="https://your-domain.com/sofia-api"
  apikey="proxy-managed"
  userid="doctor-123"
  patientid="patient-456"
></sofia-sdk>

Resolución automática del endpoint y el proxy. Para las claves más nuevas el SDK normalmente auto-resolvería el endpoint. Para enrutar el tráfico REST a través de tu proxy, pasa un baseurl explícito que apunte al proxy (como se muestra arriba) — un baseurl explícito siempre tiene prioridad sobre la resolución automática.

wssurl está deprecada y se ignora desde la v1.0.7. La URL WebSocket de transcripción ahora la proporciona automáticamente la settings API — no hay wssurl que hacer proxy. Contacta a [e-mail] si tu infraestructura necesita enrutar el tráfico WebSocket del transcriber; el equipo de Omniloy puede asesorarte sobre el mejor enfoque.

​

Allowlisting de IPs

Como capa adicional de protección, Omniloy puede restringir el uso de la API key a direcciones IP específicas. Esto es especialmente útil con un proxy en backend, donde todo el tráfico proviene de la IP fija de tu servidor. Contacta a [e-mail] para configurar el allowlisting de IPs para tus claves de producción.

​

Solución de problemas comunes

​

El componente no se carga

1. Verifique que la importación esté en el archivo principal
2. Confirme que no hay errores en la consola del navegador
3. Verifique la conectividad de red si usa CDN

​

Errores de CORS

• Asegúrese de servir su aplicación desde HTTPS
• Para las claves más nuevas el endpoint se resuelve automáticamente; si tu clave requiere baseurl, verifica que su URL sea correcta

​

Componente no definido

// Espere a que el componente esté definido
customElements.whenDefined('sofia-sdk').then(() => {
  console.log('SofIA SDK está listo');
});

​

Próximos pasos

Una vez completada la instalación:

1. Propiedades requeridas: Configure los parámetros obligatorios
2. Propiedades opcionales: Personalice el comportamiento
3. Esquemas de datos clínicos: Defina la estructura de datos a generar