@ocularsolution/react

SDK oficial de Ocular Solution para integrar videollamadas en aplicaciones React (Vite, Next.js, CRA).

Provee un Provider + hooks que cargan el widget de Ocular en su página y lo controlan programáticamente. SSR-safe: no accede a window/document en el servidor.

Compatibilidad

| Componente | Versión | |---|---| | React / React DOM | ≥ 18 (validado con 19.1) | | Bundlers | Vite, Next.js, Webpack, CRA | | TypeScript (opcional) | ≥ 5.0 — tipos .d.ts incluidos |

1. Antes de empezar

Solicite a Ocular Solution sus datos de aprovisionamiento:

1. widgetCode — código de organización de su widget. Configúrelo por variable de entorno; no lo incruste en el repositorio.
2. widgetUrl — URL https del script del widget para su entorno.
3. Autorización de su dominio — el origin desde el que su web usará el widget debe estar dado de alta por Ocular Solution. Sin este registro el widget no se inicializa (verá OCULAR_E_WIDGET_TIMEOUT).

2. Instalación

pnpm add @ocularsolution/react
# o
npm install @ocularsolution/react

3. Uso

// src/App.jsx (ejemplo con Vite)
import { OcularProvider, useOcularCall } from '@ocularsolution/react';

function Controls() {
  const { state, show, hide, toggle } = useOcularCall();
  return (
    <>
      <button onClick={() => show(true)}>Abrir videollamada</button>
      <button onClick={() => hide()} disabled={state !== 'visible'}>Ocultar</button>
      <span>Estado: {state}</span>
    </>
  );
}

export default function App() {
  return (
    <OcularProvider
      widgetCode={import.meta.env.VITE_OCULAR_WIDGET_CODE}
      widgetUrl={import.meta.env.VITE_OCULAR_WIDGET_URL}
      appOrigin={import.meta.env.VITE_OCULAR_APP_ORIGIN}
    >
      <Controls />
    </OcularProvider>
  );
}

Next.js (App Router)

Los componentes del SDK son client components: use la directiva 'use client' en el archivo que monte <OcularProvider>. El SDK es SSR-safe (la carga del widget ocurre solo en el navegador).

4. API

<OcularProvider>

| Prop | Tipo | Req. | Descripción | |---|---|---|---| | widgetCode | string | Sí | Código de organización | | widgetUrl | string | Sí | URL https del script del widget | | appOrigin | string | No | Origin del iframe para validar mensajes | | widgetModule | string | No | Módulos del widget (default 'call') | | dataset | Record<string,string> | No | Atributos data-* extra del loader | | autoLoad | boolean | No | Carga el widget al montar | | nonce | string | No | Nonce CSP para los scripts inyectados | | scriptIntegrity | string | No | Hash SRI del script del widget |

useOcularCall()

const { state, load, show, hide, toggle, setLocale, setCustomer, showPopUp, align } = useOcularCall();
// state: 'idle' | 'loading' | 'ready' | 'visible' | 'hidden' | 'error'

useOcular()

Devuelve el cliente de bajo nivel (OcularClient) para suscribirse a eventos: state:changed, widget:ready, widget:message, error.

5. Content Security Policy

Si su sitio usa CSP estricta, permita el script del widget en script-src y pase nonce al Provider para el bridge inline. Consulte la guía de implementación completa con su contacto de Ocular Solution.

6. Errores comunes

| Código | Causa | Solución | |---|---|---| | OCULAR_E_WIDGET_TIMEOUT | Dominio no autorizado, widgetUrl/widgetCode incorrectos | Verifique el aprovisionamiento con Ocular Solution | | OCULAR_E_SCRIPT_LOAD | El navegador no pudo descargar el script (red/CSP) | Verifique la URL y su política CSP | | OCULAR_E_INVALID_CONFIG | Configuración incompleta | El mensaje indica el campo |

Protección de datos

setCustomer() permite asociar datos del usuario a la sesión. No envíe datos personales sin base legal y consentimiento. Las videollamadas pueden ser grabadas según la configuración de su organización: informe al usuario conforme a la normativa aplicable.

© Ocular Solution. Soporte: a través de su canal de cuenta. Incidentes de seguridad: [email protected]