এমবেডেড স্বাক্ষর

<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 এক্সপোর্ট করে।