Osadzone podpisywanie

<bf-signing> renderuje stronę podpisywania Bona Fide w odizolowanej ramce iframe (sandbox) na Twojej stronie, dopasowuje jej rozmiar do dokumentu i zgłasza działania osoby podpisującej jako zdarzenia DOM. Nie zależy od żadnego frameworka; dołączone są lekkie nakładki dla React i Vue.

1. Utwórz kopertę z delivery: "embedded", aby odbiorcy nie otrzymywali wiadomości e-mail.

2. Utwórz sesję na swoim serwerze, gdy osoba podpisująca otwiera stronę, podając źródło (origin) swojej witryny w allowedOrigins. Osadzona strona odmawia komunikacji z każdą stroną nadrzędną, której tam nie wymieniono.

   // 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. Wyrenderuj element z tokenem.

   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. Potwierdź wynik na serwerze. Traktuj zdarzenie z przeglądarki jako sygnał dla interfejsu, a w kwestii wyniku polegaj na webhooku envelope.completed (lub na GET /v1/envelopes/{id}).

Atrybuty

Atrybut (właściwość React / Vue)	Domyślnie	Uwagi
session		Token bfs_…. Jego zmiana przeładowuje ramkę
base-url (baseUrl)	https://sign.bonafidesign.com/s/	Hostowana ścieżka podpisywania danego wdrożenia
theme	auto	auto, light lub dark
locale		Przekazywany do strony podpisywania
min-height, max-height (minHeight, maxHeight)	480, 90vh	Piksele lub vh. Ramka rośnie wraz z dokumentem w tych granicach, a potem przewija się wewnątrz
timeout	30000	Liczba milisekund oczekiwania na stronę, po której zgłaszany jest error z kodem load_timeout
frame-title	Document signing	Dostępny tytuł ramki iframe

Element ma też metodę reload(), przydatną na przykład po utworzeniu nowej sesji.

Zdarzenia

Zdarzenia propagują się w górę (bubble), przekraczają granice shadow root i przenoszą dane w event.detail. bf-event jest wywoływane dla każdego z nich.

Zdarzenie	detail
ready	{ type: 'ready' }: strona podpisywania została wczytana
field_completed	{ type, field }: pole zostało wypełnione
signed	{ type, recipient }: ten odbiorca przesłał podpis
completed	{ type, envelope }: koperta jest zakończona
declined	{ type, reason? }
session_expiring	{ type, expiresAt }: wkrótce utwórz nową sesję
error	{ type, code, message }, w tym load_timeout i invalid_base_url

Właściwości React to onReady, onFieldCompleted, onSigned, onCompleted, onDeclined, onSessionExpiring, onError i onEvent; Vue emituje nazwy zdarzeń (@completed, @session_expiring, …) oraz event.

Model bezpieczeństwa

• Token jest przekazywany we fragmencie adresu URL ramki iframe (#session=…), który nigdy nie trafia na serwer ani do nagłówka Referer. Strona podpisywania odczytuje go, usuwa z adresu URL i historii, a następnie wymienia na token dostępu przechowywany w pamięci. Pliki cookie nie są używane.
• Ramka iframe działa w piaskownicy (allow-scripts allow-same-origin allow-forms allow-popups allow-popups-to-escape-sandbox allow-downloads) z referrerpolicy="strict-origin".
• Twoja strona przyjmuje wiadomość tylko wtedy, gdy pochodzi ona z ramki iframe danego elementu i ze źródła base-url i daje się sparsować jako wiadomość w przestrzeni nazw bona-fide.embed/1. Wszystko inne jest ignorowane.
• Strona podpisywania wysyła wiadomości dokładnie do Twojego źródła (nigdy *) i tylko wtedy, gdy to źródło znajduje się w allowedOrigins sesji. API również odrzuca wywołania sesji osadzonej ze źródeł, które nie są dozwolone.

Strona hostowana zamiast osadzania

Jeśli wolisz nie osadzać, utwórz sesję z "mode": "hosted" i przekieruj pod jej url; ustaw returnUrl, aby osoba podpisująca wróciła do Ciebie. Zobacz Sesje podpisywania.

Notatka

Powyższy adres URL skryptu to ten sam, którego używa fragment kodu do osadzania w panelu. Element i jego nakładki pochodzą z jednego pakietu, @bona-fide/embed: główny punkt wejścia rejestruje <bf-signing>, a @bona-fide/embed/react i @bona-fide/embed/vue eksportują BonaFideSigning.