Integrieren Sie den Legalesign Dokumenten-Viewer in Ihre Website

Tipp

Sie können diese Komponente in Aktion als Quick Send in der Console sehen.

Der Legalesign Dokumenten-Viewer ist eine plattformunabhängige Webkomponente, die es Ihnen ermöglicht, Vorlagen für das Dokumenten-Signing zu bearbeiten, vorzuschauen und anzupassen. Er funktioniert nahtlos in HTML mit JavaScript, React, Vue, Angular oder jedem Web-Framework.

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 Dokumenten-Viewer verwenden.

Wenn Sie zusätzliche Hilfe bei der Integration des Dokumenten-Viewers in Ihren technischen Stack benötigen, wenden Sie sich bitte an unseren Support-Desk.

Sie können diese größeren Widgets mit REST/GraphQL API-Integrationen verwenden, um nahtlose Dokumenten-Signing-Prozesse für Ihre Mitarbeiter und Kunden bereitzustellen.

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

Grundintegration

HTML/JavaScript

Die HTML/Javascript-Version dieser Komponente kann mit jedem Entwicklungsstack verwendet werden, z.B. PHP, ASP .Net etc. Sie können die Komponente direkt von npm einbinden, wenn Ihre Umgebung keine Installation zulässt. Eine Demoseite finden Sie im Beispiel-Repository 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 drei Optionen:

SRP JWT direkt — Wenn Ihr Backend bereits SRP-Authentifizierung nutzt, übergeben Sie das JWT Access Token direkt an das Widget.
GraphQL generateComponentToken — Rufen Sie die Mutation mit Ihrem API-Schlüssel oder SRP JWT auf, um ein kurzlebiges, eingeschränktes Komponententoken auszugeben.
REST API — Rufen Sie GET /templatepdf/{pdfId}/component-token/ mit Ihrem API-Schlüssel auf.

Option 2 (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 3 (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 (oder Ihr SRP JWT) an das Widget. Details zu den Token-Optionen finden Sie unter Widget Authorization.

React-Integration

Wir haben außerdem eine Version der Komponente erstellt, die direkt mit React-Frameworks integriert.

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. Dies kann entweder ein SRP JWT Access Token oder ein kurzlebiges Komponententoken von generateComponentToken sein. Informationen zum sicheren Token-Flow finden Sie unter Widget Authorization.

token="eyJraWQiOiJBTkJIeT..."

templateid

Die API-ID der Vorlage, die Sie den Benutzern präsentieren möchten. Sie finden diese in der URL, wenn Sie die Vorlage in der Web-App bearbeiten.

templateid="dHBsYjQ5YTg5NWQtYWRhMy0xMWYwLWIxZGMtMDY5NzZlZmU0MzIx"

Editor-Modus

Voll ausgestattete Erstellung und Bearbeitung von Vorlagen mit allen verfügbaren Werkzeugen. Dieser Modus ist für Workflows gedacht, bei denen eine hoch wiederverwendbare Vorlage mit Rollen hilfreich ist. Wenn Sie Ihr Dokument nur einmal verwenden möchten (vielleicht hat Ihr Dokumentengenerierungssystem bereits alle Kundendaten eingefügt), 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 zur Optimierung der Benutzererfahrung. In der Legalesign Web App ist dies die Funktion "Quick send".

Fügen Sie Ihre Empfänger zum Attribut 'recipient' hinzu, und Ihr Benutzer kann schnell Signaturen und Formularfelder platzieren, bevor er das Dokument sendet. Ideal für integrierte Kunden, bei denen die Empfänger bereits definiert sind.

Der typische Workflow ist: Klonen oder Hochladen eines PDFs, dann Einbetten des Viewers, wo der Benutzer Unterschriften- und Formularfelder ergänzen kann, und schließlich Anbieten eines Buttons zum Senden des Dokuments.

Klonen

Klonen Sie eine existierende Vorlage mittels 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 sie dann zur bereitgestellten uploadUrl hoch. Verwenden Sie den Titel [deleted], wenn Sie das PDF nicht in Ihrer Bibliothek behalten möchten. Es wird innerhalb der nächsten 24 Stunden gelöscht. Ansonsten verwenden Sie einen beliebigen Titel Ihrer Wahl:

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 an die uploadUrl hoch. Der Content-Typ muss application/pdf sein.

Viewer einbetten

Das Hauptattribut ist 'recipients'. Für weitere Details zu Zustimmern oder Zeugen benötigen Sie zusätzliche Angaben – 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 vor-generierter Empfänger
Verstecken des Absenders im Dropdown
Ausblenden der Dokumentoptionen
Anzeigen der Pflichtfelder standardmäßig
Entfernen von Absender und Absenderfeldern aus dem Editor
Förderung der schnellen Auswahl der Pflichtfelder 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 Werkzeugleiste
Verstecken der Dokumentoptionen
Verstecken der Werkzeugkiste
Setzt Teilnehmer und Felder auf Nur-Lesen

Erweiterte Konfiguration

Werkzeugkasten filtern

Beschränken Sie verfügbare Feldtypen mittels mit Pipe getrennten Werten. Wenn kein Wert angegeben wird, wird angenommen, dass der Werkzeugkasten ungefiltert 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`	Freitextfeld
`signing date`	Datum, automatisch beim Signieren ausgefüllt (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`	Gezeichnetes/Freihand-Feld (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 Rolle und Telefonnummer für jeden Empfänger übergeben. Wird keine Rolle angegeben, wird der Empfänger als Unterzeichner behandelt.

Sie können die Rolle "WITNESS" oder "APPROVER" verwenden. Für die Rolle "WITNESS" addieren Sie 100 zum signerIndex des entsprechenden Unterzeichners. Zum Beispiel, wenn Sie für Unterzeichner 2 (signerIndex: 2) einen Zeugen benötigen, setzen Sie den WITNESS signerIndex auf 102.

<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 Buttons mit Slots

Fügen Sie der Werkzeugleiste benutzerdefinierte Buttons mittels 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>

Ereignisbehandlung

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-Ereignis verwenden.

const editor = document.querySelector('ls-document-viewer');

editor.addEventListener('validate', (event) => {
  console.log('Template validation changed:', event.detail.valid);
});

Beispiel für Ereignisbehandlung in React

Eine Event-Nutzung in React wird mit dem bekannten Präfix on<EventName> versehen.

<LsDocumentViewer
  onUpdate={(event) => {
    console.log('Template changed:', event.detail);
  }}
  ...
/>

Ereignistypen

`update`-Ereignis

Wird ausgelöst, wenn die Dokumentvorlage geändert wird, z.B. durch Hinzufügen oder Entfernen von Feldern. Liefert nicht nur das Ereignis, das die Änderung verursacht hat, sondern auch den aktualisierten Zustand des Vorlagenobjekts als JSON.

`validate`-Ereignis

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`-Ereignis

Wird ausgelöst, wenn ein Feld im Editor ausgewählt wird.

`addParticipant`-Ereignis

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>

Sie können die GraphQL send-Mutation clientseitig verwenden, wenn Sie das SRP JWT Token nutzen, andernfalls serverseitig mit Ihrem API-Schlüssel entweder über die GraphQL- oder REST-Schnittstelle.

Send mutation — einzelnes Dokument senden
Send Input Schema — vollständige Eingabereferenz
REST Send – REST-Sendung-Dokument-Referenz

Fehlerbehebung

Wenn Sie Probleme mit der Komponente feststellen, stellen Sie sicher, dass:

Sie Zugriff auf die Domain des Dokumentenspeichers haben oder diese unter https://s3.amazonaws.com/* auf der Whitelist steht

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)

Ressourcen

GraphQL Integrationsanleitung — wie man den Viewer an die GraphQL API zum Senden anschließt
GraphQL API Dokumentation
NPM Paket
React Paket
Support

Hilfe erhalten

Für technischen Support oder Fragen zur Integration kontaktieren Sie das Legalesign-Support-Team oder besuchen Sie die API-Dokumentation.

Integrieren Sie den Legalesign Dokumenten-Viewer in Ihre Website

Installation

NPM Installation

Für React-Projekte

Grundintegration

HTML/JavaScript

Authentifizierung – Erhalten Sie ein Token

React-Integration

Erforderliche Attribute

token

templateid

Widget-Modi

Editor-Modus

Compose-Modus

Klonen

Oder Hochladen

Viewer einbetten

Vorschau-Modus

Erweiterte Konfiguration

Werkzeugkasten filtern

Empfänger

Benutzerdefinierte Buttons mit Slots

Ereignisbehandlung

Beispiel für Ereignisbehandlung in React

Ereignistypen

`update`-Ereignis

`validate`-Ereignis

`selectFields`-Ereignis

`addParticipant`-Ereignis

Komplettes Beispiel

Fehlerbehebung

Browser-Unterstützung

Ressourcen

Hilfe erhalten

Export This Article

Installation​

NPM Installation​

Für React-Projekte​

Grundintegration​

HTML/JavaScript​

Authentifizierung – Erhalten Sie ein Token​

React-Integration​

Erforderliche Attribute​

token​

templateid​

Widget-Modi​

Editor-Modus​

Compose-Modus​

Klonen​

Oder Hochladen​

Viewer einbetten​

Vorschau-Modus​

Erweiterte Konfiguration​

Werkzeugkasten filtern​

Empfänger​

Benutzerdefinierte Buttons mit Slots​

Ereignisbehandlung​

Beispiel für Ereignisbehandlung in React​

Ereignistypen​

update-Ereignis​

validate-Ereignis​

selectFields-Ereignis​

addParticipant-Ereignis​

Komplettes Beispiel​

Fehlerbehebung

Browser-Unterstützung​

Ressourcen​

Hilfe erhalten​

Export This Article

Installation

NPM Installation

Für React-Projekte

Grundintegration

HTML/JavaScript

Authentifizierung – Erhalten Sie ein Token

React-Integration

Erforderliche Attribute

token

templateid

Widget-Modi

Editor-Modus

Compose-Modus

Klonen

Oder Hochladen

Viewer einbetten

Vorschau-Modus

Erweiterte Konfiguration

Werkzeugkasten filtern

Empfänger

Benutzerdefinierte Buttons mit Slots

Ereignisbehandlung

Beispiel für Ereignisbehandlung in React

Ereignistypen

`update`-Ereignis

`validate`-Ereignis

`selectFields`-Ereignis

`addParticipant`-Ereignis

Komplettes Beispiel

Browser-Unterstützung

Ressourcen

Hilfe erhalten