@nexbasira/embed
Um widget de navegador que renderiza a experiência do lado do terreno da NexBasira dentro da sua própria aplicação. Coloque um <div>, aponte-o para um URL de sessão emitido, escute os eventos de ciclo de vida. Sem boilerplate de iframe que tenha de escrever você mesmo.
Instalação
npm install @nexbasira/embedOu via tag <script> para uso sem bundler — ver Tag script abaixo.
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 é o URL assinado de uso único que o seu backend recebe de sessions.invite(). Nunca embeba um segredo de API no URL — apenas o token de sessão de terreno, que é de uso único + fixado por IP/UA.
Métodos imperativos
O handle widget devolvido permite à página anfitriã conduzir a experiência do lado do terreno programaticamente — tipicamente usado por uma toolbar fora do 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 listenersCada método envia uma mensagem à janela do iframe via postMessage com o expectedOrigin configurado; o dispatcher interno do iframe encaminha-as para o controlo relevante.
Eventos de ciclo de vida
Cada callback que passa a embed({ on... }) é invocado quando chega o postMessage correspondente do iframe. A verificação de origem é imposta — mensagens de qualquer outra origem são ignoradas, portanto pode confiar na forma do payload.
| Callback | Dispara quando | Payload |
|---|---|---|
onReady | iframe terminou o carregamento + handshake | — |
onSessionJoined | Utilizador no terreno entrou na sala | sessionId |
onSessionComplete | Sessão fechada (operador terminou, ou expirou automaticamente) | sessionId |
onEvidenceAdded | Nova captura / anotação / quadro branco / clip | { id, kind } |
onWhiteboardOpened | Painel de quadro branco aberto | — |
onWhiteboardSaved | Quadro branco exportado para Provas | { id } |
onParticipantJoined / onParticipantLeft | Alteração de estado de participante | { id, role } |
onError | Qualquer erro do lado do iframe | { message, code } |
Tag script
Para consumidores sem 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>
O bundle anexa NexBasira.embed ao window para este padrão.
Fixação de origem
Por defeito, o widget deriva a origem esperada do iframe a partir do URL que passou (sessionUrl) e rejeita mensagens de qualquer outra origem. Se estiver a alojar a experiência do lado do terreno num domínio personalizado (escalão Pro), passe expectedOrigin explicitamente:
embed({
container: "#nb-host",
sessionUrl: "https://inspect.yourco.com/r/abc",
expectedOrigin: "https://inspect.yourco.com",
// ...
});
Aplicação React?
Use @nexbasira/react em vez disso — mesmo widget por baixo, API React idiomática (componente <NexBasiraSession> + hook useNexBasiraSession()), callbacks de closure atualizadas entre re-renders.
O que vem a seguir
- @nexbasira/react — wrapper React
- @nexbasira/node — SDK do lado do servidor para emitir o
sessionUrl - Código-fonte no GitHub