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

# Installation

> SofIA SDK Installation Guide

SofIA SDK is available as an npm package that can be integrated into modern web projects. Choose the installation method that best fits your development environment.

## Installation Methods

### Option 1: NPM/Yarn (Recommended)

This is the recommended option for most projects using modern bundlers like Webpack, Vite, or similar.

#### Installation with NPM

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

#### Installation with Yarn

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

#### Import in your project

```javascript theme={null}
// In your main file (main.js, app.js, index.js, etc.)
import '@omniloy/sofia-sdk';
```

Once imported, the `<sofia-sdk>` component will be available globally throughout your application.

### Option 2: CDN

Ideal for rapid prototyping, bundler-free development, or integration into legacy systems.

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

#### For specific version

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

### Option 3: Manual build

For projects with custom build pipelines that already have the package installed via npm.

```html theme={null}
<script src="/dist/webcomponents.umd.js"></script>
```

## Installation Verification

After installation, you can verify that the component is available:

### In the browser

Open developer tools and run:

```javascript theme={null}
console.log(customElements.get('sofia-sdk'));
```

Should show the component definition instead of `undefined`.

### In your HTML

Try adding the basic component:

```html theme={null}
<sofia-sdk></sofia-sdk>
```

If installation was successful, you'll see a message indicating missing required properties.

## Compatibility

### Supported browsers

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

### Compatible frameworks

* **Vanilla JavaScript**: Full compatibility
* **React**: Native support for Web Components
* **Angular**: CUSTOM\_ELEMENTS\_SCHEMA required
* **Svelte**: Compatible compiler. Svelte works out of the box -- no dedicated guide needed. Import the SDK in your component's `<script>` tag and use `<sofia-sdk>` directly in your template.

### SSR Frameworks (Next.js, Nuxt)

<Warning>
  SofIA SDK is a **client-side only** Web Component. It relies on browser APIs (`customElements`, `WebSocket`, `getUserMedia`, `localStorage`) that do not exist in server environments. You must disable server-side rendering for any component that imports the 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**

Component template:

```vue theme={null}
<template>
  <ClientOnly>
    <sofia-sdk /* props */ ></sofia-sdk>
  </ClientOnly>
</template>
```

Create the plugin file below. The `.client` suffix ensures Nuxt only loads it in the browser:

```typescript plugins/sofia-sdk.client.ts theme={null}
export default defineNuxtPlugin(() => {
  import('@omniloy/sofia-sdk');
});
```

## Environment Requirements

### HTTPS Protocol

SofIA SDK requires HTTPS for audio and microphone functionalities:

* **Local development**: `https://localhost` or use tools like `local-ssl-proxy`
* **Production**: Valid SSL certificate mandatory

### Content Security Policy (CSP)

If your application uses CSP, add the following directives:

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

## Production Security

<Warning>
  **The `apikey` is visible in client-side source code.** Since `apikey` is passed as an HTML attribute, anyone can view it via browser DevTools. For production deployments, use a backend proxy to keep the key server-side, and request IP allowlisting from Omniloy as an additional layer.
</Warning>

### Recommended: Backend Proxy

Route SDK REST traffic through your own backend so the real API key never reaches the browser. The proxy intercepts requests from the SDK, injects the API key server-side, and forwards them to Omniloy.

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

const app = express();

// Proxy REST API calls — the SDK sends requests to /sofia-api/*
// and the proxy forwards them to Omniloy with the real API key
app.use('/sofia-api', createProxyMiddleware({
  target: process.env.SOFIA_BASE_URL,  // e.g. https://api.omniloy.com
  changeOrigin: true,
  pathRewrite: { '^/sofia-api': '' },
  onProxyReq: (proxyReq) => {
    proxyReq.setHeader('x-api-key', process.env.SOFIA_API_KEY);
  },
}));

app.listen(3000);
```

Then point the SDK's `baseurl` at your proxy. The `apikey` attribute is still required by the SDK — use a placeholder value since the proxy injects the real key:

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

<Info>
  **What about `wssurl`?** The WebSocket connection (`wssurl`) is used for real-time audio transcription and is handled separately from REST calls. Contact **[support@omniloy.com](mailto:support@omniloy.com)** if you need to proxy WebSocket traffic as well — the Omniloy team can advise on the best approach for your infrastructure.
</Info>

### IP Allowlisting

As an additional layer of protection, Omniloy can restrict API key usage to specific IP addresses. This is especially useful with a backend proxy, where all traffic originates from your server's fixed IP. Contact **[support@omniloy.com](mailto:support@omniloy.com)** to configure IP allowlisting for your production keys.

## Common Troubleshooting

### Component doesn't load

1. Verify the import is in the main file
2. Confirm there are no errors in the browser console
3. Check network connectivity if using CDN

### CORS errors

* Ensure your application is served from HTTPS
* Verify that `baseurl` and `wssurl` URLs are correct

### Component not defined

```javascript theme={null}
// Wait for the component to be defined
customElements.whenDefined('sofia-sdk').then(() => {
  console.log('SofIA SDK is ready');
});
```

## Next Steps

Once installation is complete:

1. **[Required properties](/sofia/en/sdk/required-properties)**: Configure mandatory parameters
2. **[Optional properties](/sofia/en/sdk/optional-properties)**: Customize behavior
3. **[Clinical data schemas](/sofia/en/sdk/templates)**: Define data structure to generate