Penandatanganan tersemat

<bf-signing> merender halaman penandatanganan Bona Fide dalam iframe ber-sandbox di dalam halaman Anda, menyesuaikan ukurannya dengan dokumen, dan melaporkan tindakan penanda tangan sebagai event DOM. Komponen ini tidak bergantung pada framework; wrapper React dan Vue yang ringan sudah disertakan.

1. Buat amplop dengan delivery: "embedded", agar penerima tidak dikirimi email.

2. Buat sesi di server Anda saat penanda tangan membuka halaman, dengan origin situs Anda di allowedOrigins. Halaman tersemat menolak berkomunikasi dengan halaman induk mana pun yang tidak tercantum di sana.

   // 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 elemen dengan token tersebut.

   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. Konfirmasikan di server Anda. Perlakukan event browser sebagai sinyal UI dan andalkan webhook envelope.completed (atau GET /v1/envelopes/{id}) untuk hasilnya.

Atribut

Atribut (prop React / Vue)	Default	Catatan
session		Token bfs_…. Mengubahnya akan memuat ulang frame
base-url (baseUrl)	https://sign.bonafidesign.com/s/	Rute penandatanganan yang di-hosting pada deployment
theme	auto	auto, light, atau dark
locale		Diteruskan ke halaman penandatanganan
min-height, max-height (minHeight, maxHeight)	480, 90vh	Piksel atau vh. Frame membesar mengikuti dokumen di antara kedua nilai, lalu menggulir di dalamnya
timeout	30000	Milidetik untuk menunggu halaman sebelum error dengan kode load_timeout
frame-title	Document signing	Judul iframe yang dapat diakses

Elemen ini juga memiliki metode reload(), misalnya untuk dipakai setelah membuat sesi baru.

Event

Event melakukan bubbling, melintasi shadow root, dan membawa payload di event.detail. bf-event dipicu untuk semuanya.

Event	detail
ready	{ type: 'ready' }: halaman penandatanganan telah dimuat
field_completed	{ type, field }: sebuah kolom telah diisi
signed	{ type, recipient }: penerima ini telah mengirimkan
completed	{ type, envelope }: amplop telah selesai
declined	{ type, reason? }
session_expiring	{ type, expiresAt }: segera buat sesi baru
error	{ type, code, message }, termasuk load_timeout dan invalid_base_url

Prop React adalah onReady, onFieldCompleted, onSigned, onCompleted, onDeclined, onSessionExpiring, onError, dan onEvent; Vue memancarkan nama-nama event (@completed, @session_expiring, …) dan event.

Model keamanan

• Token dibawa di fragmen URL iframe (#session=…), yang tidak pernah sampai ke server atau header Referer. Halaman penandatanganan membacanya, menghapusnya dari URL dan riwayat, lalu menukarnya dengan token akses yang disimpan di memori. Tidak ada cookie yang digunakan.
• iframe berada dalam sandbox (allow-scripts allow-same-origin allow-forms allow-popups allow-popups-to-escape-sandbox allow-downloads) dengan referrerpolicy="strict-origin".
• Halaman Anda hanya menerima pesan yang berasal dari iframe milik elemen itu sendiri dan dari origin base-url dan dapat di-parse sebagai pesan bona-fide.embed/1 dengan namespace. Selain itu diabaikan.
• Halaman penandatanganan mengirim pesan ke origin Anda yang persis (tidak pernah *), dan hanya jika origin tersebut ada di allowedOrigins sesi. API juga menolak panggilan sesi tersemat dari origin yang tidak diizinkan.

Alternatif: di-hosting

Jika Anda lebih memilih tidak menyematkan, buat sesi dengan "mode": "hosted" dan alihkan ke url-nya; tetapkan returnUrl untuk membawa penanda tangan kembali. Lihat Sesi penandatanganan.

Catatan

URL skrip di atas adalah URL yang dipakai cuplikan kode sematan di dasbor. Elemen dan wrapper-nya berasal dari satu paket, @bona-fide/embed: entri root mendaftarkan <bf-signing>, sedangkan @bona-fide/embed/react dan @bona-fide/embed/vue mengekspor BonaFideSigning.