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

npm install @omniloy/sofia-sdk

Installation with Yarn

yarn add @omniloy/sofia-sdk

Import in your project

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

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

For specific version

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

Option 3: Manual build

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

<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:

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

Should show the component definition instead of undefined.

In your HTML

Try adding the basic component:

<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)

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.

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

Component template:

<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:

plugins/sofia-sdk.client.ts

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

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.

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.

// 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:

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

Note on endpoint auto-resolution and the proxy. For newer keys the SDK would normally auto-resolve the endpoint. To route REST traffic through your proxy instead, pass an explicit baseurl pointing at the proxy (as shown above) — an explicit baseurl always overrides automatic resolution.

wssurl is deprecated and ignored since v1.0.7. The transcription WebSocket URL is now provided automatically by the settings API — there is no wssurl to proxy. Contact [e-mail] if your infrastructure needs to route the transcriber WebSocket traffic; the Omniloy team can advise on the best approach.

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 [e-mail] 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 the baseurl URL is correct (or that your key resolves to the expected endpoint)

Component not defined

// 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: Configure mandatory parameters
2. Optional properties: Customize behavior
3. Clinical data schemas: Define data structure to generate