Ký nhúng

<bf-signing> kết xuất trang ký của Bona Fide trong một iframe sandbox bên trong trang của bạn, điều chỉnh kích thước theo tài liệu, và báo cáo các thao tác của người ký dưới dạng sự kiện DOM. Thành phần này không phụ thuộc framework; kèm theo là các bản bao gọn nhẹ cho React và Vue.

1. Tạo phong bì với delivery: "embedded", để người nhận không nhận email.

2. Tạo phiên trên máy chủ của bạn khi người ký mở trang, với origin của trang web bạn trong allowedOrigins. Trang nhúng từ chối giao tiếp với bất kỳ trang cha nào không có trong danh sách đó.

   // 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. Kết xuất phần tử với token.

   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. Xác nhận trên máy chủ của bạn. Hãy coi sự kiện trình duyệt là tín hiệu giao diện và dựa vào webhook envelope.completed (hoặc GET /v1/envelopes/{id}) để biết kết quả.

Thuộc tính

Thuộc tính (prop React / Vue)	Mặc định	Ghi chú
session		Token bfs_…. Thay đổi giá trị sẽ tải lại khung
base-url (baseUrl)	https://sign.bonafidesign.com/s/	Đường dẫn trang ký lưu trữ sẵn của bản triển khai
theme	auto	auto, light hoặc dark
locale		Được chuyển cho trang ký
min-height, max-height (minHeight, maxHeight)	480, 90vh	Pixel hoặc vh. Khung tăng chiều cao theo tài liệu trong khoảng giữa hai giá trị, sau đó cuộn bên trong
timeout	30000	Số mili giây chờ trang trước khi phát error với mã load_timeout
frame-title	Document signing	Tiêu đề hỗ trợ tiếp cận của iframe

Phần tử còn có phương thức reload(), chẳng hạn dùng sau khi tạo một phiên mới.

Sự kiện

Sự kiện nổi bọt, đi xuyên qua shadow root và mang payload trong event.detail. bf-event được phát cho tất cả sự kiện.

Sự kiện	detail
ready	{ type: 'ready' }: trang ký đã tải xong
field_completed	{ type, field }: một trường đã được điền
signed	{ type, recipient }: người nhận này đã gửi
completed	{ type, envelope }: phong bì đã hoàn tất
declined	{ type, reason? }
session_expiring	{ type, expiresAt }: hãy sớm tạo phiên mới
error	{ type, code, message }, bao gồm load_timeout và invalid_base_url

Các prop của React là onReady, onFieldCompleted, onSigned, onCompleted, onDeclined, onSessionExpiring, onError và onEvent; Vue phát các tên sự kiện (@completed, @session_expiring, …) và event.

Mô hình bảo mật

• Token được truyền trong phần fragment của URL iframe (#session=…), phần này không bao giờ đến máy chủ hay header Referer. Trang ký đọc token, xóa nó khỏi URL và lịch sử, rồi đổi nó lấy một token truy cập giữ trong bộ nhớ. Không dùng cookie.
• Iframe chạy trong sandbox (allow-scripts allow-same-origin allow-forms allow-popups allow-popups-to-escape-sandbox allow-downloads) với referrerpolicy="strict-origin".
• Trang của bạn chỉ chấp nhận một thông điệp khi nó đến từ chính iframe của phần tử và từ origin base-url và phân tích được thành thông điệp bona-fide.embed/1 có namespace. Mọi thứ khác đều bị bỏ qua.
• Trang ký gửi thông điệp đến đúng origin của bạn (không bao giờ là *), và chỉ khi origin đó có trong allowedOrigins của phiên. API cũng từ chối các lệnh gọi của phiên nhúng đến từ origin không được phép.

Dùng trang lưu trữ sẵn thay thế

Nếu bạn không muốn nhúng, hãy tạo phiên với "mode": "hosted" và chuyển hướng đến url của nó; đặt returnUrl để đưa người ký quay lại. Xem Phiên ký.

Ghi chú

URL script ở trên là URL mà đoạn mã nhúng của bảng điều khiển sử dụng. Phần tử và các bản bao của nó đến từ một gói duy nhất, @bona-fide/embed: điểm vào gốc đăng ký <bf-signing>, còn @bona-fide/embed/react và @bona-fide/embed/vue xuất BonaFideSigning.