@ocularsolution/astro

SDK oficial de Ocular Solution para integrar videollamadas en sitios Astro mediante islands de React.

Incluye una integración de Astro que expone la configuración del widget y re-exporta los componentes React del SDK para usarlos con client:load / client:idle.

Compatibilidad

| Componente | Versión | |---|---| | Astro | ≥ 4.0 | | @astrojs/react | requerido | | 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 sitio 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/astro @astrojs/react react react-dom
# o
npm install @ocularsolution/astro @astrojs/react react react-dom

3. Uso

Registrar la integración

// astro.config.mjs
import { defineConfig } from 'astro/config';
import react from '@astrojs/react';
import ocular from '@ocularsolution/astro';

export default defineConfig({
  integrations: [
    react(),
    ocular({
      widgetCode: process.env.PUBLIC_OCULAR_WIDGET_CODE,
      widgetUrl: process.env.PUBLIC_OCULAR_WIDGET_URL,
      appOrigin: process.env.PUBLIC_OCULAR_APP_ORIGIN,
    }),
  ],
});

Usar los componentes como islands

---
// src/pages/videollamada.astro
import { OcularProvider, OcularCall } from '@ocularsolution/astro';
---

<OcularProvider
  widgetCode={import.meta.env.PUBLIC_OCULAR_WIDGET_CODE}
  widgetUrl={import.meta.env.PUBLIC_OCULAR_WIDGET_URL}
  appOrigin={import.meta.env.PUBLIC_OCULAR_APP_ORIGIN}
  client:load
>
  <OcularCall client:load />
</OcularProvider>

Los componentes con estado de Ocular deben usar client:load o client:idle — no se renderizan en el servidor.

4. API

La integración re-exporta la API completa de @ocularsolution/react: OcularProvider, OcularCall, useOcular(), useOcularCall() y DomTransport. Consulte el README de @ocularsolution/react para la referencia de props, estados y eventos.

5. 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 | | Hydration mismatch | Componentes de Ocular renderizados en servidor | Use client:load / client:idle |

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]