Integration des Dokumenten-Viewers
Der Document Viewer ist eine Webkomponente, mit der Nutzer Vorlagen bearbeiten und Dokumente zur Unterzeichnung vorbereiten können – direkt in Ihrer Anwendung. Diese Anleitung zeigt, wie man ihn mit der GraphQL-API verbindet, um einen vollständigen Signatur-Workflow zu erstellen.
Übersicht
Eine typische Integration umfasst diese Schritte:
- Authentifizieren — ein Token für den Viewer erhalten
- Eine Vorlage hochladen — über die GraphQL-API
- Den Viewer rendern — Vorlage-ID und Token übergeben
- Events erfassen — der Viewer sendet
updateundvalidateEvents während der Nutzer arbeitet - Das Dokument senden — die
sendMutation mit Empfänger- und Rollendaten aus dem Viewer aufrufen
Authentifizierung
Der Viewer benötigt ein gültiges Token, das als token-Attribut übergeben wird. Ihr Backend stellt ein kurzlebiges Komponenten-Token über generateComponentToken bereit. Siehe Widget Authorization, bevor Sie den Viewer in Ihre Anwendung integrieren.
Compose-Modus — Ein vorgefertigtes Dokument senden
Der Compose-Modus ist für Workflows gedacht, bei denen Ihr System die Empfänger bereits kennt. Der Nutzer platziert lediglich die Signaturfelder und sendet.
1. Den Viewer rendern
<ls-document-viewer
id="viewer"
templateid="dHBsYjQ5YTg5NWQtYWRhMy0xMWYwLWIxZGMtMDY5NzZlZmU0MzIx"
token="YOUR_ACCESS_TOKEN"
mode="compose"
recipients='[
{"email": "jane@example.com", "firstname": "Jane", "lastname": "Smith", "signerIndex": 1},
{"email": "john@example.com", "firstname": "John", "lastname": "Doe", "signerIndex": 2}
]'
filtertoolbox="signature|initials|date|text"
>
<span slot="right-button">
<button id="send-btn" disabled>Send</button>
</span>
</ls-document-viewer>
2. Validierung und Rollen-IDs verfolgen
Während der Nutzer Felder hinzufügt, sendet der Viewer Events. Für diese Events benötigen Sie zwei Dinge:
validate— zeigt an, ob die Vorlage alle notwendigen Felder enthält (mindestens eine Signatur pro Empfänger)update— liefert den aktuellen Vorlagenstatus, inklusiveroleIdfür jeden Teilnehmer, wenn die Rollenzuordnung benötigt wird
const viewer = document.getElementById('viewer');
const sendBtn = document.getElementById('send-btn');
let isValid = false;
const recipientRoles = {};
viewer.addEventListener('validate', (e) => {
isValid = e.detail.valid;
sendBtn.disabled = !isValid;
});
viewer.addEventListener('update', (e) => {
const roles = e.detail.template.roles;
roles.forEach((role) => {
recipientRoles[role.signerIndex] = role.id;
});
});
Die roleId aus dem update Event ordnet jedem Empfänger seine Felder in der Vorlage zu. Nehmen Sie diese auf, wenn Ihr Sendevorgang diese Zuordnung benötigt.
3. Das Dokument senden
Wenn der Nutzer auf Senden klickt, rufen Sie die send Mutation mit den Empfängerdaten und den aus dem Viewer erfassten Rollen-IDs auf:
sendBtn.addEventListener('click', async () => {
const token = '<token-from-authentication-guide>';
const recipients = [
{
firstName: 'Jane',
lastName: 'Smith',
email: 'jane@example.com',
role: 'Signer',
roleId: recipientRoles[1],
signerIndex: 1,
order: 1,
},
{
firstName: 'John',
lastName: 'Doe',
email: 'john@example.com',
role: 'Signer',
roleId: recipientRoles[2],
signerIndex: 2,
order: 2,
},
];
const response = await fetch('https://graphql.uk.legalesign.com/graphql', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
Authorization: `Bearer ${token}`,
},
body: JSON.stringify({
query: `mutation SendDocument {
send(input: {
groupId: "YOUR_GROUP_ID"
templateId: "dHBsYjQ5YTg5NWQtYWRhMy0xMWYwLWIxZGMtMDY5NzZlZmU0MzIx"
title: "Contract - Jane Smith & John Doe"
recipients: ${JSON.stringify(recipients).replace(/"(\w+)":/g, '$1:')}
sequentialSigning: true
})
}`,
}),
});
const result = await response.json();
const taskId = result.data.send;
// Poll for completion
console.log('Task started:', taskId);
});
Die send Mutation gibt eine Task-ID zurück. Polling Sie die task Abfrage und überwachen Sie den Status task.report.status, bis dieser COMPLETED oder FAILED erreicht, um die Fertigstellung der Dokumentenerstellung zu bestätigen.
Editor-Modus — Vorlagenerstellung
Der Editor-Modus bietet Nutzern die vollständige Bearbeitungserfahrung der Vorlage — Rollen hinzufügen, Felder platzieren, Optionen konfigurieren. Verwenden Sie diesen Modus, wenn Nutzer wiederverwendbare Vorlagen erstellen sollen.
<ls-document-viewer
id="editor"
templateid="dHBsYjQ5YTg5NWQtYWRhMy0xMWYwLWIxZGMtMDY5NzZlZmU0MzIx"
token="YOUR_ACCESS_TOKEN"
mode="editor"
></ls-document-viewer>
Im Editor-Modus wird das update Event bei jeder Änderung der Vorlage ausgelöst. Sie können dies nutzen, um den Vorlagenstatus zu verfolgen oder eine Speicheranzeige einzublenden:
const editor = document.getElementById('editor');
editor.addEventListener('update', (e) => {
console.log('Template updated:', e.detail);
});
editor.addEventListener('validate', (e) => {
console.log('Template valid:', e.detail.valid);
});
Vorlagenänderungen werden automatisch vom Viewer gespeichert — Sie müssen keine GraphQL-Mutation aufrufen, um Änderungen zu sichern.
React-Integration
Die React-Hülle bietet dieselbe Funktionalität mit React-typischer Ereignisbehandlung:
import { useState } from 'react';
import { LsDocumentViewer } from 'legalesign-document-viewer-react';
const DocumentCompose = ({ templateId, recipients, token }) => {
const [isValid, setIsValid] = useState(false);
const [roleMap, setRoleMap] = useState({});
const handleValidate = (e) => {
setIsValid(e.detail.valid);
};
const handleUpdate = (e) => {
const roles = e.detail.template.roles;
const map = {};
roles.forEach((role) => {
map[role.signerIndex] = role.id;
});
setRoleMap(map);
};
const handleSend = async () => {
const mappedRecipients = recipients.map((r, i) => ({
...r,
roleId: roleMap[r.signerIndex],
order: i + 1,
}));
const response = await fetch('https://graphql.uk.legalesign.com/graphql', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
Authorization: `Bearer ${token}`,
},
body: JSON.stringify({
query: `mutation SendDocument {
send(input: {
groupId: "YOUR_GROUP_ID"
templateId: "${templateId}"
title: "Document"
recipients: ${JSON.stringify(mappedRecipients).replace(/"(\w+)":/g, '$1:')}
})
}`,
}),
});
const result = await response.json();
console.log('Task ID:', result.data.send);
};
if (!token) return null;
return (
<LsDocumentViewer
templateid={templateId}
token={token}
mode="compose"
recipients={JSON.stringify(recipients)}
onValidate={handleValidate}
onUpdate={handleUpdate}
>
<div slot="right-button">
<button onClick={handleSend} disabled={!isValid}>
Send
</button>
</div>
</LsDocumentViewer>
);
};
Zeugen
Um einen Zeugen für einen Unterzeichner hinzuzufügen, setzen Sie roleType: "WITNESS" und verwenden Sie einen signerIndex, der dem Index des übergeordneten Unterzeichners + 100 entspricht. Beispielsweise hat ein Zeuge für Unterzeichner 2 den signerIndex: 102:
<ls-document-viewer
mode="compose"
recipients='[
{"email": "signer@example.com", "firstname": "Alice", "lastname": "Jones", "signerIndex": 1},
{"email": "signer2@example.com", "firstname": "Bob", "lastname": "Brown", "signerIndex": 2},
{"email": "witness@example.com", "firstname": "Carol", "lastname": "White", "signerIndex": 102, "roleType": "WITNESS"}
]'
...
></ls-document-viewer>
Schlüsselbegriffe
| Viewer-Konzept | GraphQL-Typ | Beschreibung |
|---|---|---|
templateid Attribut | Template | Die bearbeitete oder zusammengesetzte Vorlage |
recipients Attribut | RecipientInput | Empfänger, die im Compose-Modus übergeben werden |
roleId aus update Event | Role | Verknüpft einen Empfänger mit seinen Feldern in der Vorlage |
validate Event | — | Ob die Vorlage alle erforderlichen Felder enthält |
send Mutation | send | Sendet das Dokument nach der Komposition |
token Attribut | — | Token aus der Authentifizierung |
mode="compose" | — | Vereinfachter Modus für das Platzieren von Feldern und Senden |
mode="editor" | — | Vollständiger Bearbeitungsmodus für Vorlagen |
experience im Send-Input | Experience | Steuert Branding, E-Mails und Signierseite — siehe Erklärung der Experiences |
Verwandte Inhalte
- Dokumenten-Viewer Referenz — vollständige Attribut- und Event-Referenz
- send Mutation — ein Dokument senden
- DocumentSendSettingsInput — vollständige Struktur des Send-Inputs
- Erläuterung der Versandmethoden — send vs sendBatch vs sendBulk
- Eine Datei als Vorlage hochladen — Vorlagen per API hochladen
- Authentifizierung — Authentifizierungsmodus wählen