Upotettu allekirjoitus

<bf-signing> renderöi Bona Fiden allekirjoitussivun hiekkalaatikoituun iframeen sivullasi, mitoittaa sen asiakirjan mukaan ja raportoi allekirjoittajan toimet DOM-tapahtumina. Se ei riipu mistään sovelluskehyksestä; ohuet React- ja Vue-kääreet sisältyvät mukaan.

1. Luo kirjekuori asetuksella delivery: "embedded", jotta vastaanottajille ei lähetetä sähköpostia.

2. Luo istunto palvelimellasi, kun allekirjoittaja avaa sivun, ja lisää sivustosi alkuperä kenttään allowedOrigins. Upotettu sivu kieltäytyy viestimästä minkään sellaisen yläsivun kanssa, jota siinä ei ole lueteltu.

   // 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öi elementti tunnuksella.

   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. Vahvista palvelimellasi. Käsittele selaimen tapahtumaa käyttöliittymän signaalina ja luota lopputuloksen osalta envelope.completed-webhookiin (tai kutsuun GET /v1/envelopes/{id}).

Attribuutit

Attribuutti (React- / Vue-prop)	Oletus	Huomautukset
session		bfs_…-tunnus. Sen muuttaminen lataa kehyksen uudelleen
base-url (baseUrl)	https://sign.bonafidesign.com/s/	Asennuksen isännöidyn allekirjoituksen reitti
theme	auto	auto, light tai dark
locale		Välitetään allekirjoitussivulle
min-height, max-height (minHeight, maxHeight)	480, 90vh	Pikseleinä tai vh. Kehys kasvaa asiakirjan mukana näiden välillä ja vierittyy sen jälkeen sisäisesti
timeout	30000	Millisekunnit, jotka sivua odotetaan ennen error-tapahtumaa koodilla load_timeout
frame-title	Document signing	Iframen saavutettava otsikko

Elementillä on myös reload()-metodi, esimerkiksi uuden istunnon luomisen jälkeen käytettäväksi.

Tapahtumat

Tapahtumat kuplivat, ylittävät shadow root -rajat ja kuljettavat hyötykuorman kentässä event.detail. bf-event laukeaa niistä jokaisesta.

Tapahtuma	detail
ready	{ type: 'ready' }: allekirjoitussivu latautui
field_completed	{ type, field }: kenttä täytettiin
signed	{ type, recipient }: tämä vastaanottaja lähetti allekirjoituksen
completed	{ type, envelope }: kirjekuori on valmis
declined	{ type, reason? }
session_expiring	{ type, expiresAt }: luo pian uusi istunto
error	{ type, code, message }, mukaan lukien load_timeout ja invalid_base_url

React-propit ovat onReady, onFieldCompleted, onSigned, onCompleted, onDeclined, onSessionExpiring, onError ja onEvent; Vue lähettää tapahtumanimet (@completed, @session_expiring, …) sekä event.

Tietoturvamalli

• Tunnus kulkee iframen URL-fragmentissa (#session=…), joka ei koskaan päädy palvelimelle eikä Referer-otsakkeeseen. Allekirjoitussivu lukee sen, poistaa sen URL-osoitteesta ja historiasta ja vaihtaa sen muistissa säilytettävään käyttötunnukseen. Evästeitä ei käytetä.
• Iframe on hiekkalaatikoitu (allow-scripts allow-same-origin allow-forms allow-popups allow-popups-to-escape-sandbox allow-downloads) asetuksella referrerpolicy="strict-origin".
• Sivusi hyväksyy viestin vain, kun se tulee elementin omasta iframesta ja base-url-alkuperästä ja jäsentyy nimiavaruuden mukaiseksi bona-fide.embed/1-viestiksi. Kaikki muu ohitetaan.
• Allekirjoitussivu lähettää viestit täsmälleen sinun alkuperääsi (ei koskaan *) ja vain, jos tämä alkuperä on istunnon allowedOrigins-luettelossa. API myös hylkää upotetun istunnon kutsut alkuperistä, joita ei ole sallittu.

Isännöity vaihtoehto

Jos et halua upottaa, luo istunto asetuksella "mode": "hosted" ja ohjaa sen url-osoitteeseen; aseta returnUrl, jotta allekirjoittaja palaa takaisin. Katso Allekirjoitusistunnot.

Huomio

Yllä oleva skriptin URL-osoite on sama, jota hallintapaneelin upotuskoodi käyttää. Elementti ja sen kääreet tulevat yhdestä paketista, @bona-fide/embed: juurimoduuli rekisteröi <bf-signing>-elementin, ja @bona-fide/embed/react sekä @bona-fide/embed/vue vievät BonaFideSigning-komponentin.