@nexbasira/embed
Przeglądarkowy widget, który renderuje doświadczenie strony terenowej NexBasira wewnątrz Twojej aplikacji. Wstaw <div>, wskaż mu URL utworzonej sesji, nasłuchuj zdarzeń cyklu życia. Bez boilerplate iframe, który musiałbyś pisać samodzielnie.
Instalacja
npm install @nexbasira/embedLub przez tag <script> do użycia bez bundlera — zobacz Tag script poniżej.
Podstawowe użycie
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 to jednorazowy podpisany URL, który Twój backend otrzymuje z sessions.invite(). Nigdy nie osadzaj sekretu API w URL — tylko token sesji terenowej, który jest jednorazowy i powiązany z IP/UA.
Metody imperatywne
Zwrócony uchwyt widget pozwala stronie hosta programowo sterować doświadczeniem strony terenowej — zwykle używany przez pasek narzędzi poza 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 listenersKażda metoda wysyła komunikat do okna iframe przez postMessage ze skonfigurowanym expectedOrigin; wewnętrzny dyspozytor iframe kieruje je do odpowiedniej kontrolki.
Zdarzenia cyklu życia
Każdy callback, który przekażesz do embed({ on... }), jest wywoływany, gdy nadchodzi pasujący postMessage z iframe. Sprawdzenie origin jest wymuszane — komunikaty z dowolnego innego origin są ignorowane, więc możesz zaufać kształtowi payloadu.
| Callback | Wyzwala się, gdy | Payload |
|---|---|---|
onReady | iframe zakończył ładowanie + handshake | — |
onSessionJoined | Użytkownik terenowy dołączył do pokoju | sessionId |
onSessionComplete | Sesja zamknięta (operator zakończył lub auto-wygaśnięcie) | sessionId |
onEvidenceAdded | Nowy zrzut / adnotacja / tablica / klip | { id, kind } |
onWhiteboardOpened | Panel tablicy otwarty | — |
onWhiteboardSaved | Tablica wyeksportowana do Evidence | { id } |
onParticipantJoined / onParticipantLeft | Zmiana stanu uczestnika | { id, role } |
onError | Dowolny błąd po stronie iframe | { message, code } |
Tag script
Dla odbiorców bez bundlera:
<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>
Bundle dołącza NexBasira.embed do window dla tego wzorca.
Przypinanie origin
Domyślnie widget wyprowadza oczekiwany origin iframe z przekazanego URL (sessionUrl) i odrzuca komunikaty z dowolnego innego origin. Jeśli hostujesz doświadczenie strony terenowej na własnej domenie (tier Pro), przekaż expectedOrigin jawnie:
embed({
container: "#nb-host",
sessionUrl: "https://inspect.yourco.com/r/abc",
expectedOrigin: "https://inspect.yourco.com",
// ...
});
Aplikacja React?
Użyj @nexbasira/react zamiast tego — ten sam widget pod spodem, idiomatyczne API React (komponent <NexBasiraSession> + hook useNexBasiraSession()), świeże domknięcia callbacków przy re-renderach.
Co dalej
- @nexbasira/react — wrapper React
- @nexbasira/node — serwerowy SDK do tworzenia
sessionUrl - Źródło na GitHub