Vai al contenuto principale

Integra il Visualizzatore di Documenti Legalesign nel Tuo Sito Web

suggerimento

Puoi vedere questo componente in azione come Quick Send in Console.

Il Visualizzatore di Documenti Legalesign è un componente web indipendente dalla piattaforma che ti permette di modificare, visualizzare in anteprima e personalizzare template per la firma dei documenti. Costruito con StencilJS, funziona perfettamente con JavaScript vanilla, React, Vue, Angular o qualsiasi framework web.

Questo componente plug and play è progettato in modo che tu possa integrare parti chiave della creazione dei documenti nei tuoi sistemi interni, come un CRM o un'applicazione di business. Finché il tuo sistema può renderizzare e supportare componenti HTML, puoi utilizzare il Visualizzatore di Documenti. Se hai bisogno di ulteriore aiuto per integrare il Visualizzatore di Documenti nel tuo stack tecnico, ti preghiamo di contattare il nostro servizio di supporto. Puoi usare questi widget più grandi con integrazioni API REST/GraphQL per fornire processi di firma documenti senza interruzioni per il tuo staff e i tuoi clienti.

Installazione​

Installazione NPM​

npm install legalesign-document-viewer

Per Progetti React​

npm install legalesign-document-viewer-react

Integrazione Base​

HTML/JavaScript Vanilla​

La versione HTML/JavaScript di questo componente può essere usata con qualsiasi stack di sviluppo, come PHP, ASP .Net ecc. Puoi collegarti direttamente al componente da npm se il tuo ambiente non permette di installarlo. Puoi provare una pagina di dimostrazione dal repository degli esempi qui [https://github.com/legalesign/ls-document-viewer-example].

Aggiungi gli script del componente al tuo HTML:

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

Dovrai utilizzare codice lato server per ottenere il token per l'account che vuoi usare.

Integrazione React​

Abbiamo anche generato una versione del componente che si integra direttamente con i framework React.

import { LsDocumentViewer } from 'legalesign-document-viewer-react';

function App() {
  return (
    <LsDocumentViewer
      templateid="YOUR_TEMPLATE_ID"
      token="YOUR_AUTH_TOKEN"
      mode="compose"
    />
  );
}

Attributi Richiesti​

token​

Il tuo token di sicurezza per l'autenticazione. Questo verifica la tua identità e l'accesso al template. Per maggiori informazioni su come ottenere in modo sicuro un token senza esporre le tue credenziali, consulta gli esempi nella guida all'autenticazione

token="eyJraWQiOiJBTkJIeT..."

templateid​

L'ID API del template che vuoi presentare agli utenti. Puoi facilmente trovarlo guardando l'URL quando stai modificando il template nell'applicazione Console.

templateid="dHBsYjQ5YTg5NWQtYWRhMy0xMWYwLWIxZGMtMDY5NzZlZmU0MzIx"

Modalità del Widget​

Modalità Editor​

Creazione e modifica completa del template con tutti gli strumenti disponibili. Questo è pensato per flussi di lavoro in cui un template altamente riusabile con ruoli è utile. Se l'intenzione è usare il documento una sola volta (forse il tuo sistema di generazione dei documenti ha già inserito tutte le informazioni del cliente) allora potresti voler considerare invece la modalità compose.

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

Modalità Compose​

Modalità semplificata per aggiungere rapidamente campi firma a template pre-generati. Ideale per clienti integrati dove i destinatari sono già definiti.

Il flusso di lavoro tipico è:

  1. La tua applicazione genera un PDF
  2. Lo carichi tramite API per creare un template:
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. Carica il file PDF su S3 usando l'ID del template
  2. Incorpora il visualizzatore in modalità compose con i dettagli dei destinatari
  3. Il tuo utente aggiunge i campi firma e invia

Per maggiori informazioni sui destinatari vedi 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>

La modalità compose automaticamente:

  • Rileva i destinatari pre-generati
  • Nasconde il mittente dal menu a discesa
  • Nasconde le opzioni del documento
  • Mostra di default i campi obbligatori
  • Rimuove il mittente e i campi mittente dall'editor
  • Favorisce la selezione rapida dei campi obbligatori per ogni destinatario

Modalità Anteprima​

Una comoda anteprima del documento che mostra il documento con tutti i campi attuali e permette all'utente di sfogliare le pagine.

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

La modalità compose automaticamente:

  • Nasconde la barra degli strumenti
  • Nasconde le opzioni del documento
  • Nasconde la toolbox
  • Rende partecipanti e campi di sola lettura

Configurazione Avanzata​

Filtro Toolbox​

Restringe i tipi di campo disponibili usando valori separati da pipe. Se non viene fornito alcun valore, si assume che la toolbox non sia filtrata e tutte le opzioni siano disponibili.

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

endpoint​

Il tuo endpoint API GraphQL, se ti è stato fornito un endpoint specifico per il cliente.

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

Destinatari​

Definisci i destinatari del documento in formato JSON. Nota che gli elementi richiesti per un destinatario sono firstname, lastname, email e signerIndex; opzionalmente puoi inoltre passare il ruolo e il phonenumber per ciascun destinatario. Omettere un ruolo significa che il destinatario sarà trattato come un firmatario distinto; per cambiare questo puoi passare role: "WITNESS" e includere un indice firmatario speciale per indicare quale è il suo genitore, quindi per esempio se volessi includere un testimone per il firmatario 2, quel testimone avrebbe un signerIndex di 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>

Pulsanti Personalizzati con Slot​

Aggiungi pulsanti personalizzati alla barra degli strumenti utilizzando gli slot:

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

Gestione degli Eventi​

Ascolta gli eventi del componente per tracciare i cambiamenti:

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

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

Puoi tracciare se un template è diventato valido o non valido usando l'evento validate.

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

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

Esempio Gestione Eventi in React​

Usando un evento in React si antepone il prefisso familiare on<EventName>.

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

Tipi di Eventi​

Evento update​

Viene attivato quando il template del documento viene modificato, come l'aggiunta o rimozione di campi. Fornisce non solo l'evento che lo ha causato ma anche lo stato aggiornato dell'oggetto template in formato JSON.

Evento validate​

Viene attivato quando il template del documento viene modificato, la proprietà valid nei dettagli mostra se il template è diventato valido o non valido.

Evento selectFields​

Viene attivato quando un campo viene selezionato nell'editor.

Evento addParticipant​

Viene attivato quando un ruolo partecipante viene aggiunto al template.

Esempio Completo​

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

Risoluzione dei Problemi

Se incontri problemi con il componente, assicurati che:

Supporto Browser​

Il componente utilizza standard web moderni e supporta:

  • Chrome/Edge (ultime versioni)
  • Firefox (ultime versioni)
  • Safari (ultime versioni)
  • Browser mobili (iOS Safari, Chrome Mobile)

Risorse​

Ottenere Aiuto​

Per supporto tecnico o domande sull'integrazione, contatta il team di supporto Legalesign o visita la documentazione API.

Export This Article

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