Yerleşik imzalama

<bf-signing>, Bona Fide’ın imzalama sayfasını sayfanızın içinde korumalı alana alınmış (sandbox) bir iframe’de gösterir, iframe’i belgeye göre boyutlandırır ve imzacının yaptıklarını DOM olayları olarak bildirir. Herhangi bir framework’e bağlı değildir; ince React ve Vue sarmalayıcıları dahildir.

1. Zarfı delivery: "embedded" ile oluşturun; böylece alıcılara e-posta gönderilmez.

2. İmzacı sayfayı açtığında, sitenizin kaynağını allowedOrigins içine ekleyerek sunucunuzda bir oturum oluşturun. Yerleşik sayfa, orada listelenmeyen hiçbir üst sayfayla iletişim kurmaz.

   // 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. Belirteçle öğeyi oluşturun.

   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. Sunucunuzda doğrulayın. Tarayıcı olayını bir arayüz sinyali olarak değerlendirin ve sonuç için envelope.completed webhook’una (veya GET /v1/envelopes/{id} çağrısına) güvenin.

Öznitelikler

Öznitelik (React / Vue prop’u)	Varsayılan	Notlar
session		bfs_… belirteci. Değiştirilmesi çerçeveyi yeniden yükler
base-url (baseUrl)	https://sign.bonafidesign.com/s/	Dağıtımın barındırılan imzalama yolu
theme	auto	auto, light veya dark
locale		İmzalama sayfasına iletilir
min-height, max-height (minHeight, maxHeight)	480, 90vh	Piksel veya vh. Çerçeve bu iki değer arasında belgeyle birlikte büyür, sonra içeride kaydırılır
timeout	30000	load_timeout kodlu bir error oluşmadan önce sayfanın beklendiği milisaniye
frame-title	Document signing	iframe’in erişilebilir başlığı

Öğenin ayrıca, örneğin yeni bir oturum oluşturduktan sonra kullanmak için bir reload() yöntemi vardır.

Olaylar

Olaylar kabarcıklanır (bubble), shadow root sınırlarını aşar ve yükü event.detail içinde taşır. bf-event bunların tümü için tetiklenir.

Olay	detail
ready	{ type: 'ready' }: imzalama sayfası yüklendi
field_completed	{ type, field }: bir alan dolduruldu
signed	{ type, recipient }: bu alıcı gönderim yaptı
completed	{ type, envelope }: zarf tamamlandı
declined	{ type, reason? }
session_expiring	{ type, expiresAt }: yakında yeni bir oturum oluşturun
error	load_timeout ve invalid_base_url dahil { type, code, message }

React prop’ları onReady, onFieldCompleted, onSigned, onCompleted, onDeclined, onSessionExpiring, onError ve onEvent’tir; Vue olay adlarını (@completed, @session_expiring, …) ve event olayını yayar.

Güvenlik modeli

• Belirteç, iframe’in URL parçasında (#session=…) taşınır; bu parça hiçbir zaman bir sunucuya veya bir Referer başlığına ulaşmaz. İmzalama sayfası onu okur, URL’den ve geçmişten kaldırır ve bellekte tutulan bir erişim belirteciyle değiştirir. Çerez kullanılmaz.
• iframe korumalı alandadır (allow-scripts allow-same-origin allow-forms allow-popups allow-popups-to-escape-sandbox allow-downloads) ve referrerpolicy="strict-origin" kullanır.
• Sayfanız bir mesajı yalnızca öğenin kendi iframe’inden geldiğinde ve base-url kaynağından geldiğinde ve ad alanlı bir bona-fide.embed/1 mesajı olarak ayrıştırıldığında kabul eder. Diğer her şey yok sayılır.
• İmzalama sayfası mesajları tam olarak sizin kaynağınıza gönderir (asla * değil) ve bunu yalnızca o kaynak oturumun allowedOrigins listesindeyse yapar. API de izin verilmeyen kaynaklardan gelen yerleşik oturum çağrılarını reddeder.

Bunun yerine barındırılan

Yerleştirmek istemiyorsanız oturumu "mode": "hosted" ile oluşturun ve kullanıcıyı onun url adresine yönlendirin; imzacıyı geri getirmek için returnUrl ayarlayın. Bkz. İmzalama oturumları.

Not

Yukarıdaki betik URL’si, paneldeki yerleştirme kod parçacığının kullandığı URL’dir. Öğe ve sarmalayıcıları tek bir paketten gelir, @bona-fide/embed: kök giriş noktası <bf-signing> öğesini kaydeder, @bona-fide/embed/react ve @bona-fide/embed/vue ise BonaFideSigning dışa aktarır.