Eingebettete Unterschrift

<bf-signing> rendert die Signaturseite von Bona Fide in einem Sandbox-iframe innerhalb Ihrer Seite, passt dessen Größe an das Dokument an und meldet die Aktionen des Unterzeichners als DOM-Events. Die Komponente kommt ohne Framework aus; schlanke Wrapper für React und Vue sind enthalten.

1. Erstellen Sie den Umschlag mit delivery: "embedded", damit Empfänger keine E-Mail erhalten.

2. Erzeugen Sie auf Ihrem Server eine Sitzung, wenn der Unterzeichner die Seite öffnet, mit dem Origin Ihrer Website in allowedOrigins. Die eingebettete Seite kommuniziert mit keiner übergeordneten Seite, die dort nicht aufgeführt ist.

   // 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. Rendern Sie das Element mit dem 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. Bestätigen Sie das Ergebnis auf Ihrem Server. Behandeln Sie das Browser-Event als Signal für die Oberfläche und verlassen Sie sich für das Ergebnis auf den envelope.completed-Webhook (oder auf GET /v1/envelopes/{id}).

Attribute

Attribut (React-/Vue-Prop)	Standard	Hinweise
session		Das Token bfs_…. Eine Änderung lädt den Frame neu
base-url (baseUrl)	https://sign.bonafidesign.com/s/	Die gehostete Signaturroute der Installation
theme	auto	auto, light oder dark
locale		Wird an die Signaturseite übergeben
min-height, max-height (minHeight, maxHeight)	480, 90vh	Pixel oder vh. Der Frame wächst zwischen beiden Werten mit dem Dokument und scrollt dann intern
timeout	30000	Millisekunden, die auf die Seite gewartet wird, bevor ein error mit dem Code load_timeout ausgelöst wird
frame-title	Document signing	Der barrierefreie Titel des iframes

Das Element hat außerdem eine Methode reload(), etwa nachdem Sie eine neue Sitzung erzeugt haben.

Events

Events steigen auf (Bubbling), überqueren Shadow Roots und tragen die Nutzdaten in event.detail. bf-event wird für alle ausgelöst.

Event	detail
ready	{ type: 'ready' }: Die Signaturseite ist geladen
field_completed	{ type, field }: Ein Feld wurde ausgefüllt
signed	{ type, recipient }: Dieser Empfänger hat abgesendet
completed	{ type, envelope }: Der Umschlag ist abgeschlossen
declined	{ type, reason? }
session_expiring	{ type, expiresAt }: Erzeugen Sie bald eine neue Sitzung
error	{ type, code, message }, einschließlich load_timeout und invalid_base_url

Die React-Props sind onReady, onFieldCompleted, onSigned, onCompleted, onDeclined, onSessionExpiring, onError und onEvent; Vue gibt die Eventnamen (@completed, @session_expiring, …) und event aus.

Sicherheitsmodell

• Das Token wird im URL-Fragment des iframes übertragen (#session=…), das nie einen Server oder einen Referer-Header erreicht. Die Signaturseite liest es, entfernt es aus URL und Verlauf und tauscht es gegen ein Zugriffstoken im Arbeitsspeicher ein. Es werden keine Cookies verwendet.
• Das iframe läuft in einer Sandbox (allow-scripts allow-same-origin allow-forms allow-popups allow-popups-to-escape-sandbox allow-downloads) mit referrerpolicy="strict-origin".
• Ihre Seite akzeptiert eine Nachricht nur, wenn sie aus dem eigenen iframe des Elements und vom Origin der base-url stammt und sich als Nachricht im Namensraum bona-fide.embed/1 parsen lässt. Alles andere wird ignoriert.
• Die Signaturseite sendet Nachrichten an Ihren exakten Origin (nie *), und nur dann, wenn dieser Origin in den allowedOrigins der Sitzung steht. Auch die API lehnt Aufrufe einer eingebetteten Sitzung von nicht erlaubten Origins ab.

Stattdessen gehostet

Wenn Sie lieber nicht einbetten möchten, erstellen Sie die Sitzung mit "mode": "hosted" und leiten Sie zu ihrer url weiter; setzen Sie returnUrl, um den Unterzeichner zurückzuholen. Siehe Signatursitzungen.

Hinweis

Die obige Skript-URL ist dieselbe, die das Einbettungs-Snippet des Dashboards verwendet. Das Element und seine Wrapper stammen aus einem Paket, @bona-fide/embed: Der Haupteinstiegspunkt registriert <bf-signing>, und @bona-fide/embed/react sowie @bona-fide/embed/vue exportieren BonaFideSigning.