@nexbasira/embed
Un widget browser che rende l'esperienza lato campo NexBasira dentro la tua app. Inserisci un <div>, puntalo a una session URL generata, ascolta gli eventi del ciclo di vita. Nessun boilerplate iframe da scrivere a mano.
Installazione
npm install @nexbasira/embedOppure tramite tag <script> per l'uso non bundled — vedi Tag script qui sotto.
Uso di base
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 è la URL firmata monouso che il tuo backend riceve da sessions.invite(). Non incorporare mai un secret API nella URL — solo il token di sessione campo, che è monouso + vincolato a IP/UA.
Metodi imperativi
L'handle widget restituito permette alla pagina host di guidare l'esperienza lato campo in modo programmatico — tipicamente usato da una toolbar fuori dall'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 listenersOgni metodo invia un messaggio alla window dell'iframe tramite postMessage con l'expectedOrigin configurato; il dispatcher interno dell'iframe li instrada al controllo pertinente.
Eventi del ciclo di vita
Ogni callback che passi a embed({ on... }) viene invocata quando arriva il postMessage corrispondente dall'iframe. Il controllo dell'origin è applicato — i messaggi da qualsiasi altra origin vengono ignorati, così puoi fidarti della forma del payload.
| Callback | Si attiva quando | Payload |
|---|---|---|
onReady | iframe ha completato il caricamento + handshake | — |
onSessionJoined | L'utente sul campo è entrato nella room | sessionId |
onSessionComplete | Sessione chiusa (operatore ha terminato, o scaduta automaticamente) | sessionId |
onEvidenceAdded | Nuova snapshot / annotazione / lavagna / clip | { id, kind } |
onWhiteboardOpened | Pannello lavagna aperto | — |
onWhiteboardSaved | Lavagna esportata in Evidence | { id } |
onParticipantJoined / onParticipantLeft | Cambio di stato del partecipante | { id, role } |
onError | Qualsiasi errore lato iframe | { message, code } |
Tag script
Per i consumer senza bundler:
<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>
Il bundle collega NexBasira.embed su window per questo pattern.
Pinning dell'origin
Per impostazione predefinita il widget deriva l'origin atteso dell'iframe dalla URL che hai passato (sessionUrl) e rifiuta i messaggi da qualsiasi altra origin. Se ospiti l'esperienza lato campo su un dominio personalizzato (piano Pro), passa expectedOrigin esplicitamente:
embed({
container: "#nb-host",
sessionUrl: "https://inspect.yourco.com/r/abc",
expectedOrigin: "https://inspect.yourco.com",
// ...
});
App React?
Usa @nexbasira/react invece — stesso widget sotto, API React idiomatica (componente <NexBasiraSession> + hook useNexBasiraSession()), callback con closure fresca tra i re-render.
Prossimi passi
- @nexbasira/react — wrapper React
- @nexbasira/node — SDK lato server per generare la
sessionUrl - Sorgente su GitHub