> ## Documentation Index
> Fetch the complete documentation index at: https://omniloy.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

```bash theme={null}
npm install @omniloy/sofia-sdk
```

#### Instalación con Yarn

```bash theme={null}
yarn add @omniloy/sofia-sdk
```

#### Importación en su proyecto

```javascript theme={null}
// 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.

```html theme={null}
<script src="https://unpkg.com/@omniloy/sofia-sdk@latest/dist/webcomponents.umd.js"></script>
```

#### Para versión específica

```html theme={null}
<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.

```html theme={null}
<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:

```javascript theme={null}
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:

```html theme={null}
<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)

<Warning>
  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.
</Warning>

**Next.js — App Router**

```tsx theme={null}
'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**

```tsx theme={null}
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:

```vue theme={null}
<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:

```typescript plugins/sofia-sdk.client.ts theme={null}
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

<Warning>
  **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.
</Warning>

### 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.

```javascript theme={null}
// 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:

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

<Info>
  **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.
</Info>

<Warning>
  **`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 **[support@omniloy.com](mailto:support@omniloy.com)** si tu infraestructura necesita enrutar el tráfico WebSocket del transcriber; el equipo de Omniloy puede asesorarte sobre el mejor enfoque.
</Warning>

### 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 **[support@omniloy.com](mailto:support@omniloy.com)** 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

```javascript theme={null}
// 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](/sofia/es/sdk/required-properties)**: Configure los parámetros obligatorios
2. **[Propiedades opcionales](/sofia/es/sdk/optional-properties)**: Personalice el comportamiento
3. **[Esquemas de datos clínicos](/sofia/es/sdk/templates)**: Defina la estructura de datos a generar