Ingesloten ondertekening

<bf-signing> rendert de ondertekeningspagina van Bona Fide in een gesandboxt iframe binnen uw pagina, past de grootte aan het document aan en meldt wat de ondertekenaar doet als DOM-events. De component is frameworkonafhankelijk; lichte wrappers voor React en Vue zijn inbegrepen.

1. Maak de envelop aan met delivery: "embedded", zodat ontvangers geen e-mail krijgen.

2. Maak een sessie aan op uw server wanneer de ondertekenaar de pagina opent, met de origin van uw site in allowedOrigins. De ingesloten pagina weigert te communiceren met een bovenliggende pagina die daar niet in staat.

   // Your backend (never expose the API key to the browser)
   const res = await fetch(`https://api.bonafidesign.com/v1/envelopes/${envelopeId}/sessions`, {
     method: 'POST',
     headers: { Authorization: `Bearer ${process.env.BONA_FIDE_API_KEY}`, 'Content-Type': 'application/json' },
     body: JSON.stringify({ recipient: recipientId, mode: 'embedded', allowedOrigins: ['https://app.example.com'] }),
   });
   const { token } = await res.json(); // 'bfs_…', single-use, 10 minutes by default

3. Render het element met het token.

   HTML

   <script type="module" src="https://js.bonafidesign.com/v1"></script>
   
   <bf-signing session="bfs_…" theme="auto" min-height="480" max-height="90vh"></bf-signing>
   
   <script>
     const el = document.querySelector('bf-signing');
     el.addEventListener('completed', (e) => {
       // e.detail = { type: 'completed', envelope: 'env_…' }
       window.location.href = '/onboarding/next';
     });
     el.addEventListener('session_expiring', () => refreshSession());
     el.addEventListener('error', (e) => console.error(e.detail.code, e.detail.message));
   </script>

   React

   import { BonaFideSigning } from '@bona-fide/embed/react';
   
   export function SignContract({ token }: { token: string }) {
     return (
       <BonaFideSigning
         session={token}
         theme="auto"
         minHeight={480}
         maxHeight="90vh"
         onCompleted={(e) => console.log('envelope completed', e.envelope)}
         onDeclined={(e) => console.log('declined', e.reason)}
         onSessionExpiring={() => refreshSession()}
         onError={(e) => console.error(e.code, e.message)}
       />
     );
   }

   Vue

   <script setup lang="ts">
   import { BonaFideSigning } from '@bona-fide/embed/vue';
   defineProps<{ token: string }>();
   const done = (e: { envelope: string }) => console.log('envelope completed', e.envelope);
   </script>
   
   <template>
     <BonaFideSigning :session="token" theme="auto" :min-height="480" max-height="90vh" @completed="done" />
   </template>

4. Bevestig op uw server. Behandel het browserevent als een signaal voor de UI en vertrouw voor de uitkomst op de envelope.completed-webhook (of GET /v1/envelopes/{id}).

Attributen

Attribuut (React- / Vue-prop)	Standaard	Opmerkingen
session		Het bfs_…-token. Als het wijzigt, wordt het frame opnieuw geladen
base-url (baseUrl)	https://sign.bonafidesign.com/s/	De gehoste ondertekeningsroute van de deployment
theme	auto	auto, light of dark
locale		Doorgegeven aan de ondertekeningspagina
min-height, max-height (minHeight, maxHeight)	480, 90vh	Pixels of vh. Het frame groeit tussen die twee waarden mee met het document en scrolt daarna intern
timeout	30000	Milliseconden wachten op de pagina voordat er een error met code load_timeout volgt
frame-title	Document signing	De toegankelijke titel van het iframe

Het element heeft ook een methode reload(), bijvoorbeeld voor gebruik nadat u een nieuwe sessie hebt aangemaakt.

Events

Events bubbelen, gaan door shadow roots heen en dragen de payload in event.detail. bf-event wordt voor al deze events afgevuurd.

Event	detail
ready	{ type: 'ready' }: de ondertekeningspagina is geladen
field_completed	{ type, field }: er is een veld ingevuld
signed	{ type, recipient }: deze ontvanger heeft ingediend
completed	{ type, envelope }: de envelop is voltooid
declined	{ type, reason? }
session_expiring	{ type, expiresAt }: maak binnenkort een nieuwe sessie aan
error	{ type, code, message }, inclusief load_timeout en invalid_base_url

De React-props zijn onReady, onFieldCompleted, onSigned, onCompleted, onDeclined, onSessionExpiring, onError en onEvent; Vue emit de eventnamen (@completed, @session_expiring, …) en event.

Beveiligingsmodel

• Het token reist in het URL-fragment van het iframe (#session=…), dat nooit een server of een Referer-header bereikt. De ondertekeningspagina leest het, verwijdert het uit de URL en de geschiedenis en wisselt het in voor een toegangstoken dat in het geheugen blijft. Er worden geen cookies gebruikt.
• Het iframe is gesandboxt (allow-scripts allow-same-origin allow-forms allow-popups allow-popups-to-escape-sandbox allow-downloads) met referrerpolicy="strict-origin".
• Uw pagina accepteert een bericht alleen als het afkomstig is van het eigen iframe van het element en van de origin van base-url en te parsen is als een bona-fide.embed/1-bericht met namespace. Al het andere wordt genegeerd.
• De ondertekeningspagina post berichten naar uw exacte origin (nooit *), en alleen als die origin in de allowedOrigins van de sessie staat. Ook de API weigert calls van een ingesloten sessie vanaf origins die niet zijn toegestaan.

Liever gehost

Wilt u niet insluiten, maak de sessie dan aan met "mode": "hosted" en stuur door naar de url ervan; stel returnUrl in om de ondertekenaar terug te brengen. Zie Ondertekeningssessies.

Opmerking

De script-URL hierboven is de URL die het embedfragment in het dashboard gebruikt. Het element en de wrappers komen uit één package, @bona-fide/embed: het hoofdentrypoint registreert <bf-signing>, en @bona-fide/embed/react en @bona-fide/embed/vue exporteren BonaFideSigning.