Integrieren Sie den Legalesign-Dokumenten-Viewer in Ihre Website
Sie können diese Komponente in Aktion als Quick Send in der Console sehen.
Aktuelle Version: v1.0.27 — Changelog
Der Legalesign Document Viewer ist eine plattformunabhängige Webkomponente, mit der Sie Vorlagen für die Dokumentenunterzeichnung bearbeiten, anzeigen und anpassen können. Sie funktioniert nahtlos in HTML mit JavaScript, React, Vue, Angular oder jedem Webframework.
Diese Plug-and-Play-Komponente ist so konzipiert, dass Sie wichtige Teile der Dokumentenerstellung in Ihre internen Systeme integrieren können, wie z. B. ein CRM oder eine Fachanwendung.
Solange Ihr System HTML-Komponenten rendern und unterstützen kann, können Sie den Document Viewer verwenden.
Wenn Sie zusätzliche Unterstützung bei der Integration des Document Viewer in Ihren technischen Stack benötigen, wenden Sie sich bitte an unseren Support.
Sie können diese größeren Widgets mit REST/GraphQL-API-Integrationen verwenden, um nahtlose Dokumentenunterzeichnungsprozesse für Ihre Mitarbeiter und Kunden zu ermöglichen.
Installation
NPM Installation
npm install legalesign-document-viewer
# or
pnpm add legalesign-document-viewer
Für React-Projekte
npm install legalesign-document-viewer-react
# or
pnpm add legalesign-document-viewer-react
Grundlegende Integration
HTML/JavaScript
Die HTML/JavaScript-Version dieser Komponente kann mit jedem Entwicklungs-Stack, wie PHP, ASP .Net usw., verwendet werden. Sie können direkt von npm auf die Komponente verlinken, wenn Ihre Umgebung keine Installation zulässt. Eine Demonstrationsseite aus dem Beispiel-Repository finden Sie hier: [https://github.com/legalesign/ls-viewer-demo].
Fügen Sie die Komponentenskripte zu Ihrem HTML hinzu:
<!DOCTYPE html>
<html>
<head>
<link rel="stylesheet" href="node_modules/legalesign-document-viewer/dist/ls-document-viewer/ls-document-viewer.css" />
<script type="module" src="node_modules/legalesign-document-viewer/dist/ls-document-viewer/ls-document-viewer.esm.js"></script>
<script nomodule src="node_modules/legalesign-document-viewer/dist/ls-document-viewer/ls-document-viewer.js"></script>
</head>
<body>
<ls-document-viewer
id="my-editor"
templateid="YOUR_TEMPLATE_ID"
token="YOUR_AUTH_TOKEN"
></ls-document-viewer>
</body>
</html>
Authentifizierung - Erhalten Sie ein Token
Sie müssen serverseitigen Code verwenden, um YOUR_AUTH_TOKEN zu erhalten. Es gibt zwei Optionen, und beide verwenden Ihren API-Schlüssel:
- GraphQL
generateComponentToken— Rufen Sie die Mutation mit Ihrem API-Schlüssel auf, um ein kurzlebiges, eingrenzbares Komponententoken zu erzeugen. - REST API — Rufen Sie
GET /templatepdf/{pdfId}/component-token/mit Ihrem API-Schlüssel auf.
Option 1 (GraphQL):
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 {
generateComponentToken(input: { component: LS_DOCUMENT_VIEWER }) {
token
expiresIn
expiresAt
}
}`,
}),
});
const { data } = await response.json();
const token = data.generateComponentToken.token;
Option 2 (REST):
const response = await fetch(
`https://eu-api.legalesign.com/api/v1/templatepdf/${pdfId}/component-token/`,
{
headers: {
Authorization: `Bearer ${process.env.LEGALESIGN_API_KEY}`,
},
}
);
const { token } = await response.json();
Übergeben Sie das zurückgegebene token an das Widget. Weitere Details zu Tokenoptionen finden Sie unter Widget Authorization.
React-Integration
Wir haben auch eine Version der Komponente erstellt, die sich direkt in React-Frameworks integrieren lässt.
import { LsDocumentViewer } from 'legalesign-document-viewer-react';
function App() {
return (
<LsDocumentViewer
templateid="YOUR_TEMPLATE_ID"
token="YOUR_AUTH_TOKEN"
mode="compose"
/>
);
}
Erforderliche Attribute
token
Ihr Sicherheitstoken zur Authentifizierung: ein kurzlebiges Komponententoken von generateComponentToken oder dem REST-Endpunkt component-token. Weitere Informationen zum sicheren Tokenfluss finden Sie unter Widget Authorization.
token="eyJraWQiOiJBTkJIeT..."
templateid
Die API-ID der Vorlage, die Sie den Benutzern präsentieren möchten. Diese finden Sie in der URL, wenn Sie die Vorlage in der Webanwendung bearbeiten.
templateid="dHBsYjQ5YTg5NWQtYWRhMy0xMWYwLWIxZGMtMDY5NzZlZmU0MzIx"
Widget-Modi
Editor-Modus
Voll ausgestattete Vorlagenerstellung und -bearbeitung mit allen verfügbaren Werkzeugen. Dieser Modus ist für Workflows gedacht, bei denen eine hochgradig wiederverwendbare Vorlage mit Rollen hilfreich ist. Wenn Sie das Dokument nur einmal verwenden möchten (vielleicht hat Ihr Dokumentengenerierungssystem bereits alle Kundeninformationen ausgefüllt), sollten Sie stattdessen den Compose-Modus in Betracht ziehen.
<ls-document-viewer mode="editor" ...></ls-document-viewer>
Compose-Modus
Dieser Modus ist eine „Empfänger-zuerst“-Methode, um die Benutzererfahrung zu vereinfachen. In der Legalesign-Webanwendung ist dies die Funktion „Quick send“.
Fügen Sie Ihre Empfänger dem Attribut „recipient“ hinzu, und Ihr Benutzer kann schnell seine Unterschriften und Formularfelder platzieren, bevor er das Dokument sendet. Ideal für integrierte Kunden, bei denen Empfänger bereits definiert sind.
Der typische Workflow ist: PDF klonen oder hochladen, dann den Viewer einbetten, wo der Benutzer Unterschrifts- und Formularfelder hinzufügen kann, und dann eine Schaltfläche zum Senden des Dokuments anbieten.
Klonen
Klonen Sie eine vorhandene Vorlage mit der Mutation copyTemplate:
const response = await fetch('https://graphql.uk.legalesign.com/graphql', {
method: 'POST',
headers: {
'Authorization': `Bearer ${token}`,
'Content-Type': 'application/json'
},
body: JSON.stringify({
query: `
mutation CopyTemplate {
copyTemplate(input: {
groupId: "yourGroupId",
templateId: "yourTemplateId",
newTitle: "new document title",
copyFields: true|false
})
}
`
})
});
const { data } = await response.json();
const templateId = data.copyTemplate;
Oder Hochladen
Erstellen Sie eine Vorlage und laden Sie diese dann auf die bereitgestellte uploadUrl hoch. Verwenden Sie den Titel [deleted], wenn Sie das PDF nicht in Ihrer Bibliothek behalten möchten. Es wird in den nächsten 24 Stunden gelöscht. Andernfalls können Sie jeden gewünschten Titel verwenden:
const response = await fetch('https://graphql.uk.legalesign.com/graphql', {
method: 'POST',
headers: {
'Authorization': `Bearer ${token}`,
'Content-Type': 'application/json'
},
body: JSON.stringify({
query: `
mutation CreateTemplate {
createTemplate(input: {groupId: "yourGroupid", title: "[deleted]"}) {
id
uploadUrl
}
}
`
})
});
const { data } = await response.json();
const templateId = data.createTemplate.id;
const uploadUrl = data.createTemplate.uploadUrl;
Laden Sie nun Ihre Datei per PUT auf die uploadUrl hoch. Der Content-Type muss application/pdf sein.
Viewer einbetten
Das Hauptattribut ist 'recipients'. Für Genehmiger oder Zeugen benötigen Sie zusätzliche Details – weitere Informationen finden Sie unter Recipients.
<ls-document-viewer
mode="compose"
recipients='[
{"email": "user@example.com", "firstname": "John", "lastname": "Doe", "signerIndex": 1},
{"email": "user2@example.com", "firstname": "Jane", "lastname": "Smith", "signerIndex": 2}
]'
...></ls-document-viewer>
Der Compose-Modus bewirkt automatisch:
- Erkennung vorab generierter Empfänger
- Verstecken des Absenders im Dropdown
- Verstecken der Dokumentoptionen
- Anzeigen der erforderlichen Felder standardmäßig
- Entfernen des Absenders und der Absenderfelder aus dem Editor
- Förderung der schnellen Auswahl der erforderlichen Felder für jeden Empfänger
Vorschau-Modus
Eine hilfreiche Dokumentenvorschau, die das Dokument mit allen aktuellen Feldern anzeigt und dem Benutzer das Blättern durch die Seiten ermöglicht.
<ls-document-viewer mode="preview" ...></ls-document-viewer>
Der Vorschau-Modus bewirkt automatisch:
- Verstecken der Symbolleiste
- Verstecken der Dokumentoptionen
- Verstecken der Toolbox
- Teilnehmer und Felder werden schreibgeschützt
Erweiterte Konfiguration
Filter-Toolbox
Beschränken Sie verfügbare Feldtypen mit durch Pipes getrennten Werten. Wenn kein Wert angegeben ist, wird davon ausgegangen, dass die Toolbox ungefiltert ist und alle Optionen verfügbar sind.
<ls-document-viewer
filtertoolbox="signature|initials|date|text"
...
></ls-document-viewer>
Verfügbare Filterwerte:
| Wert | Beschreibung |
|---|---|
signature | Unterschriftsfeld (nur Unterzeichner) |
auto sign | Auto-Unterschriftsfeld (nur Absender) |
text | Freier Texteingabe |
signing date | Datum, das beim Unterschreiben automatisch ausgefüllt wird (nur Unterzeichner) |
date | Datumsauswahlfeld |
email | E-Mail-Eingabe |
initials | Initialenfeld |
number | Numerische Eingabe |
dropdown | Dropdown-Auswahl |
checkbox | Kontrollkästchen |
regex | Regex-validierte Eingabe (nur Unterzeichner) |
image | Bild-Upload (nur Unterzeichner) |
file | Datei-Upload (nur Unterzeichner) |
drawn | Zeichnungs-/Freihandfeld (nur Unterzeichner) |
Empfänger
Definieren Sie Dokumentempfänger im JSON-Format.
Die erforderlichen Elemente für jeden Empfänger sind firstname, lastname, email und signerIndex;
Optional können Sie für jeden Empfänger die Rolle und Telefonnummer übergeben. Wird keine Rolle angegeben, wird der Empfänger als Unterzeichner behandelt.
Sie können die Rolle "WITNESS" oder "APPROVER" angeben. Für die Rolle "WITNESS" addieren Sie 100 zur signerIndex-Nummer des jeweiligen Unterzeichners. Wenn Sie beispielsweise einen Zeugen für Unterzeichner 2 (signerIndex: 2) benötigen, geben Sie WITNESS signerIndex: 102 an.
<ls-document-viewer
recipients='[
{"email": "user@example.com", "firstname": "John", "lastname": "Doe", "signerIndex": 1},
{"email": "user2@example.com", "firstname": "Jane", "lastname": "Smith", "signerIndex": 2}
{"email": "user3@example.com", "firstname": "Joan", "lastname": "Mitchell", "signerIndex": 102, roleType: "WITNESS"}
]'
...
></ls-document-viewer>
Benutzerdefinierte Schaltflächen mit Slots
Fügen Sie der Symbolleiste benutzerdefinierte Schaltflächen mit Slots hinzu. Wahrscheinlich verwenden Sie diese, um entweder den Vorgang abzubrechen oder das Dokument zu senden.
<ls-document-viewer ...>
<style>
.custom-button {
padding: 2px 12px;
border-radius: 1rem;
background-color: #9df5d4;
color: #125241;
font-weight: 500;
}
</style>
<span slot="left-button">
<button class="custom-button">Cancel</button>
</span>
<span slot="right-button">
<button class="custom-button">Send Document</button>
</span>
</ls-document-viewer>
Ereignisverarbeitung
Hören Sie auf Komponentenevents, um Änderungen zu verfolgen:
const editor = document.querySelector('ls-document-viewer');
editor.addEventListener('update', (event) => {
console.log('Template changed:', event.detail);
});
Sie können verfolgen, ob eine Vorlage gültig oder ungültig geworden ist, indem Sie das validate-Event verwenden.
const editor = document.querySelector('ls-document-viewer');
editor.addEventListener('validate', (event) => {
console.log('Template validation changed:', event.detail.valid);
});
Beispiel für Event-Handling in React
In React werden Events mit dem bekannten Präfix on<EventName> benutzt.
<LsDocumentViewer
onUpdate={(event) => {
console.log('Template changed:', event.detail);
}}
...
/>
Event-Typen
update-Event
Wird ausgelöst, wenn die Dokumentvorlage geändert wird, z. B. durch Hinzufügen oder Entfernen von Feldern. Liefert nicht nur das auslösende Event, sondern auch den aktualisierten Zustand des Vorlagenobjekts als JSON.
validate-Event
Wird ausgelöst, wenn die Dokumentvorlage geändert wird; die Eigenschaft valid im Detail zeigt an, ob die Vorlage gültig oder ungültig geworden ist.
selectFields-Event
Wird ausgelöst, wenn ein Feld im Editor ausgewählt wird.
addParticipant-Event
Wird ausgelöst, wenn eine Teilnehmerrolle zur Vorlage hinzugefügt wird.
Komplettes Beispiel
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>Document Editor</title>
<link rel="stylesheet" href="https://unpkg.com/legalesign-document-viewer/ls-document-viewer.css" />
<script type="module" src="https://unpkg.com/legalesign-document-viewer"></script>
</head>
<body style="padding: 0; margin: 0">
<ls-document-viewer
id="my-editor"
templateid="dHBsYjQ5YTg5NWQtYWRhMy0xMWYwLWIxZGMtMDY5NzZlZmU0MzIx"
token="YOUR_TOKEN_HERE"
mode="compose"
recipients='[
{"email": "signer@example.com", "firstname": "John", "lastname": "Doe", "signerIndex": 1}
]'
filtertoolbox="signature|initials|date"
>
<span slot="left-button">
<button onclick="handleCancel()">Cancel</button>
</span>
<span slot="right-button">
<button onclick="handleSend()">Send</button>
</span>
</ls-document-viewer>
<script>
const editor = document.querySelector('ls-document-viewer');
editor.addEventListener('update', (event) => {
// shows the change event and the template details
console.log('Document updated:', event.detail);
});
function handleCancel() {
// Implement the cancel logic, e.g. go to a home page
window.location.href = '/cancelpage';
}
function handleSend() {
// Implement send logic if required.
console.log('Sending document...');
}
</script>
</body>
</html>
Senden Sie das Dokument serverseitig mit Ihrem API-Schlüssel über die GraphQL- oder REST-Schnittstelle.
- Send mutation — senden eines einzelnen Dokuments
- Send Input Schema — vollständige Eingabereferenz
- REST Send - REST Referenz zum Dokument senden
Fehlerbehebung
Wenn Sie Probleme mit der Komponente haben, stellen Sie sicher, dass:
- Sie auf die Domain der Dokumentenspeicherung zugreifen können oder diese unter https://s3.amazonaws.com/* freigeschaltet haben
Browser-Unterstützung
Die Komponente verwendet moderne Webstandards und unterstützt:
- Chrome/Edge (neueste Version)
- Firefox (neueste Version)
- Safari (neueste Version)
- Mobile Browser (iOS Safari, Chrome Mobile)
Changelog
| Version | Datum | Zusammenfassung |
|---|---|---|
| v1.0.27 | 19. Okt 2026 | Verbesserungen bei der Feldpositionierung |
| v1.0.26 | 3. Sep 2026 | Scroll-Fixes; verzögertes Rendering beim Laden |
| v1.0.21 | 12. Aug 2026 | Vorschau-Modus-Optionen; Verbesserungen beim update-Event |
| v1.0.18 | 17. Jul 2026 | Regex-Feldpanel; erweiterte Eigenschaften für Mehrfachfelder; Dropdown-Verbesserungen; Umbenennung von Zeugen |
| v1.0.12 | 10. Jul 2026 | excludeFromPdf-Feld-Eigenschaft |
| v1.0.9 | 9. Jul 2026 | Auto-Datum und Regex-Felder; erweiterte Eigenschaften; Feldreihenfolge |
| v1.0.6 | 2. Jul 2026 | Schriftarten-Fix zur Vermeidung von Signaturfehlern; Vorschau-Ränder |
| v1.0.5 | 29. Jun 2026 | Undo/Redo-Tastenkürzel |
| v1.0.4 | 26. Jun 2026 | Verbesserungen bei Events; optimistische Updates; Undo/Redo |
| v1.0.0 | 24. Jun 2026 | Erste stabile Version |
Ressourcen
- GraphQL Integrationsanleitung — wie man den Viewer mit der GraphQL API für das Senden verbindet
- GraphQL API Dokumentation
- NPM-Paket
- React-Paket
- Support
Hilfe erhalten
Für technischen Support oder Fragen zur Integration wenden Sie sich an das Legalesign-Supportteam oder besuchen Sie die API-Dokumentation.