Zum Hauptinhalt springen

Integrieren Sie den Legalesign-Dokumentbetrachter in Ihre Webseite

Tipp

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

Der Legalesign-Dokumentbetrachter ist eine plattformunabhängige Webkomponente, die es Ihnen ermöglicht, Vorlagen für die Dokumentenunterzeichnung zu bearbeiten, vorzuschauen und anzupassen. Er wurde mit StencilJS entwickelt und funktioniert nahtlos mit reinem JavaScript, React, Vue, Angular oder jedem anderen Web-Framework.

Diese Plug-and-Play-Komponente ist so konzipiert, dass Sie wichtige Teile der Dokumentenerstellung in Ihre internen Systeme integrieren können, wie beispielsweise in ein CRM- oder Geschäftsanwendungssystem. Solange Ihr System HTML-Komponenten rendern und unterstützen kann, können Sie den Dokumentbetrachter verwenden. Wenn Sie zusätzliche Hilfe bei der Integration des Dokumentbetrachters in Ihr technisches 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 Dokumentunterzeichnungsprozesse für Ihre Mitarbeiter und Kunden zu ermöglichen.

Installation​

NPM Installation​

npm install legalesign-document-viewer

Für React-Projekte​

npm install legalesign-document-viewer-react

Basisintegration​

Vanilles HTML/JavaScript​

Die HTML/JavaScript-Version dieser Komponente kann mit jedem Entwicklungs-Stack verwendet werden, wie zum Beispiel PHP, ASP .Net etc. Sie können direkt von npm auf die Komponente verlinken, falls Ihre Umgebung eine Installation nicht zulässt. Eine Demo-Seite aus dem Beispiel-Repository können Sie hier ausprobieren: [https://github.com/legalesign/ls-viewer-demo].

Fügen Sie die Komponentenskripte in Ihr HTML ein:

<!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>

Für YOUR_AUTH_TOKEN müssen Sie serverseitigen Code verwenden. Das Token kann ein SRP JWT oder ein kurzlebiges Komponenten-Token sein, das mit generateComponentToken erstellt wurde. Siehe Widget-Autorisierung.

React-Integration​

Wir haben auch eine Version der Komponente erstellt, die direkt mit React-Frameworks integriert werden kann.

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 für die Authentifizierung. Dieses verifiziert Ihre Identität und den Zugriff auf die Vorlage. Verwenden Sie serverseitigen Code, um entweder ein SRP JWT oder ein kurzlebiges Komponenten-Token bereitzustellen. Siehe Widget-Autorisierung für den sicheren Token-Flow.

token="eyJraWQiOiJBTkJIeT..."

templateid​

Die API-ID der Vorlage, die Sie den Benutzern präsentieren möchten. Diese finden Sie leicht, indem Sie in der URL nachsehen, während Sie die Vorlage in der Console-Anwendung bearbeiten.

templateid="dHBsYjQ5YTg5NWQtYWRhMy0xMWYwLWIxZGMtMDY5NzZlZmU0MzIx"

Widget-Modi​

Editor-Modus​

Voll ausgestattete Vorlagenerstellung und -bearbeitung mit allen verfügbaren Werkzeugen. Dies ist gedacht für Arbeitsabläufe, bei denen eine stark wiederverwendbare Vorlage mit Rollen hilfreich ist. Wenn Sie Ihr Dokument nur einmal verwenden möchten (vielleicht hat Ihr Dokumentengenerierungssystem bereits alle Kundendaten ausgefüllt), sollten Sie stattdessen den compose-Modus in Betracht ziehen.

<ls-document-viewer mode="editor" ...></ls-document-viewer>

Compose-Modus​

Ein schlanker Modus zum schnellen Hinzufügen von Signaturfeldern zu vorab generierten Vorlagen. Ideal für integrierte Kunden, bei denen die Empfänger bereits definiert sind.

Der typische Arbeitsablauf ist:

  1. Ihre Anwendung erzeugt ein PDF
  2. Laden Sie es über die API hoch, um eine Vorlage zu erstellen:
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: "${groupId}"
          title: "${documentTitle}"
        })
      }
    `
  })
});
const { data } = await response.json();
const templateId = data.createTemplate;
  1. Laden Sie die PDF-Datei mit der Vorlage-ID in S3 hoch
  2. Betten Sie den Viewer im Compose-Modus mit Empfängerdetails ein
  3. Ihr Benutzer fügt Signaturfelder hinzu und sendet

Weitere Informationen zu Empfängern 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 erledigt automatisch:

  • Erkennt vorab generierte Empfänger
  • Versteckt den Absender im Dropdown
  • Versteckt Dokumentoptionen
  • Zeigt erforderliche Felder standardmäßig an
  • Entfernt den Absender und Absenderfelder aus dem Editor
  • Ermöglicht eine schnelle Auswahl der erforderlichen Felder für jeden Empfänger

Vorschau-Modus​

Eine hilfreiche Dokumentenvorschau, die das Dokument mit allen aktuellen Feldern zeigt und es dem Benutzer erlaubt, durch Seiten zu blättern.

<ls-document-viewer mode="preview" ...></ls-document-viewer>

Der Compose-Modus erledigt automatisch:

  • Versteckt die Symbolleiste
  • Versteckt Dokumentoptionen
  • Versteckt die Werkzeugleiste
  • Macht Teilnehmer und Felder schreibgeschützt

Erweiterte Konfiguration​

Toolbox filtern​

Beschränken Sie verfügbare Feldtypen mit durch Pipes getrennten Werten. Wenn kein Wert angegeben ist, wird angenommen, dass die Toolbox ungefiltert und alle Optionen verfügbar sind.

<ls-document-viewer
  filtertoolbox="signature|initials|date|text"
  ...
></ls-document-viewer>

endpoint​

Ihr GraphQL-API-Endpunkt, falls Ihnen ein client-spezifischer Endpunkt gegeben wurde.

endpoint="https://your-api.appsync-api.region.amazonaws.com/graphql"

Empfänger​

Definieren Sie Dokumentempfänger im JSON-Format. Beachten Sie, dass die erforderlichen Elemente für einen Empfänger firstname, lastname, email und signerIndex sind; optional können Sie auch role und phonenumber für jeden Empfänger übergeben. Wird keine Rolle angegeben, wird der Empfänger als eigenständiger Unterzeichner behandelt. Um dies zu ändern, können Sie role: "WITNESS" angeben und einen speziellen signerIndex aufnehmen, der zeigt, wer der übergeordnete Unterzeichner ist. Zum Beispiel erhält ein Zeuge für Unterzeichner 2 einen signerIndex von 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 Symbolleiste benutzerdefinierte Buttons mit Slots hinzu:

<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 Komponentenereignisse, 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, mithilfe des validate-Ereignisses.

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​

Die Verwendung eines Ereignisses in react wird mit dem vertrauten 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 es 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>

Fehlerbehebung

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

Browser-Unterstützung​

Die Komponente verwendet moderne Webstandards und unterstützt:

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

Ressourcen​

Hilfe erhalten​

Für technischen Support oder Integrationsfragen wenden Sie sich an das Legalesign-Supportteam oder besuchen Sie die API-Dokumentation.

Export This Article

Save a copy of this page as PDF or plain text.