एम्बेडेड हस्ताक्षर

<bf-signing> आपके पेज के अंदर एक सैंडबॉक्स किए गए iframe में Bona Fide का हस्ताक्षर पेज रेंडर करता है, उसका आकार दस्तावेज़ के अनुसार तय करता है, और हस्ताक्षरकर्ता जो कुछ करता है उसे DOM इवेंट के रूप में बताता है। यह किसी फ़्रेमवर्क पर निर्भर नहीं है; हल्के React और Vue रैपर साथ में शामिल हैं।

1. delivery: "embedded" के साथ लिफ़ाफ़ा बनाएँ, ताकि प्राप्तकर्ताओं को ईमेल न भेजा जाए।

2. अपने सर्वर पर एक सेशन बनाएँ, जब हस्ताक्षरकर्ता पेज खोले, और अपनी साइट का ओरिजिन 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 वेबहुक (या 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() मेथड भी है, उदाहरण के लिए नया सेशन बनाने के बाद।

इवेंट

इवेंट बबल होते हैं, shadow root पार करते हैं, और पेलोड 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 फ़्रैगमेंट (#session=…) में जाता है, जो कभी किसी सर्वर या Referer हेडर तक नहीं पहुँचता। हस्ताक्षर पेज उसे पढ़ता है, URL और हिस्ट्री से हटाता है, और उसे मेमोरी में रखे जाने वाले एक्सेस टोकन से बदल लेता है। किसी कुकी का इस्तेमाल नहीं होता।
• iframe सैंडबॉक्स किया गया है (allow-scripts allow-same-origin allow-forms allow-popups allow-popups-to-escape-sandbox allow-downloads), referrerpolicy="strict-origin" के साथ।
• आपका पेज कोई संदेश तभी स्वीकार करता है जब वह एलिमेंट के अपने iframe से आए और base-url ओरिजिन से आए और नेमस्पेस वाले bona-fide.embed/1 संदेश के रूप में पार्स हो। बाकी सब कुछ अनदेखा किया जाता है।
• हस्ताक्षर पेज संदेश ठीक आपके ओरिजिन पर भेजता है (कभी * पर नहीं), और सिर्फ़ तब, जब वह ओरिजिन सेशन के allowedOrigins में हो। API भी उन ओरिजिन से आने वाले एम्बेडेड सेशन के कॉल अस्वीकार करता है, जिनकी अनुमति नहीं है।

इसके बजाय होस्टेड

अगर आप एम्बेड नहीं करना चाहते, तो "mode": "hosted" के साथ सेशन बनाएँ और उसके url पर रीडायरेक्ट करें; हस्ताक्षरकर्ता को वापस लाने के लिए returnUrl सेट करें। हस्ताक्षर सेशन देखें।

टिप्पणी

ऊपर दिया गया स्क्रिप्ट URL वही है, जिसे डैशबोर्ड का एम्बेड स्निपेट इस्तेमाल करता है। एलिमेंट और उसके रैपर एक ही पैकेज, @bona-fide/embed से आते हैं: रूट एंट्री <bf-signing> को रजिस्टर करती है, और @bona-fide/embed/react व @bona-fide/embed/vue, BonaFideSigning एक्सपोर्ट करते हैं।