التوقيع المضمَّن

يعرض <bf-signing> صفحة التوقيع الخاصة بـ Bona Fide داخل iframe معزول (sandboxed) في صفحتك، ويضبط حجمه وفق المستند، ويبلّغ عمّا يفعله الموقِّع على شكل أحداث 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. أكّد النتيجة على خادمك. تعامل مع حدث المتصفح كإشارة للواجهة فقط، واعتمد على webhook envelope.completed (أو GET /v1/envelopes/{id}) لمعرفة النتيجة.

السمات

السمة (خاصية React / Vue)	الافتراضي	ملاحظات
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	عدد الميلي ثانية لانتظار الصفحة قبل حدث error بالرمز load_timeout
frame-title	Document signing	العنوان الذي تقرؤه أدوات الإتاحة للـ iframe

يحتوي العنصر أيضًا على التابع reload()، لاستخدامه مثلًا بعد إصدار جلسة جديدة.

الأحداث

تنتشر الأحداث صعودًا (bubble)، وتعبر جذور shadow، وتحمل الحمولة في 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 هي onReady وonFieldCompleted وonSigned وonCompleted وonDeclined وonSessionExpiring وonError وonEvent؛ أما Vue فيُطلق أسماء الأحداث (@completed، @session_expiring، …) وevent.

نموذج الأمان

• ينتقل الرمز في جزء الـ fragment من عنوان URL للـ iframe (#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.