Integrieren Sie den Legalesign Signer in Ihre Website

Für Ihr Team aktivieren

Die Signer-Komponente muss aktiviert werden. Kontaktieren Sie den Support, um sie für Ihr Team freizuschalten.

Aktuelle Version: v1.1.7 — Changelog

Der Legalesign Signer ist eine plattformunabhängige Web-Komponente, die eine vollständige und nahtlose Erfahrung beim Signieren von Dokumenten direkt in Ihrer eigenen App bietet. Er funktioniert mit einfachem HTML, React, Vue, Angular oder jedem Webframework.

Betten Sie diese Komponente überall dort ein, wo Ihre Benutzer Dokumente signieren müssen — innerhalb eines CRM, Kundenportals oder einer internen Anwendung, die HTML rendert.

Installation

Direkt vom CDN laden (keine Installation erforderlich):

<script type="module" src="https://cdn.legalesign.io/signer/latest/ls-signer.esm.js"></script>

React-Installation

Installation über einen Paketmanager:

npm install legalesign-signer
# or
pnpm add legalesign-signer

Grundlegende Integration

HTML & JavaScript

<ls-signer
  recipient-id="abc123"
  private-key="key"
  session-id="session"
></ls-signer>

<script>
  const signer = document.querySelector('ls-signer');
  signer.addEventListener('signingSuccess', (e) => console.log('Signed:', e.detail.eventType, e.detail.documentId));
  signer.addEventListener('signingFail', (e) => console.error('Failed:', e.detail.failureReason, e.detail.error));
  signer.addEventListener('fieldChange', (e) => console.log('Field event:', e.detail.eventType));
</script>

React

import { useEffect, useState } from 'react';
import { LsSigner } from 'legalesign-signer/react';
import 'legalesign-signer/react.css';

function SigningPage() {
  const [signerData, setSignerData] = useState(null);

  useEffect(() => {
    fetch('/your-backend/to-get-token')
      .then(res => res.json())
      .then(setSignerData);
  }, []);

  if (!signerData) return <p>Loading...</p>;

  return (
    <LsSigner
      recipientId={signerData.recipientId}
      privateKey={signerData.token}
      sessionId={signerData.sessionId}
      onSuccess={({ eventType, documentId }) => console.log(eventType, documentId)}
      onFail={({ eventType, failureReason, error }) => console.error(eventType, failureReason, error)}
      onChange={({ eventType, uuid, saved, field, document }) => console.log('Event:', eventType)}
    />
  );
}

React benötigt react und react-dom (v18 oder v19) als Peer-Dependencies.

Vue

<template>
  <ls-signer
    ref="signer"
    :recipient-id="recipientId"
    :private-key="privateKey"
    :session-id="sessionId"
  />
</template>

<script setup>
import { ref, onMounted, onBeforeUnmount } from 'vue';

const signer = ref(null);

function handleSuccess(e) {
  console.log('Signed:', e.detail);
}
function handleFail(e) {
  console.error('Failed:', e.detail);
}

onMounted(() => {
  signer.value.addEventListener('signingSuccess', handleSuccess);
  signer.value.addEventListener('signingFail', handleFail);
});

onBeforeUnmount(() => {
  signer.value?.removeEventListener('signingSuccess', handleSuccess);
  signer.value?.removeEventListener('signingFail', handleFail);
});
</script>

Tipp

Wenn Sie Vue mit Vite verwenden, fügen Sie isCustomElement: (tag) => tag.startsWith('ls-') zu Ihrer Vue-Plugin-Konfiguration hinzu, um Warnungen über unbekannte Elemente zu unterdrücken.

Warnung

Vue 3 wandelt Eventnamen bei benutzerdefinierten Elementen in Kleinbuchstaben um, daher funktioniert @signingSuccess nicht. Verwenden Sie addEventListener am Element-Ref wie oben gezeigt.

Nuxt 3

Um SSR-Fehler zu vermeiden, umschließen Sie <ls-signer> mit <ClientOnly>. Fügen Sie die Konfiguration für benutzerdefinierte Elemente in nuxt.config.ts hinzu:

export default defineNuxtConfig({
  vue: {
    compilerOptions: {
      isCustomElement: (tag) => tag.startsWith('ls-'),
    },
  },
});

Authentifizierung

Die Signer-Komponente benötigt ein kurzlebiges Token von Ihrem Backend. Es gibt zwei Optionen:

1. GraphQL generateComponentToken — Aufruf mit component: LS_SIGNER und entweder einem recipientId oder sessionId im Signer-Bereich (bitte eines angeben, nicht beide).
2. REST API — Aufruf GET /signer/{signerId}/component-token/ mit Ihrem API-Schlüssel.

Beide liefern das token und sessionId, die die Komponente benötigt. Siehe Widget Authorization für den vollständigen serverseitigen Token-Flow.

Option 1: GraphQL (Node.js)

Verwendung von recipientId (am häufigsten — verwenden, wenn Sie den Empfänger kennen, aber noch keine Sitzung haben):

const response = await fetch('https://graphql.uk.legalesign.com/graphql', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    Authorization: `Bearer ${process.env.LEGALESIGN_API_KEY}`,
  },
  body: JSON.stringify({
    query: `mutation MintSignerToken($input: GenerateComponentTokenInput!) {
      generateComponentToken(input: $input) {
        token
        tokenType
        sessionId
        expiresIn
        expiresAt
      }
    }`,
    variables: {
      input: {
        component: 'LS_SIGNER',
        signer: { recipientId: '<recipient-id>' }
      }
    }
  })
});

const { data } = await response.json();
const { token, sessionId } = data.generateComponentToken;

Alternativ, wenn Sie bereits eine sessionId aus einem vorherigen Aufruf haben:

variables: {
  input: {
    component: 'LS_SIGNER',
    signer: { sessionId: '<session-id>' }
  }
}

Option 2: REST API

const response = await fetch(
  `https://eu-api.legalesign.com/api/v1/signer/${signerId}/component-token/`,
  {
    headers: {
      Authorization: `Bearer ${process.env.LEGALESIGN_API_KEY}`,
    },
  }
);

const { token, sessionId } = await response.json();

Übergeben Sie token als private-key und sessionId als session-id an die Komponente.

Erforderliche Attribute

Attribut	Typ	Beschreibung
recipient-id	string	Empfänger-Identifikator (base64, Präfix rec oder UUID)
private-key	string	Token, zurückgegeben von generateComponentToken
session-id	string	Sitzungs-ID, zurückgegeben von generateComponentToken

Optionale Attribute

Attribut	Typ	Standard	Beschreibung
colour	string	blue	Farbthemenname (siehe Theming)
style	string	``	Stiländerungen (siehe Customer CSS)
branding	boolean	true	Legalesign-Branding anzeigen. Auf false setzen, um es zu entfernen.
language	string	—	Erzwingt eine bestimmte Sprache und blendet den Sprachumschalter aus (siehe Internationalisation)

Events

React-Prop	Web-Komponenten-Event	eventType	Wann
onSuccess	signingSuccess	"success"	Dokument erfolgreich signiert
onFail	signingFail	"failure"	Signierung fehlgeschlagen, abgelehnt, abgelaufen, abgebrochen, gelöscht, entfernt oder bereits anderweitig abgeschlossen
onChange	fieldChange	"ready"	Dokument und Bilder vollständig geladen
onChange	fieldChange	"save"	Ein Feldwert wurde gespeichert
onChange	fieldChange	"select"	Ein Feld wurde ausgewählt oder fokussiert

onSuccess / signingSuccess

Wird ausgelöst, wenn der Empfänger das Dokument erfolgreich signiert hat.

{
  eventType: 'success';
  documentId: string;   // UUID of the signed document
  recipientId: string;  // UUID of the recipient
}

React:

<LsSigner
  onSuccess={({ eventType, documentId, recipientId }) => {
    console.log(eventType);   // "success"
    console.log(documentId);
    console.log(recipientId);
  }}
/>

Web-Komponente:

signer.addEventListener('signingSuccess', (e) => {
  console.log(e.detail.eventType);   // "success"
  console.log(e.detail.documentId);
  console.log(e.detail.recipientId);
});

onFail / signingFail

Wird ausgelöst, wenn die Signierung fehlschlägt — entweder wegen einer Dokumentenablehnung oder eines Fehlers während des Signiervorgangs (z. B. Netzwerkfehler, abgelaufene Sitzung, Dokumentkonflikt).

{
  eventType: 'failure';
  failureReason: FailureReason;
  error: string;          // Human-readable error message
  documentId?: string;    // UUID of the document (if available)
  recipientId: string;    // UUID of the recipient
}

failureReason	Ursache
documentExpired	Dokument-state ist "expired" oder expires Datum liegt in der Vergangenheit
sessionExpired	API gab 401 oder 403 zurück beim Laden des Dokuments
cancelled	Dokument-state ist "cancelled"
deleted	Dokument-Flag is_deleted ist true
rejected	Empfänger lehnte das Dokument ab (is_rejected ist true)
removed	API gab 404 zurück — Dokument existiert nicht mehr
documentCompleted	Die Signier-API gab completed zurück — das Dokument wurde bereits signiert, wahrscheinlich in einem anderen Browser oder Gerät. Die Komponente zeigt dem Empfänger eine Informationsmeldung statt eines Fehlers.
signingError	Jeder andere Fehler beim Laden oder Signieren

React:

<LsSigner
  onFail={({ eventType, failureReason, error, documentId, recipientId }) => {
    console.log(eventType);      // "failure"
    console.log(failureReason);  // e.g. "documentExpired"
    console.log(error);
  }}
/>

Web-Komponente:

signer.addEventListener('signingFail', (e) => {
  console.log(e.detail.eventType);      // "failure"
  console.log(e.detail.failureReason);  // e.g. "documentExpired"
  console.log(e.detail.error);
});

onChange / fieldChange

Alle drei eventType-Werte teilen dasselbe Event. Verwenden Sie eventType, um zu unterscheiden.

eventType: "ready"

Wird einmal ausgelöst, wenn das Dokument und alle Seitenbilder vollständig geladen sind und die Signieroberfläche zur Interaktion bereitsteht.

{
  eventType: 'ready';
  document: {
    documentId: string;      // UUID of the document
    name: string;            // Document name
    state: string;           // Document state (e.g. "signing")
    recipientId: string;     // UUID of the recipient
    recipientRole?: string;  // Role of the recipient (e.g. "witness")
    pageCount: number;       // Number of pages
    expires?: string;        // Expiry date (ISO string, if set)
    isApprover: boolean;     // Whether the recipient is an approver
    isWitness: boolean;      // Whether the recipient is a witness
    canReassign: boolean;    // Whether the recipient can reassign
    doOfferReject: boolean;  // Whether the reject option is shown
  };
}

React:

<LsSigner
  onChange={({ eventType, document }) => {
    if (eventType === 'ready') {
      console.log('Ready to sign:', document.documentId, document.name);
      console.log('Pages:', document.pageCount);
      console.log('Expires:', document.expires);
    }
  }}
/>

Web-Komponente:

signer.addEventListener('fieldChange', (e) => {
  if (e.detail.eventType === 'ready') {
    console.log('Ready to sign:', e.detail.document.documentId, e.detail.document.name);
  }
});

eventType: "save"

Wird ausgelöst, nachdem ein Feldwert auf dem Server gespeichert wurde.

{
  eventType: 'save';
  uuid: string;                   // UUID of the field
  saved: boolean;                 // Whether the save was successful
  field: Record<string, any>;     // Full field object (see Field Properties below)
}

React:

<LsSigner
  onChange={({ eventType, uuid, saved, field }) => {
    if (eventType === 'save') {
      console.log(uuid, saved, field.value);
    }
  }}
/>

Web-Komponente:

signer.addEventListener('fieldChange', (e) => {
  if (e.detail.eventType === 'save') {
    console.log(e.detail.uuid, e.detail.saved, e.detail.field.value);
  }
});

eventType: "select"

Wird ausgelöst, wenn ein Feld ausgewählt oder fokussiert wird — ausgelöst durch Benutzerklick, Tastaturnavigation, Auto-Forward oder Seitenleisteninteraktion.

{
  eventType: 'select';
  uuid: string;                   // UUID of the selected field
  field: Record<string, any>;     // Full field object (see Field Properties below)
}

React:

<LsSigner
  onChange={({ eventType, uuid, field }) => {
    if (eventType === 'select') {
      console.log('selected', uuid, field.fieldtype);
    }
  }}
/>

Web-Komponente:

signer.addEventListener('fieldChange', (e) => {
  if (e.detail.eventType === 'select') {
    console.log('selected', e.detail.uuid, e.detail.field.fieldtype);
  }
});

Felder-Eigenschaften

Das in den save- und select-Events enthaltene field-Objekt enthält die folgenden Eigenschaften:

Eigenschaft	Typ	Beschreibung
uuid	string	Eindeutiger Feldbezeichner
fieldtype	string	Feldtyp (z. B. "text", "signature", "date", "checkbox")
value	string	Aktueller Feldwert
state	boolean	Ob das Feld erfolgreich gespeichert wurde
optional	boolean	Ob das Feld optional ist
page	number	Seitenzahl, auf der das Feld erscheint
label	string	Feldbeschriftung (falls gesetzt)
validation	number	Validierungstyp-Code
logicaction	string	Logik-Aktion-Typ ("1" = Radio, "2" = Summe, "3" = Bedingt)
logicgroup	string	Logik-Gruppen-ID
mapto	string	Zielgruppe für Logik (steuernde Felder)
auto	boolean	Ob das Feld automatisch ausgefüllt wird
dirty	boolean	Ob das Feld ungespeicherte lokale Änderungen hat

React Props

Die React-Komponente verwendet camelCase-Props und Callback-Props anstelle von DOM-Events:

Prop	Typ	Erforderlich	Beschreibung
recipientId	string	✅	Empfänger-Identifikator
privateKey	string	✅	Private Key aus der Mutation generateComponentToken
sessionId	string	✅	Sitzungs-ID
colour	LsSignerColour	❌	Farbthema
branding	boolean	❌	Legalesign-Branding anzeigen. Standard ist true.
language	string	❌	Erzwingt eine bestimmte Sprache (siehe Internationalisation)
onSuccess	(data: { eventType: 'success'; documentId: string; recipientId: string }) => void	❌	Wird bei erfolgreicher Signierung aufgerufen
onFail	(data: { eventType: 'failure'; failureReason: FailureReason; error: string; documentId?: string; recipientId: string }) => void	❌	Wird bei Signierungsfehler aufgerufen
onChange	(data: { eventType: 'ready' | 'save' | 'select'; document?: DocumentSummary; uuid?: string; saved?: boolean; field?: Record<string, any> }) => void	❌	Wird bei Feld-Events und wenn Dokument bereit ist aufgerufen

Allgemeiner Event-Handler (Debugging & Prototyping)

Da jedes Event eventType enthält, können Sie eine einzige Funktion an alle Events binden:

React:

const handleSignerEvent = (e) => {
  switch (e.eventType) {
    case 'success': console.log('Signed:', e.documentId); break;
    case 'failure': console.log('Failed:', e.failureReason, e.error); break;
    case 'ready':   console.log('Ready:', e.document?.name); break;
    case 'save':    console.log('Saved field:', e.uuid, e.saved); break;
    case 'select':  console.log('Selected field:', e.uuid); break;
  }
};

<LsSigner
  onSuccess={handleSignerEvent}
  onFail={handleSignerEvent}
  onChange={handleSignerEvent}
/>

Web-Komponente:

const handleSignerEvent = (e) => {
  switch (e.detail.eventType) {
    case 'success': console.log('Signed:', e.detail.documentId); break;
    case 'failure': console.log('Failed:', e.detail.failureReason, e.detail.error); break;
    case 'ready':   console.log('Ready:', e.detail.document?.name); break;
    case 'save':    console.log('Saved field:', e.detail.uuid, e.detail.saved); break;
    case 'select':  console.log('Selected field:', e.detail.uuid); break;
  }
};

signer.addEventListener('signingSuccess', handleSignerEvent);
signer.addEventListener('signingFail', handleSignerEvent);
signer.addEventListener('fieldChange', handleSignerEvent);

Theming

Setzen Sie ein Farbthema mit der colour-Prop. Alle Farbtöne werden automatisch abgeleitet.

Verfügbare Farben

pink · blue · purple · indigo · teal · green · lightblue · burnt · aubergine · red · yellow · cyan · lime · trueGreen

Lassen Sie die Prop weg für das Standardblau.

<ls-signer colour="pink" ...></ls-signer>

<LsSigner colour="pink" ... />

Die colour-Prop setzt ein data-ls-theme-Attribut an der Komponentenwurzel. CSS-Custom-Properties definieren eine 10–100 Tonscala für jede Farbe:

Farbton	Verwendung
10	Helle Hintergründe, subtile Füllungen
20	Subtile Rahmen
30	Fokus-Ringe
60	Primärfarbe (Buttons, Links, aktive Zustände)
70	Hover-Zustand
80	Dunkle/starke Akzente

Benutzerdefiniertes CSS

Die Komponente bietet CSS-Custom-Properties, die überschrieben werden können, um das Erscheinungsbild über das Farbthema hinaus anzupassen. Dieses Properties-Set ist derzeit begrenzt, kontaktieren Sie uns für weitere Optionen.

<ls-signer
  style="--ls-font-family: 'Inter', sans-serif; --ls-color-primary-60: #e91e63;"
  recipient-id="abc123"
  private-key="key"
  session-id="session"
></ls-signer>

Verfügbare Eigenschaften

Eigenschaft	Standard	Beschreibung
--ls-font-family	'IBM Plex Sans', sans-serif	Primäre Schriftfamilie
--ls-color-primary-10 bis --ls-color-primary-100	—	Voller Primärfarbton-Skala (überschreibt Thema)
--ls-color-error	#f64a44	Fehlerzustandsfarbe
--ls-color-error-light	#fff0f0	Fehler-Hintergrund
--ls-color-success	#46dbaa	Erfolgszustandsfarbe
--ls-color-success-light	#effff9	Erfolgs-Hintergrund
--ls-color-warning	#fad232	Warnzustandsfarbe
--ls-color-warning-light	#fffcef	Warn-Hintergrund
--ls-color-border	#d8d9dc	Standard-Rahmenfarbe
--ls-color-border-subtle	#e0e2e5	Subtile Rahmenfarbe
--ls-color-bg-subtle	#f7f8fa	Subtiler Hintergrund

Hinweis: Für vollständige benutzerdefinierte CSS-Injektion (direktes Targeting interner Elemente, Überschreiben von Schriftgrößen, Border-Radius, Abständen etc.) ist dies eine geplante zukünftige Funktion. Bitte melden Sie sich bei uns, wenn Sie interessiert sind.

Internationalisierung

Die Komponente unterstützt 17 Sprachen mit in den Build eingebetteten Übersetzungen. Die Sprache wird automatisch anhand des Browsers erkannt. Ein integrierter Sprachumschalter in der Signier-Oberfläche ermöglicht es dem Empfänger, die Sprache jederzeit zu wechseln.

Setzen Sie das language-Attribut, um eine bestimmte Sprache zu erzwingen. Wird es gesetzt, wird der integrierte Sprachumschalter ausgeblendet und die Browser-Erkennung umgangen.

<ls-signer language="fr" recipient-id="abc123" private-key="key" session-id="session"></ls-signer>

<LsSigner language="fr" recipientId="abc123" privateKey="key" sessionId="session" />

Prioritätsreihenfolge: language-Prop → Browsersprache → Englische Fallback-Sprache.

Code	Sprache	Code	Sprache
en	Englisch	nl	Niederländisch
fr	Französisch	fi	Finnisch
bg	Bulgarisch	it	Italienisch
es	Spanisch	he	Hebräisch
de	Deutsch	sv	Schwedisch
gs	Schottisch-Gälisch	cy	Walisisch
ar	Arabisch	is	Isländisch
el	Griechisch	iw	Hebräisch (Legacy)
pt	Portugiesisch
ro	Rumänisch

CDN-Versionierung

Die CDN-URL unterstützt sowohl latest als auch feste Versionsnummern:

<!-- Always get the most recent version (recommended) -->
<script type="module" src="https://cdn.legalesign.io/signer/latest/ls-signer.esm.js"></script>

<!-- Pin to a specific version -->
<script type="module" src="https://cdn.legalesign.io/signer/v1.1.7/ls-signer.esm.js"></script>

Wir empfehlen die Verwendung von latest — damit erhält Ihre Integration automatisch Fehlerbehebungen, Sicherheitspatches und neue Funktionen. Verwenden Sie eine feste Version, wenn Sie während eines QA-Freeze oder kontrollierten Rollouts an einer bekannten, stabilen Version festhalten müssen. Siehe die vollständige Versionshistorie bei npm für verfügbare Versionen.

Komplettes Beispiel

<!DOCTYPE html>
<html>
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>Document Signing</title>
    <script type="module" src="https://cdn.legalesign.io/signer/latest/ls-signer.esm.js"></script>
  </head>
  <body>
    <ls-signer
      recipient-id="abc123"
      private-key="key"
      session-id="session"
      colour="teal"
    ></ls-signer>

    <script>
      const signer = document.querySelector('ls-signer');

      signer.addEventListener('signingSuccess', (event) => {
        console.log('Document signed:', event.detail.documentId);
        window.location.href = '/thank-you';
      });

      signer.addEventListener('signingFail', (event) => {
        console.error('Signing failed:', event.detail.failureReason, event.detail.error);
      });

      signer.addEventListener('fieldChange', (event) => {
        if (event.detail.eventType === 'ready') {
          console.log('Ready to sign:', event.detail.document.name);
        }
      });
    </script>
  </body>
</html>

Browser-Unterstützung

• Chrome/Edge (aktuellste Versionen)
• Firefox (aktuellste Versionen)
• Safari (aktuellste Versionen)
• Mobile Browser (iOS Safari, Chrome Mobile)

Changelog

Version	Datum	Zusammenfassung
v1.1.7	20 Okt 2026	documentCompleted als Fehlergrund; Verbesserungen beim Feldspeichern; Positionskorrekturen; verbesserte Fehlerereigniserfassung
v1.1.0	22 Jul 2026	onChange / fieldChange-Event; language-Prop; bedingte Felder; Auto-Jump; QES
v1.0.12	20 Jul 2026	onChange / fieldChange Event mit ready, save, select; Werte für failureReason; Regex-Validierung
v1.0.11	15 Jul 2026	language-Prop; bedingte, Dropdown-, Checkbox-Felder; Phone-Input; Feldreihenfolge
v1.0.6	9 Jun 2026	branding-Prop hinzugefügt
v1.0.3	15 Mai 2026	colour-Prop; CSS-Custom-Properties; Fehlerbehebungen
v1.0.0	11 Mai 2026	Erste stabile Version

Ressourcen

• NPM-Paket
• Widget Authorization
• GraphQL API Dokumentation
• Migration von iframe-Signierung
• Support

Video: Migration von iframe zur Signer-Komponente