@nexbasira/embed
En browser-widget, der gengiver NexBasiras feltside-oplevelse i din egen app. Indsæt en <div>, peg den mod en præget session-URL, lyt efter lifecycle-events. Ingen iframe-boilerplate, du selv skal skrive.
Installation
npm install @nexbasira/embedEller via <script>-tag til ikke-bundlet brug — se Script-tag nedenfor.
Grundlæggende brug
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 er den engangs-signerede URL, din backend får tilbage fra sessions.invite(). Indlejr aldrig en API-secret i URL'en — kun feltsession-tokenet, som er engangsbrug + IP/UA-pinnet.
Imperative metoder
Det returnerede widget-handle lader værtssiden styre feltside-oplevelsen programmatisk — typisk brugt af en værktøjslinje uden for iframen:
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 listenersHver metode poster en besked til iframens vindue via postMessage med den konfigurerede expectedOrigin; iframens interne dispatcher router dem til den relevante kontrol.
Lifecycle-events
Hvert callback, du sender til embed({ on... }), kaldes, når den matchende postMessage fra iframen ankommer. Origin-tjekket håndhæves — beskeder fra enhver anden origin ignoreres, så du kan stole på payloadens form.
| Callback | Udløses når | Payload |
|---|---|---|
onReady | iframe færdig med indlæsning + handshake | — |
onSessionJoined | Feltbruger tilsluttede rummet | sessionId |
onSessionComplete | Session lukket (operatør afsluttede, eller auto-udløbet) | sessionId |
onEvidenceAdded | Nyt snapshot / annotation / whiteboard / klip | { id, kind } |
onWhiteboardOpened | Whiteboard-panel åbnet | — |
onWhiteboardSaved | Whiteboard eksporteret til beviser | { id } |
onParticipantJoined / onParticipantLeft | Ændring af deltagerstatus | { id, role } |
onError | Enhver fejl på iframe-siden | { message, code } |
Script-tag
Til forbrugere uden en 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>
Bundtet vedhæfter NexBasira.embed på window til dette mønster.
Origin-pinning
Som standard udleder widgetten den forventede iframe-origin fra den URL, du gav (sessionUrl), og afviser beskeder fra enhver anden origin. Hvis du hoster feltside-oplevelsen på et eget domæne (Pro-niveau), skal du sende expectedOrigin eksplicit:
embed({
container: "#nb-host",
sessionUrl: "https://inspect.yourco.com/r/abc",
expectedOrigin: "https://inspect.yourco.com",
// ...
});
React-app?
Brug @nexbasira/react i stedet — samme widget under motorhjelmen, idiomatisk React-API (<NexBasiraSession>-komponent + useNexBasiraSession()-hook), fresh-closure-callbacks på tværs af re-renders.
Hvad er det næste
- @nexbasira/react — React-wrapper
- @nexbasira/node — server-side SDK til at præge
sessionUrl - Kildekode på GitHub