Indlejret underskrift

<bf-signing> renderer Bona Fides underskriftsside i en sandboxet iframe på din side, tilpasser størrelsen til dokumentet og rapporterer, hvad underskriveren gør, som DOM-hændelser. Den er uafhængig af frameworks; tynde wrappers til React og Vue følger med.

1. Opret kuverten med delivery: "embedded", så modtagerne ikke får e-mails.

2. Opret en session på din server, når underskriveren åbner siden, med dit websteds origin i allowedOrigins. Den indlejrede side nægter at kommunikere med en overordnet side, der ikke er angivet der.

   // 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 elementet med tokenet.

   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. Bekræft på din server. Behandl browserhændelsen som et signal til brugerfladen, og stol på envelope.completed-webhooket (eller GET /v1/envelopes/{id}) for resultatet.

Attributter

Attribut (React-/Vue-prop)	Standard	Bemærkninger
session		Tokenet bfs_…. Hvis det ændres, genindlæses rammen
base-url (baseUrl)	https://sign.bonafidesign.com/s/	Installationens hostede underskriftsrute
theme	auto	auto, light eller dark
locale		Sendes videre til underskriftssiden
min-height, max-height (minHeight, maxHeight)	480, 90vh	Pixels eller vh. Rammen vokser med dokumentet mellem de to værdier og ruller derefter internt
timeout	30000	Millisekunder, der ventes på siden før en error med koden load_timeout
frame-title	Document signing	Iframens tilgængelige titel

Elementet har også en metode, reload(), f.eks. til brug efter oprettelse af en ny session.

Hændelser

Hændelserne bobler, krydser shadow roots og har deres payload i event.detail. bf-event udløses for dem alle.

Hændelse	detail
ready	{ type: 'ready' }: underskriftssiden er indlæst
field_completed	{ type, field }: et felt er udfyldt
signed	{ type, recipient }: denne modtager har indsendt
completed	{ type, envelope }: kuverten er fuldført
declined	{ type, reason? }
session_expiring	{ type, expiresAt }: opret snart en ny session
error	{ type, code, message }, herunder load_timeout og invalid_base_url

React-props er onReady, onFieldCompleted, onSigned, onCompleted, onDeclined, onSessionExpiring, onError og onEvent; Vue udsender hændelsesnavnene (@completed, @session_expiring, …) og event.

Sikkerhedsmodel

• Tokenet sendes i iframens URL-fragment (#session=…), som aldrig når en server eller en Referer-header. Underskriftssiden læser det, fjerner det fra URL’en og historikken og bytter det til et adgangstoken i hukommelsen. Der bruges ingen cookies.
• Iframen er sandboxet (allow-scripts allow-same-origin allow-forms allow-popups allow-popups-to-escape-sandbox allow-downloads) med referrerpolicy="strict-origin".
• Din side accepterer kun en meddelelse, når den kommer fra elementets egen iframe og fra origin i base-url og kan fortolkes som en meddelelse i navnerummet bona-fide.embed/1. Alt andet ignoreres.
• Underskriftssiden sender meddelelser til dit præcise origin (aldrig *) og kun, hvis det origin er i sessionens allowedOrigins. API’et afviser også en indlejret sessions kald fra origins, der ikke er tilladt.

Hostet i stedet

Hvis du hellere vil undgå at indlejre, opretter du sessionen med "mode": "hosted" og omdirigerer til dens url; angiv returnUrl for at sende underskriveren tilbage. Se Signeringssessioner.

Note

Script-URL’en ovenfor er den, dashboardets indlejringskode bruger. Elementet og dets wrappers kommer fra én og samme pakke, @bona-fide/embed: rodindgangen registrerer <bf-signing>, og @bona-fide/embed/react og @bona-fide/embed/vue eksporterer BonaFideSigning.