@nexbasira/embed
Un widget navigateur qui affiche l'expérience côté terrain de NexBasira dans votre propre application. Insérez un <div>, pointez-le vers une URL de session générée, écoutez les événements du 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 jeton de session terrain, à usage unique et épinglé à l'IP / au UA.
Méthodes impératives
Le handle widget retourné permet à la page hôte de piloter l'expérience côté terrain par programmation — généralement utilisé par une barre d'outils hors 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 envoie un message à la fenêtre de l'iframe via postMessage avec l'expectedOrigin configuré ; le répartiteur interne de l'iframe les route vers le contrôle concerné.
Événements du cycle de vie
Chaque callback que vous passez à embed({ on... }) est invoqué lorsque le postMessage correspondant de l'iframe arrive. Le contrôle de l'origine est appliqué — les messages provenant de toute autre origine sont ignorés, vous pouvez donc vous fier à la forme de la charge utile.
| Callback | Déclenché quand | Charge utile |
|---|---|---|
onReady | l'iframe a fini de charger + établi la poignée de main | — |
onSessionJoined | L'utilisateur terrain a rejoint la salle | sessionId |
onSessionComplete | Session close (fin par l'opérateur ou expiration automatique) | sessionId |
onEvidenceAdded | Nouvelle capture / annotation / tableau blanc / clip | { id, kind } |
onWhiteboardOpened | Panneau du tableau blanc 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 schéma.
Épinglage de l'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é (offre 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 au fil des re-rendus.
Et ensuite
- @nexbasira/react — wrapper React
- @nexbasira/node — SDK server-side pentru a emite
sessionUrl - Sursă pe GitHub