Vai al contenuto principale

Integra il Visualizzatore Documenti Legalesign nel Tuo Sito Web

suggerimento

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

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

Questo componente plug and play è progettato per integrare le parti chiave della creazione di documenti nei tuoi sistemi interni, come un CRM o un'applicazione aziendale. Finché il tuo sistema può renderizzare e supportare componenti HTML, puoi utilizzare il Visualizzatore Documenti. Se hai bisogno di ulteriore assistenza per integrare il Visualizzatore Documenti nel tuo stack tecnico, contatta il nostro supporto. Puoi utilizzare questi widget più ampi con integrazioni API REST/GraphQL per fornire processi di firma documentale senza interruzioni per il tuo personale 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 utilizzata con qualsiasi stack di sviluppo, come PHP, ASP .Net ecc. Puoi collegarti direttamente al componente da npm se il tuo ambiente non permette l’installazione. Puoi provare una pagina dimostrativa dal repository degli esempi qui [https://github.com/legalesign/ls-viewer-demo].

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 usare codice lato server per ottenere YOUR_AUTH_TOKEN. Il token può essere un JWT SRP o un token componente a breve scadenza generato con generateComponentToken. Consulta Autorizzazione Widget.

Integrazione React​

Abbiamo anche generato una versione del componente che si integra direttamente con 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 modello. Usa codice lato server per fornire un JWT SRP o un token componente a breve termine. Vedi Autorizzazione Widget per il flusso di token sicuro.

token="eyJraWQiOiJBTkJIeT..."

templateid​

L'ID API del modello che vuoi presentare agli utenti. Puoi trovarlo facilmente guardando l’URL mentre modifichi il modello nell'applicazione Console.

templateid="dHBsYjQ5YTg5NWQtYWRhMy0xMWYwLWIxZGMtMDY5NzZlZmU0MzIx"

Modalità Widget​

Modalità Editor​

Creazione e modifica del modello con tutte le funzionalità disponibili. È pensata per flussi di lavoro in cui un modello altamente riutilizzabile con ruoli è utile. Se intendi usare il documento solo una volta (forse il tuo sistema di generazione documenti ha già inserito tutte le informazioni del cliente), potresti considerare invece la modalità compose.

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

Modalità Compose​

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

Il flusso tipico è:

  1. La tua applicazione genera un PDF
  2. Lo carica via API per creare un modello:
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 modello
  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 Destinatari.

<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 destinatari pre-generati
  • Nasconde il mittente dal menu a discesa
  • Nasconde le opzioni documento
  • Mostra campi obbligatori di default
  • Rimuove mittente e campi mittente dall’editor
  • Favorisce la selezione rapida dei campi richiesti per ogni destinatario

Modalità Anteprima​

Un’utile anteprima del documento che mostra il documento con tutti i campi correnti 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 cassetta degli attrezzi (toolbox)
  • Rende partecipanti e campi in sola lettura

Configurazione Avanzata​

Filtro Toolbox​

Limita i tipi di campo disponibili usando valori separati da pipe. Se non viene fornito nessun valore, si assume che la toolbox non abbia filtri 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 anche passare role e phonenumber per ciascun destinatario. Omettere un ruolo significa che il destinatario sarà trattato come firmatario distinto; per modificare questo puoi passare role: "WITNESS" e includere un indice firmatario speciale per indicare quale è il loro genitore, quindi per esempio se vuoi includere un testimone per il firmatario 2, quel testimone avrà 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 usando 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 Eventi​

Ascolta gli eventi del componente per tracciare le modifiche:

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

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

Puoi tracciare se un modello è 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 di Gestione Eventi in React​

Usare un evento in React lo prefissa con il familiare on<EventName>.

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

Tipi di Eventi​

Evento update​

Scatenato quando il modello del documento viene modificato, come aggiunta o rimozione di campi. Fornisce non solo l’evento che lo ha causato ma anche lo stato aggiornato dell’oggetto modello in JSON.

Evento validate​

Scatenato quando il modello del documento viene modificato, la proprietà valid nel dettaglio mostra se il modello è diventato valido o non valido.

Evento selectFields​

Scatenato quando un campo viene selezionato nell’editor.

Evento addParticipant​

Scatenato quando un ruolo partecipante viene aggiunto al modello.

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 Problemi

Se riscontri problemi con il componente, assicurati che:

Supporto Browser​

Il componente usa standard web moderni e supporta:

  • Chrome/Edge (ultima versione)
  • Firefox (ultima versione)
  • Safari (ultima versione)
  • 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.