Inbäddad signering

<bf-signing> renderar Bona Fides signeringssida i en sandlådad iframe på din sida, anpassar storleken efter dokumentet och rapporterar vad undertecknaren gör som DOM-händelser. Den är oberoende av ramverk; tunna omslag för React och Vue ingår.

1. Skapa kuvertet med delivery: "embedded", så att mottagarna inte får några mejl.

2. Skapa en session på din server när undertecknaren öppnar sidan, med din webbplats ursprung i allowedOrigins. Den inbäddade sidan vägrar kommunicera med en överordnad sida som inte finns med där.

   // 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. Rendera elementet med 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. Bekräfta på din server. Behandla webbläsarhändelsen som en signal till gränssnittet och förlita dig på webhooken envelope.completed (eller GET /v1/envelopes/{id}) för utfallet.

Attribut

Attribut (React-/Vue-egenskap)	Standard	Kommentar
session		Token bfs_…. Om den ändras läses ramen in igen
base-url (baseUrl)	https://sign.bonafidesign.com/s/	Driftmiljöns hostade signeringsväg
theme	auto	auto, light eller dark
locale		Skickas vidare till signeringssidan
min-height, max-height (minHeight, maxHeight)	480, 90vh	Pixlar eller vh. Ramen växer med dokumentet mellan de två värdena och rullar sedan internt
timeout	30000	Millisekunder att vänta på sidan innan ett error med koden load_timeout
frame-title	Document signing	Iframens tillgängliga titel

Elementet har också en metod, reload(), till exempel för användning efter att du har skapat en ny session.

Händelser

Händelserna bubblar, passerar shadow roots och har nyttolasten i event.detail. bf-event utlöses för dem alla.

Händelse	detail
ready	{ type: 'ready' }: signeringssidan har lästs in
field_completed	{ type, field }: ett fält har fyllts i
signed	{ type, recipient }: den här mottagaren har skickat in
completed	{ type, envelope }: kuvertet är slutfört
declined	{ type, reason? }
session_expiring	{ type, expiresAt }: skapa snart en ny session
error	{ type, code, message }, inklusive load_timeout och invalid_base_url

Egenskaperna i React är onReady, onFieldCompleted, onSigned, onCompleted, onDeclined, onSessionExpiring, onError och onEvent; Vue sänder händelsenamnen (@completed, @session_expiring, …) och event.

Säkerhetsmodell

• Token färdas i iframens URL-fragment (#session=…), som aldrig når en server eller en Referer-rubrik. Signeringssidan läser den, tar bort den från URL:en och historiken och byter den mot en åtkomsttoken i minnet. Inga cookies används.
• Iframen är sandlådad (allow-scripts allow-same-origin allow-forms allow-popups allow-popups-to-escape-sandbox allow-downloads) med referrerpolicy="strict-origin".
• Din sida accepterar ett meddelande bara när det kommer från elementets egen iframe och från ursprunget i base-url och kan tolkas som ett meddelande i namnrymden bona-fide.embed/1. Allt annat ignoreras.
• Signeringssidan skickar meddelanden till ditt exakta ursprung (aldrig *), och bara om det ursprunget finns i sessionens allowedOrigins. API:et nekar också anrop från en inbäddad session som kommer från ursprung som inte är tillåtna.

Hostat i stället

Om du hellre inte vill bädda in skapar du sessionen med "mode": "hosted" och omdirigerar till dess url; ange returnUrl för att skicka tillbaka undertecknaren. Se Signeringssessioner.

Note

Skript-URL:en ovan är den som instrumentpanelens inbäddningskod använder. Elementet och dess omslag kommer från ett och samma paket, @bona-fide/embed: rotingången registrerar <bf-signing>, och @bona-fide/embed/react och @bona-fide/embed/vue exporterar BonaFideSigning.