Propiedades Opcionales

Configuraciones adicionales para personalizar SofIA SDK

Estas propiedades te permiten personalizar el comportamiento y apariencia del componente SofIA SDK para adaptarse a las necesidades específicas de tu implementación.

​

Propiedades Activas

​

Control de Interfaz

Propiedad	Tipo	Valor por Defecto	Descripción
isopen	boolean	true	Estado de visibilidad del componente, permite control bidireccional del estado abierto/cerrado. Cuando no se proporciona, el componente se inicia abierto por defecto

​

Callbacks

Propiedad	Tipo	Descripción
handleReport	function	Callback que recibe el reporte clínico estructurado generado por SofIA. Asígnalo como propiedad JS del elemento (el.handleReport = fn) — no se entrega vía atributo HTML ni evento DOM
setIsOpen	function	Función callback para manejar cambios de visibilidad solicitados por el componente
setGetLastReport	function	Un callback que recibe una función para recuperar el último reporte generado
onReportApply	function	Recibe el informe curado cuando el médico hace clic en Aplicar en el modal de vista previa de inserción. Cae en handleReport cuando el modal está desactivado
updateTemplate	function	Devuelve el contenido existente de los campos del EMR para que la generación lo integre. Ver Pre-cargar desde tu EMR
handleExtras	function	Recibe las acciones clínicas (peticiones, citas, pruebas…) extraídas de la transcripción, tal como las produjo tu esquema. Ver Acciones clínicas (Extras)
onEvent	function	Recibe los eventos de actividad del SDK (grabación, latido mientras fluye audio, interacción, escritura, informe, ciclo de vida). Payloads sin datos clínicos. Requiere eventSubscriptions. Ver Eventos de actividad

​

Firmas de Callbacks

handleReport

handleReport: (report: Record<string, unknown>) => void

Se invoca cuando el usuario activa la generación de reportes. El objeto report coincide con la estructura definida en tu JSON Schema template. Ejemplo de payload:

{
  "diagnosis": "Diabetes Mellitus Tipo 2",
  "treatment_plan": "Metformina 500mg dos veces al día"
}

setIsOpen

setIsOpen: (isOpen: boolean) => void

Se invoca cuando el SDK solicita un cambio de visibilidad (ej.: el usuario hace clic en el botón de cerrar).

setGetLastReport

setGetLastReport: (getter: () => Promise<Record<string, unknown> | undefined>) => void

Se invoca una vez durante la inicialización. Proporciona una función que puedes almacenar y llamar posteriormente para recuperar el último reporte generado para la sesión actual de paciente/usuario.

handleExtras

handleExtras: (extras: Record<string, unknown>[]) => void

Se invoca al pulsar un botón de categoría de extras (peticiones, citas, pruebas, derivaciones…). Recibe el array de items de esa categoría, tal como los produjo tu esquema templateExtras: el SDK no renombra ni transforma campos. Se empareja con la prop templateExtras. Ver Acciones clínicas (Extras).

onEvent

onEvent: (event: SdkEvent) => void
// SdkEvent = { name, family, level, ts, seq, sdkVersion, sessionId, payload }

Se invoca, de forma asíncrona, con cada evento al que te hayas suscrito mediante eventSubscriptions (p. ej. ['recording.*', 'activity.*', 'report.*']). Sin suscripción no se entrega nada. Los payloads solo contienen enumerados, booleanos y números —nunca texto clínico ni identificadores—. Pensado para detectar inactividad y para mantener viva la sesión de tu sistema mientras el médico graba (recording.heartbeat). Ver Eventos de actividad.

​

Datos Contextuales

Propiedad	Tipo	Valor por Defecto	Descripción
patientdata	string (JSON) | object	undefined	Información contextual del paciente (antecedentes, notas previas, referencias) para enriquecer el procesamiento clínico
templateExtras	string (JSON) | object	undefined	Esquema JSON Schema cuyas propiedades de primer nivel son las categorías de acción. Cada propiedad genera un botón que extrae esa categoría de la transcripción. Propiedad JS el.templateExtras; atributo del web component template-extras. Ver Acciones clínicas (Extras)

​

Curación de informes y pre-carga desde el EMR

Estas props impulsan dos funcionalidades de informes. Consulta sus guías dedicadas para el flujo completo.

Propiedad	Tipo	Descripción
onReportApply	function	Se dispara cuando el médico hace clic en Aplicar en el modal de vista previa de inserción. Recibe solo los campos que el médico dejó/editó
insertionPreviewClassNames	object	Overrides de class-name para estilar el modal de vista previa de inserción (que vive en el shadow DOM del SDK). Claves: backdrop, panel, header, body, footer, group, row, gapRow, applyButton, cancelButton
updateTemplate	function	Devuelve el contenido existente de los campos del EMR, por id de property de la plantilla, para que las notas generadas integren lo ya documentado. Ver Pre-cargar desde tu EMR

​

Eventos de actividad

Propiedad	Tipo	Descripción
onEvent	function	Handler del flujo de eventos. Solo propiedad JS (el.onEvent = fn)
eventSubscriptions	string[] (JSON)	Qué eventos recibe onEvent: nombres exactos ("recording.started"), comodines de familia ("recording.*") o "*". Sin ella no se entrega ningún evento. Propiedad JS el.eventSubscriptions; atributo del web component event-subscriptions

Ver la guía completa, con el catálogo de eventos y las recetas de inactividad, en Eventos de actividad.

​

Indicador de Consentimiento

El indicador de estado de consentimiento en el encabezado no es una propiedad del componente. Se habilita desde la configuración de tu cuenta/perfil de Omniloy (contacta a [e-mail] para activarlo). Cuando está habilitado, el indicador refleja el campo signedConsent que proporcionas dentro de patientdata (ver Datos del Paciente) y muestra tres estados: consentimiento firmado, sin firmar, y uso de IA rechazado.

Activar esta opción hace algo más que mostrar el indicador. Si el paciente consta con signedConsent.aiUse en "refused", no se pueden grabar ni generar informes en esa consulta (grabación, dictado, informe y acciones clínicas); el chat sigue disponible, con el motivo visible para el médico. Si tu HIS no informa aiUse, nada cambia respecto al comportamiento actual.

​

Localización

Propiedad	Tipo	Valor por Defecto	Descripción
language	string	"es"	Idioma de la interfaz. Valores soportados: "es" (Español), "en" (Inglés)

El idioma por defecto es "es" (Español). Si tu aplicación está dirigida a usuarios de habla inglesa, establece language="en" explícitamente.

​

Contexto de analítica

Propiedad	Tipo	Valor por Defecto	Descripción
usermedicalspecialty	string	undefined	La especialidad médica del profesional (p. ej. "cardiología"). Es puramente descriptiva: no cambia el comportamiento del SDK. Cuando se establece, se adjunta a cada evento de analítica (como user_medical_specialty) para poder segmentar el uso por especialidad. Se pasa tal cual, sin normalizar. Funciona tanto como prop de React como atributo/propiedad del web component

Cambio incompatible (v1.0.9). usermedicalspecialty sustituye al nombre en camelCase userMedicalSpecialty que se publicó en v1.0.8. El nombre antiguo ya no se lee: un host que lo siga pasando no recibe error, pero el valor se descarta en silencio y los eventos pierden la especialidad. Renómbralo al nombre en minúsculas usermedicalspecialty, en línea con el resto de props string (userid, patientid, templateid).

​

Depuración

Propiedad	Tipo	Valor por Defecto	Descripción
debug	boolean	false	Habilita logging detallado para propósitos de depuración

​

Personalización CSS

SofIA SDK se renderiza como un Web Component con Shadow DOM. Esto evita conflictos con los estilos de la aplicación host, pero también significa que el CSS global de la aplicación no afecta directamente a los elementos internos del SDK.

Si necesita ajustar estilos internos concretos, inyecte una etiqueta <style> dentro del shadowRoot del componente una vez que el Web Component esté definido y montado:

async function setupSofIACustomStyles(selector = '#sofia') {
  await customElements.whenDefined('sofia-sdk');
  const sofia = await waitForSofiaComponent(selector);

  const customStyles = `
    :host {
      --sofia-custom-spacing: 12px;
    }

    .omniscribe_chat-view-stick-to-bottom-content {
      font-size: 14px;
    }
  `;

  const existingStyle = sofia.shadowRoot.querySelector('style[data-sofia-custom]');
  const styleTag = existingStyle || document.createElement('style');

  styleTag.setAttribute('data-sofia-custom', 'true');
  styleTag.textContent = customStyles;

  if (!existingStyle) {
    sofia.shadowRoot.appendChild(styleTag);
  }
}

function waitForSofiaComponent(selector) {
  return new Promise((resolve, reject) => {
    let attempts = 0;
    const maxAttempts = 40;

    function check() {
      const sofia = document.querySelector(selector);

      if (sofia?.shadowRoot) {
        resolve(sofia);
        return;
      }

      attempts += 1;
      if (attempts >= maxAttempts) {
        reject(new Error('SofIA no está montada o no tiene shadowRoot disponible'));
        return;
      }

      setTimeout(check, 100);
    }

    check();
  });
}

setupSofIACustomStyles('#sofia').catch((error) => {
  console.warn('No se pudieron aplicar los estilos personalizados de SofIA:', error);
});

Use el selector que corresponda a su componente, por ejemplo #sofia o #sofia-component. En Angular, ejecute esta lógica en ngAfterViewInit. En AngularJS, puede llamarla después de configurar los atributos y callbacks del componente. Si el componente se crea de forma condicional, vuelva a ejecutar la función después de montarlo.

Los selectores de clases internas pueden cambiar entre versiones del SDK. El selector anterior corresponde a @omniloy/sofia-sdk 1.0.4. Mantenga estos estilos centralizados, pruebe la interfaz al actualizar @omniloy/sofia-sdk y prefiera propiedades documentadas del componente cuando estén disponibles.

​

Recuperación Manual de Reportes

Además de recibir el reporte automáticamente, puedes solicitarlo bajo demanda desde tu aplicación.

La propiedad set-get-last-report ejecuta un callback que te proporciona una función asíncrona. Debes almacenar esta referencia para usarla cuando necesites recuperar el último reporte generado.

let getLastReportFn = null;

// Callback asignado a: set-get-last-report
function registerGetter(fn) {
  getLastReportFn = fn;
}

// Ejemplo de uso en un botón externo
async function handleSaveClick() {
  if (getLastReportFn) {
    const report = await getLastReportFn();
    console.log("Reporte recuperado:", report);
  }
}

​

Ejemplos de Uso

​

Configuración básica con datos del paciente

Las propiedades de datos van como atributos del elemento; los callbacks se asignan como propiedades JS:

<sofia-sdk
  id="sofia"
  patientdata='{"age": 45, "history": "Hipertensión arterial"}'
  language="es"
  apikey="your-api-key"
  userid="user_12345"
  patientid="patient_67890"
  template='{"type": "object"}'
  templateid="soap-general-v1"
  isopen="true"
></sofia-sdk>

<script>
  customElements.whenDefined('sofia-sdk').then(() => {
    const sofia = document.getElementById('sofia');
    sofia.handleReport = (report) => console.log('Reporte:', report);
    sofia.setIsOpen = (isOpen) => console.log('Abierto:', isOpen);
  });
</script>

​

Modo solo chat (sin generación de reportes)

Para usar SofIA en modo solo chat, simplemente omita las propiedades template y templateid. El botón de generar no aparecerá.

<sofia-sdk
  apikey="your-api-key"
  userid="user_12345"
  patientid="patient_67890"
  language="es"
>
</sofia-sdk>

​

Configuración avanzada con callbacks

<sofia-sdk
  id="sofia"
  debug="true"
  apikey="your-api-key"
  userid="user_12345"
  patientid="patient_67890"
></sofia-sdk>

<script>
  customElements.whenDefined('sofia-sdk').then(() => {
    const sofia = document.getElementById('sofia');
    sofia.handleReport = (report) => console.log('Reporte:', report);
    sofia.setGetLastReport = (getReport) => { window.getLastSofiaReport = getReport; };
  });
</script>

Los callbacks son propiedades JS, no atributos HTML. Asigna cada callback directamente sobre el elemento en camelCase (ej.: element.handleReport = fn, element.setIsOpen = fn, element.setGetLastReport = fn, element.onReportApply = fn, element.updateTemplate = fn). No existe un atributo HTML handle-report ni un evento DOM — un atributo como handle-report="miFn" no se dispara. Las propiedades de datos simples (isopen, patientdata, debug) usan el mismo nombre en minúsculas como atributo HTML y como propiedad JS.

Propiedad	Tipo	Cómo asignarla
handleReport	callback	Solo propiedad JS: el.handleReport = fn
setIsOpen	callback	Solo propiedad JS: el.setIsOpen = fn
setGetLastReport	callback	Solo propiedad JS: el.setGetLastReport = fn
onReportApply	callback	Solo propiedad JS: el.onReportApply = fn
updateTemplate	callback	Solo propiedad JS: el.updateTemplate = fn
handleExtras	callback	Solo propiedad JS: el.handleExtras = fn
onEvent	callback	Solo propiedad JS: el.onEvent = fn
isopen	dato	Atributo HTML o propiedad JS
patientdata	dato	Atributo HTML o propiedad JS
templateExtras	dato	Propiedad JS el.templateExtras o atributo HTML template-extras
eventSubscriptions	dato	Propiedad JS el.eventSubscriptions o atributo HTML event-subscriptions
debug	dato	Atributo HTML o propiedad JS

​

Propiedades Deprecadas

Las siguientes propiedades están deprecadas y serán eliminadas en v2.0. No tienen efecto en la arquitectura actual basada en Chat.

Propiedad	Migración
toolsargs	Renombrada a template. Ver Propiedades Requeridas
isonlychat	Ya no es necesaria. El modo solo chat es automático cuando no se proporcionan template/templateid
disableactions	Para deshabilitar todas las acciones, no monte el componente <sofia-sdk>
disablegenerate	Para ocultar el botón de generar, no pase template/templateid
sofiatitle	Ya no es configurable. El título siempre es “SofIA”
isscreenloading	No disponible en la UI basada en Chat
transcriptorselectvalues	No se usa en la UI basada en Chat
render-report-content	No disponible en la UI basada en Chat
handleFill	No disponible en la UI basada en Chat

​

Notas Importantes

• patientdata: Debe contener solo información necesaria para el contexto clínico, siguiendo principios de minimización de datos.
• Estados: Los cambios en propiedades booleanas se reflejan inmediatamente en la interfaz.
• Localización: Cambiar el idioma afecta toda la interfaz del componente, incluyendo mensajes de error y etiquetas.
• Callbacks: Asigna los callbacks programáticamente como propiedades JS del elemento (ej.: element.handleReport = fn). No pueden conectarse mediante atributos HTML ni nombres de función globales.