@nexbasira/embed
Un widget navigateur qui affiche l'expérience côté terrain de NexBasira dans votre propre application. Déposez un <div>, pointez-le vers une URL de session émise, écoutez les événements de cycle de vie. Aucun boilerplate d'iframe à écrire vous-même.
Installation
npm install @nexbasira/embedOu via une balise <script> pour un usage sans bundler — voir Balise script ci-dessous.
Utilisation de 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 est l'URL signée à usage unique que votre backend récupère depuis sessions.invite(). N'intégrez jamais un secret d'API dans l'URL — uniquement le token de session terrain, qui est à usage unique + lié à l'IP/UA.
Méthodes impératives
Le handle widget renvoyé permet à la page hôte de piloter l'expérience côté terrain par programmation — généralement utilisé par une barre d'outils en dehors de l'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 listenersChaque méthode poste un message vers la fenêtre de l'iframe via postMessage avec l'expectedOrigin configuré ; le dispatcher interne de l'iframe les route vers le contrôle concerné.
Événements de cycle de vie
Chaque callback que vous passez à embed({ on... }) est invoqué à l'arrivée du postMessage correspondant émis par l'iframe. La vérification d'origine est appliquée — les messages provenant de toute autre origine sont ignorés, vous pouvez donc faire confiance à la forme du payload.
| Callback | Se déclenche quand | Payload |
|---|---|---|
onReady | l'iframe a fini de charger + le handshake est terminé | — |
onSessionJoined | l'utilisateur terrain a rejoint la salle | sessionId |
onSessionComplete | session fermée (terminée par l'opérateur, ou expirée automatiquement) | sessionId |
onEvidenceAdded | nouvelle capture / annotation / tableau blanc / clip | { id, kind } |
onWhiteboardOpened | le panneau tableau blanc s'est ouvert | — |
onWhiteboardSaved | tableau blanc exporté vers les preuves | { id } |
onParticipantJoined / onParticipantLeft | changement d'état d'un participant | { id, role } |
onError | toute erreur côté iframe | { message, code } |
Balise script
Pour les consommateurs sans 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>
Le bundle attache NexBasira.embed sur window pour ce pattern.
Épinglage d'origine
Par défaut, le widget déduit l'origine attendue de l'iframe à partir de l'URL que vous avez passée (sessionUrl) et rejette les messages de toute autre origine. Si vous hébergez l'expérience côté terrain sur un domaine personnalisé (formule Pro), passez explicitement expectedOrigin :
embed({
container: "#nb-host",
sessionUrl: "https://inspect.yourco.com/r/abc",
expectedOrigin: "https://inspect.yourco.com",
// ...
});
Application React ?
Utilisez @nexbasira/react à la place — même widget en dessous, API React idiomatique (composant <NexBasiraSession> + hook useNexBasiraSession()), callbacks à closure fraîche à travers les re-rendus.
Et ensuite
- @nexbasira/react — wrapper React
- @nexbasira/node — SDK côté serveur pour émettre le
sessionUrl - Source sur GitHub