Innebygd signering

<bf-signing> rendrer Bona Fides signeringsside i en sandkasset iframe på siden din, tilpasser størrelsen til dokumentet og rapporterer det signataren gjør, som DOM-hendelser. Komponenten er uavhengig av rammeverk; tynne innpakninger for React og Vue følger med.

1. Opprett konvolutten med delivery: "embedded", så mottakerne ikke får e-post.

2. Opprett en økt på serveren din når signataren åpner siden, med opprinnelsen til nettstedet ditt i allowedOrigins. Den innebygde siden nekter å kommunisere med en overordnet side som ikke står oppført 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. Bekreft på serveren din. Behandle nettleserhendelsen som et signal til brukergrensesnittet, og stol på envelope.completed-webhooken (eller GET /v1/envelopes/{id}) for utfallet.

Attributter

Attributt (React-/Vue-prop)	Standard	Merknader
session		bfs_…-tokenet. Endres det, lastes rammen inn på nytt
base-url (baseUrl)	https://sign.bonafidesign.com/s/	Installasjonens hostede signeringsrute
theme	auto	auto, light eller dark
locale		Sendes videre til signeringssiden
min-height, max-height (minHeight, maxHeight)	480, 90vh	Piksler eller vh. Rammen vokser med dokumentet mellom de to verdiene og ruller deretter internt
timeout	30000	Millisekunder å vente på siden før en error med koden load_timeout
frame-title	Document signing	Iframens tilgjengelige tittel

Elementet har også en reload()-metode, for eksempel etter at du har opprettet en ny økt.

Hendelser

Hendelsene bobler, krysser shadow roots og har nyttelasten i event.detail. bf-event utløses for alle.

Hendelse	detail
ready	{ type: 'ready' }: signeringssiden er lastet inn
field_completed	{ type, field }: et felt ble fylt ut
signed	{ type, recipient }: denne mottakeren sendte inn
completed	{ type, envelope }: konvolutten er fullført
declined	{ type, reason? }
session_expiring	{ type, expiresAt }: opprett en ny økt snart
error	{ type, code, message }, inkludert load_timeout og invalid_base_url

React-propene er onReady, onFieldCompleted, onSigned, onCompleted, onDeclined, onSessionExpiring, onError og onEvent; Vue sender ut hendelsesnavnene (@completed, @session_expiring, …) og event.

Sikkerhetsmodell

• Tokenet sendes i URL-fragmentet til iframen (#session=…), som aldri når en server eller en Referer-header. Signeringssiden leser det, fjerner det fra URL-en og historikken og bytter det mot et tilgangstoken som holdes i minnet. Ingen cookies brukes.
• Iframen er sandkasset (allow-scripts allow-same-origin allow-forms allow-popups allow-popups-to-escape-sandbox allow-downloads) med referrerpolicy="strict-origin".
• Siden din godtar en melding bare når den kommer fra elementets egen iframe og fra opprinnelsen i base-url og kan tolkes som en bona-fide.embed/1-melding med navnerom. Alt annet ignoreres.
• Signeringssiden sender meldinger til nøyaktig din opprinnelse (aldri *), og bare hvis den opprinnelsen er i øktens allowedOrigins. API-et avviser også kall fra en innebygd økt som kommer fra opprinnelser som ikke er tillatt.

Hostet i stedet

Hvis du heller ikke vil bygge inn, oppretter du økten med "mode": "hosted" og videresender til url-en; angi returnUrl for å sende signataren tilbake. Se Signeringsøkter.

Merknad

Skript-URL-en ovenfor er den som innebyggingskoden i dashbordet bruker. Elementet og innpakningene kommer fra én pakke, @bona-fide/embed: rotinngangen registrerer <bf-signing>, og @bona-fide/embed/react og @bona-fide/embed/vue eksporterer BonaFideSigning.