Skip to main content
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

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.0/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.
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"
  wssurl="wss://YOUR_WSS_URL"
  userid="doctor-123"
  patientid="patient-456"
></sofia-sdk>
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 if you need to proxy WebSocket traffic as well — the Omniloy team can advise on the best approach for your infrastructure.

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

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