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.

Der Legalesign Signer ist eine plattformunabhängige Webkomponente, die ein vollständiges und nahtloses Dokumentenunterschriftserlebnis direkt innerhalb Ihrer eigenen App bietet. Er funktioniert mit reinem HTML, React, Vue, Angular oder jedem anderen Webframework.

Betten Sie diese Komponente überall dort ein, wo Ihre Benutzer Dokumente unterschreiben müssen – in einem CRM, Kundenportal oder jeder internen Anwendung, die HTML rendert.

Installation

Laden Sie direkt vom CDN (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-Abhängigkeiten.

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 wegen unbekannter Elemente zu unterdrücken.

Warnung

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

Nuxt 3

Um SSR-Fehler zu vermeiden, wickeln Sie <ls-signer> in <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 recipientId oder sessionId im Signer Scope (geben Sie eines an, nicht beide).
2. REST API — Aufruf von GET /signer/{signerId}/component-token/ mit Ihrem API-Schlüssel.

Beide liefern das token und die 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 der Empfänger bekannt ist, aber noch keine Sitzung existiert):

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 von 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ängerkennung (base64, mit rec Präfix oder UUID)
private-key	string	Von generateComponentToken zurückgegebenes Token
session-id	string	Von generateComponentToken zurückgegebene Sitzungs-ID

Optionale Attribute

Attribut	Typ	Standard	Beschreibung
colour	string	blue	Name der Designfarbe (siehe Theming)
style	string	``	Stiländerungen (siehe Custom CSS)
branding	boolean	true	Entfernt das Legalesign Branding
language	string	—	Erzwingt eine spezifische Sprache und blendet den Sprachumschalter aus (siehe Internationalisation)

Events

Webkomponenten-Ereignis	React-Prop	eventType	Wann
signingSuccess	onSuccess	"success"	Dokument erfolgreich unterschrieben
signingFail	onFail	"failure"	Unterschrift fehlgeschlagen, abgelehnt, abgelaufen, abgebrochen, gelöscht oder entfernt
fieldChange	onChange	"ready"	Dokument und Bilder vollständig geladen
fieldChange	onChange	"save"	Ein Feldwert wurde gespeichert
fieldChange	onChange	"select"	Ein Feld wurde ausgewählt oder fokussiert

signingSuccess / onSuccess

{
  eventType: 'success';
  documentId: string;
  recipientId: string;
}

signingFail / onFail

{
  eventType: 'failure';
  failureReason: FailureReason;
  error: string;
  documentId?: string;
  recipientId: string;
}

failureReason	Ursache
documentExpired	Dokument ist abgelaufen oder das Ablaufdatum liegt in der Vergangenheit
sessionExpired	API lieferte 401 oder 403
cancelled	Dokumentzustand ist "cancelled"
deleted	Dokument wurde gelöscht
rejected	Empfänger hat das Dokument abgelehnt
removed	API lieferte 404
signingError	Jeder andere Fehler während des Ladens oder der Unterschrift

fieldChange / onChange

Alle drei eventType-Werte teilen dasselbe Ereignis. Verwenden Sie eventType zur Unterscheidung:

// eventType: 'ready' — document fully loaded
{ eventType: 'ready'; document: { documentId, name, state, recipientId, pageCount, expires?, isApprover, isWitness, canReassign, doOfferReject } }

// eventType: 'save' — field value saved
{ eventType: 'save'; uuid: string; saved: boolean; field: Record<string, any> }

// eventType: 'select' — field selected or focused
{ eventType: 'select'; uuid: string; field: Record<string, any> }

React Props

Die React-Komponente verwendet camelCase-Props und Rückruffunktionen anstelle von DOM-Ereignissen:

Prop	Typ	Erforderlich	Beschreibung
recipientId	string	✅	Empfängerkennung
privateKey	string	✅	Privater Schlüssel aus der generateComponentToken Mutation
sessionId	string	✅	Sitzungskennung
colour	LsSignerColour	❌	Designfarbe
branding	boolean	❌	Zeigt das Legalesign Branding an. Standard ist true.
language	string	❌	Erzwingt eine spezifische Sprache (siehe Internationalisation)
onSuccess	(data: { eventType: 'success'; documentId: string; recipientId: string }) => void	❌	Wird bei erfolgreichem Unterschreiben aufgerufen
onFail	(data: { eventType: 'failure'; failureReason: FailureReason; error: string; documentId?: string; recipientId: string }) => void	❌	Wird bei Fehlgeschlagenem Unterschreiben aufgerufen
onChange	(data: { eventType: 'ready' | 'save' | 'select'; document?: DocumentSummary; uuid?: string; saved?: boolean; field?: Record<string, any> }) => void	❌	Wird bei Feldereignissen und Dokumentbereitstellung aufgerufen

Catch-all Handler (Debugging & Prototyping)

Da jedes Ereignis eventType enthält, können Sie eine einzelne Funktion für alle Ereignisse verwenden:

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}
/>

Webkomponente:

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

Legen Sie ein Farbthema mit der colour-Prop fest. Alle Farbstufen 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 am Komponenten-Root. CSS-Custom-Properties definieren eine 10–100-Farbskala für jede Farbe:

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

Benutzerdefiniertes CSS

Die Komponente stellt CSS-Custom-Properties zur Verfügung, die überschrieben werden können, um das Erscheinungsbild über das Farbschema hinaus anzupassen. Dieses Set von Eigenschaften ist derzeit begrenzt, kontaktieren Sie uns für mehr.

<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	—	Vollständige Primärfarbskala (überschreibt das Thema)
--ls-color-error	#f64a44	Fehlerzustandsfarbe
--ls-color-error-light	#fff0f0	Fehlerhintergrund
--ls-color-success	#46dbaa	Erfolgszustandsfarbe
--ls-color-success-light	#effff9	Erfolgshintergrund
--ls-color-warning	#fad232	Warnzustandsfarbe
--ls-color-warning-light	#fffcef	Warnhintergrund
--ls-color-border	#d8d9dc	Standard-Randfarbe
--ls-color-border-subtle	#e0e2e5	Dezente Randfarbe
--ls-color-bg-subtle	#f7f8fa	Dezenter Hintergrund

Hinweis: Für vollständige benutzerdefinierte CSS-Injektion (direktes Anvisieren interner Elemente, Überschreiben von Schriftgrößen, Border-Radius, Abständen etc.) ist ein zukünftiges Feature geplant. Bitte kontaktieren Sie uns, wenn Sie daran interessiert sind.

Internationalisierung

Die Komponente unterstützt 17 Sprachen mit im Build enthaltenen Übersetzungen. Die Sprache wird automatisch anhand des Browsers erkannt. Ein eingebauter Sprachumschalter in der Signatur-UI erlaubt dem Empfänger, die Sprache jederzeit zu ändern.

Setzen Sie das language-Attribut, um eine bestimmte Sprache zu erzwingen. Wenn angegeben, wird der eingebaute 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 Standard fallback.

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.0/ls-signer.esm.js"></script>

Wir empfehlen die Verwendung von latest — das stellt sicher, dass Ihre Integration automatisch Fehlerbehebungen, Sicherheitspatches und neue Funktionen erhält. Verwenden Sie eine feste Version, wenn Sie während einer QA-Phase oder einem kontrollierten Rollout auf eine bekannte funktionierende Version festlegen müssen. Siehe die vollständige Versionshistorie auf 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 (aktuell)
• Firefox (aktuell)
• Safari (aktuell)
• Mobile Browser (iOS Safari, Chrome Mobile)

Ressourcen

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

Video: Migration von iframe zum Signer-Komponente