EN VIVO · CON AUDITORÍA · UE
SISTEMA · 99,99% UPTIME
v 1.0 ↗ HECHO EN UE

widget @nexbasira/embed

Widget en iframe de navegador para embeber la experiencia del lado de campo de NexBasira dentro de su propia app.

@nexbasira/embed

Un widget de navegador que renderiza la experiencia del lado de campo de NexBasira dentro de su propia app. Coloque un <div>, apúntelo a una URL de sesión generada, escuche los eventos del ciclo de vida. Sin código repetitivo de iframe que tenga que escribir usted mismo.

Instalación

npm install @nexbasira/embed

O mediante la etiqueta <script> para uso sin empaquetador: consulte Etiqueta script más abajo.

Uso básico

import { embed } from "@nexbasira/embed";

const widget = embed({
  container: "#nb-host",          // selector or HTMLElement
  sessionUrl: invite.url,          // minted by your backend via the Node/Python SDK
  width: "100%",
  height: "720px",
  onReady: () => console.log("iframe loaded"),
  onSessionJoined: (id) => console.log("field user joined", id),
  onEvidenceAdded: (ev) => console.log("evidence", ev),
  onSessionComplete: (id) => router.push(`/inspections/${id}`),
});

sessionUrl es la URL firmada de un solo uso que su backend recibe de sessions.invite(). Nunca incruste un secreto de API en la URL: solo el token de sesión de campo, que es de un solo uso + fijado a IP/UA.

Métodos imperativos

El handle widget devuelto permite a la página anfitriona controlar la experiencia del lado de campo mediante programación: normalmente lo usa una barra de herramientas fuera del iframe:

widget.requestSnapshot();    // operator-side trigger; field captures a frame
widget.openWhiteboard();
widget.closeWhiteboard();
widget.switchCamera();        // toggle front / rear on supported devices
widget.mute();
widget.unmute();
widget.endSession();
widget.destroy();             // tear down the iframe + remove listeners

Cada método publica un mensaje a la ventana del iframe vía postMessage con el expectedOrigin configurado; el despachador interno del iframe los enruta al control correspondiente.

Eventos del ciclo de vida

Cada callback que pase a embed({ on... }) se invoca cuando llega el postMessage correspondiente del iframe. La comprobación de origen se aplica: los mensajes de cualquier otro origen se ignoran, por lo que puede confiar en la forma del payload.

CallbackSe dispara cuandoPayload
onReadyel iframe terminó de cargar + handshake—
onSessionJoinedEl usuario de campo se unió a la salasessionId
onSessionCompleteSesión cerrada (el operador la finalizó, o expiró automáticamente)sessionId
onEvidenceAddedNueva captura / anotación / pizarra / clip{ id, kind }
onWhiteboardOpenedPanel de pizarra abierto—
onWhiteboardSavedPizarra exportada a Pruebas{ id }
onParticipantJoined / onParticipantLeftCambio de estado del participante{ id, role }
onErrorCualquier error del lado del iframe{ message, code }

Etiqueta script

Para consumidores sin empaquetador:

<script src="https://unpkg.com/@nexbasira/embed@latest/dist/index.umd.js"></script>
<div id="nb-host" style="width: 100%; height: 720px"></div>
<script>
  const widget = NexBasira.embed({
    container: "#nb-host",
    sessionUrl: "<minted-by-your-backend>",
    onSessionComplete: (id) => alert("done: " + id),
  });
</script>

El bundle adjunta NexBasira.embed en window para este patrón.

Fijación de origen

Por defecto, el widget deriva el origen esperado del iframe de la URL que pasó (sessionUrl) y rechaza los mensajes de cualquier otro origen. Si aloja la experiencia del lado de campo en un dominio personalizado (nivel Pro), pase expectedOrigin explícitamente:

embed({
  container: "#nb-host",
  sessionUrl: "https://inspect.yourco.com/r/abc",
  expectedOrigin: "https://inspect.yourco.com",
  // ...
});

¿App de React?

Use @nexbasira/react en su lugar: el mismo widget por debajo, API de React idiomática (componente <NexBasiraSession> + hook useNexBasiraSession()), callbacks de closure fresco a través de los re-renderizados.

Qué sigue