ایمبیڈڈ دستخط

<bf-signing> آپ کے صفحے کے اندر ایک sandboxed iframe میں Bona Fide کا دستخط کا صفحہ رینڈر کرتا ہے، اسے دستاویز کے مطابق سائز دیتا ہے، اور دستخط کنندہ جو کچھ کرتا ہے اسے DOM ایونٹس کے طور پر رپورٹ کرتا ہے۔ یہ کسی فریم ورک پر منحصر نہیں؛ ہلکے React اور Vue ریپرز شامل ہیں۔

1. delivery: "embedded" کے ساتھ لفافہ بنائیں، تاکہ وصول کنندگان کو ای میل نہ کی جائے۔

2. اپنے سرور پر سیشن بنائیں جب دستخط کنندہ صفحہ کھولے، اور اپنی سائٹ کا origin allowedOrigins میں دیں۔ ایمبیڈ کیا گیا صفحہ کسی ایسے پیرنٹ صفحے سے بات کرنے سے انکار کر دیتا ہے جو وہاں درج نہ ہو۔

   // 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. ٹوکن کے ساتھ عنصر رینڈر کریں۔

   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. اپنے سرور پر تصدیق کریں۔ براؤزر ایونٹ کو UI کا اشارہ سمجھیں اور نتیجے کے لیے envelope.completed webhook (یا GET /v1/envelopes/{id}) پر انحصار کریں۔

ایٹریبیوٹس

ایٹریبیوٹ (React / Vue prop)	ڈیفالٹ	نوٹس
session		bfs_… ٹوکن۔ اسے بدلنے سے فریم دوبارہ لوڈ ہوتا ہے
base-url (baseUrl)	https://sign.bonafidesign.com/s/	ڈیپلائمنٹ کا ہوسٹڈ دستخط والا روٹ
theme	auto	auto، light یا dark
locale		دستخط کے صفحے کو بھیجا جاتا ہے
min-height، max-height (minHeight، maxHeight)	480، 90vh	پکسلز یا vh۔ فریم ان دونوں کے درمیان دستاویز کے ساتھ بڑھتا ہے، پھر اندر اسکرول ہوتا ہے
timeout	30000	کوڈ load_timeout کے ساتھ error سے پہلے صفحے کا کتنے ملی سیکنڈ انتظار کیا جائے
frame-title	Document signing	iframe کا قابلِ رسائی عنوان

عنصر میں ایک reload() میتھڈ بھی ہے، مثلاً نیا سیشن بنانے کے بعد۔

ایونٹس

ایونٹس bubble ہوتے ہیں، shadow roots کو پار کرتے ہیں، اور پے لوڈ event.detail میں رکھتے ہیں۔ bf-event ان سب کے لیے فائر ہوتا ہے۔

ایونٹ	detail
ready	{ type: 'ready' }: دستخط کا صفحہ لوڈ ہو گیا
field_completed	{ type, field }: ایک فیلڈ بھری گئی
signed	{ type, recipient }: اس وصول کنندہ نے جمع کرا دیا
completed	{ type, envelope }: لفافہ مکمل ہو گیا
declined	{ type, reason? }
session_expiring	{ type, expiresAt }: جلد نیا سیشن بنائیں
error	{ type, code, message }، بشمول load_timeout اور invalid_base_url

React props یہ ہیں: onReady، onFieldCompleted، onSigned، onCompleted، onDeclined، onSessionExpiring، onError اور onEvent؛ Vue ایونٹس کے نام (@completed، @session_expiring، …) اور event emit کرتا ہے۔

سیکیورٹی ماڈل

• ٹوکن iframe کے URL fragment (#session=…) میں سفر کرتا ہے، جو کبھی کسی سرور یا Referer ہیڈر تک نہیں پہنچتا۔ دستخط کا صفحہ اسے پڑھتا ہے، URL اور ہسٹری سے ہٹا دیتا ہے، اور اسے میموری میں رکھے جانے والے ایکسیس ٹوکن سے بدل لیتا ہے۔ کوئی کوکیز استعمال نہیں ہوتیں۔
• iframe sandboxed ہے (allow-scripts allow-same-origin allow-forms allow-popups allow-popups-to-escape-sandbox allow-downloads) اور اس میں referrerpolicy="strict-origin" ہے۔
• آپ کا صفحہ کوئی پیغام صرف اسی وقت قبول کرتا ہے جب وہ عنصر کے اپنے iframe سے آئے اور base-url origin سے آئے اور namespaced bona-fide.embed/1 پیغام کے طور پر پارس ہو۔ باقی سب نظر انداز کر دیا جاتا ہے۔
• دستخط کا صفحہ پیغامات آپ کے عین origin کو بھیجتا ہے (کبھی * کو نہیں)، اور صرف اس صورت میں جب وہ origin سیشن کے allowedOrigins میں ہو۔ API بھی ایمبیڈڈ سیشن کی ان کالز کو مسترد کر دیتا ہے جو غیر مجاز origins سے آئیں۔

اس کے بجائے ہوسٹڈ

اگر آپ ایمبیڈ نہیں کرنا چاہتے تو سیشن "mode": "hosted" کے ساتھ بنائیں اور اس کے url پر ری ڈائریکٹ کریں؛ دستخط کنندہ کو واپس لانے کے لیے returnUrl مقرر کریں۔ دیکھیں دستخط کے سیشنز۔

نوٹ

اوپر دیا گیا اسکرپٹ URL وہی ہے جو ڈیش بورڈ کا ایمبیڈ اسنیپٹ استعمال کرتا ہے۔ عنصر اور اس کے ریپرز ایک ہی پیکج، @bona-fide/embed، سے آتے ہیں: روٹ انٹری <bf-signing> رجسٹر کرتی ہے، اور @bona-fide/embed/react اور @bona-fide/embed/vue، BonaFideSigning ایکسپورٹ کرتے ہیں۔