Integreiddio Legalesign Signer i Eich Gwefan

Galluogi i’ch tîm

Mae’r cydran Signer angen ei hactifadu. Cysylltwch â chymorth i’w alluogi i’ch tîm.

Mae Legalesign Signer yn gydran gwe annibynnol ar lwyfannau sy’n darparu profiad llofnodi dogfen llawn a di-dor o fewn eich ap eich hun. Mae’n gweithio gyda HTML vanilla, React, Vue, Angular, neu unrhyw fframwaith gwe.

Mewnosoder y gydran hon ble bynnag y mae eich defnyddwyr angen llofnodi dogfennau — o fewn CRM, porth cleient, neu unrhyw ap mewnol sy’n rendro HTML.

Gosod

Llwythwch yn uniongyrchol o’r CDN (dim gosod yn ofynnol):

<script type="module" src="https://cdn.legalesign.io/signer/latest/ls-signer.esm.js"></script>

Gosod React

Gosodwch drwy reolwr pecynnau:

npm install legalesign-signer
# or
pnpm add legalesign-signer

Integreiddio Sylfaenol

HTML a JavaScript

<ls-signer
  recipient-id="abc123"
  private-key="key"
  session-id="session"
></ls-signer>

<script>
  const signer = document.querySelector('ls-signer');
  signer.addEventListener('signingSuccess', (e) => console.log('Signed:', e.detail.eventType, e.detail.documentId));
  signer.addEventListener('signingFail', (e) => console.error('Failed:', e.detail.failureReason, e.detail.error));
  signer.addEventListener('fieldChange', (e) => console.log('Field event:', e.detail.eventType));
</script>

React

import { useEffect, useState } from 'react';
import { LsSigner } from 'legalesign-signer/react';
import 'legalesign-signer/react.css';

function SigningPage() {
  const [signerData, setSignerData] = useState(null);

  useEffect(() => {
    fetch('/your-backend/to-get-token')
      .then(res => res.json())
      .then(setSignerData);
  }, []);

  if (!signerData) return <p>Loading...</p>;

  return (
    <LsSigner
      recipientId={signerData.recipientId}
      privateKey={signerData.token}
      sessionId={signerData.sessionId}
      onSuccess={({ eventType, documentId }) => console.log(eventType, documentId)}
      onFail={({ eventType, failureReason, error }) => console.error(eventType, failureReason, error)}
      onChange={({ eventType, uuid, saved, field, document }) => console.log('Event:', eventType)}
    />
  );
}

Mae React angen react a react-dom (v18 neu v19) fel dibyniaethau cydymaith.

Vue

<template>
  <ls-signer
    ref="signer"
    :recipient-id="recipientId"
    :private-key="privateKey"
    :session-id="sessionId"
  />
</template>

<script setup>
import { ref, onMounted, onBeforeUnmount } from 'vue';

const signer = ref(null);

function handleSuccess(e) {
  console.log('Signed:', e.detail);
}
function handleFail(e) {
  console.error('Failed:', e.detail);
}

onMounted(() => {
  signer.value.addEventListener('signingSuccess', handleSuccess);
  signer.value.addEventListener('signingFail', handleFail);
});

onBeforeUnmount(() => {
  signer.value?.removeEventListener('signingSuccess', handleSuccess);
  signer.value?.removeEventListener('signingFail', handleFail);
});
</script>

cyngor

Os ydych yn defnyddio Vue gyda Vite, ychwanegwch isCustomElement: (tag) => tag.startsWith('ls-') i’ch ffurfwedd plugin Vue i gwtogi rhybuddion am elfennau anhysbys.

rhybudd

Mae Vue 3 yn gwneud enwau digwyddiadau ar elfennau arferol yn llydanrif (lowercase), felly ni fydd @signingSuccess yn gweithio. Defnyddiwch addEventListener ar y cyfeirnod elfen fel y dangosir uchod.

Nuxt 3

Wrappiwch <ls-signer> mewn <ClientOnly> i atal gwallau SSR. Ychwanegwch y ffurfweddiad elfen arferol yn nuxt.config.ts:

export default defineNuxtConfig({
  vue: {
    compilerOptions: {
      isCustomElement: (tag) => tag.startsWith('ls-'),
    },
  },
});

Dilysu

Mae’r gydran signer angen tocyn byrhoedlog o’ch cefn gwe. Mae dau opsiwn:

1. GraphQL generateComponentToken — Galwch gydag component: LS_SIGNER ac un o recipientId neu sessionId yn y cwmpas signer (darparwch un, nid y ddau).
2. REST API — Galwch GET /signer/{signerId}/component-token/ gyda’ch allwedd API.

Mae’r ddau yn dychwelyd y token a sessionId sydd eu hangen ar y gydran. Gweler Widget Authorization am llif llawn y tocyn ochr y gweinydd.

Opsiwn 1: GraphQL (Node.js)

Gan ddefnyddio recipientId (y mwyaf cyffredin — defnyddiwch pan wyddoch y derbynnydd ond heb sesiwn eto):

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 MintSignerToken($input: GenerateComponentTokenInput!) {
      generateComponentToken(input: $input) {
        token
        tokenType
        sessionId
        expiresIn
        expiresAt
      }
    }`,
    variables: {
      input: {
        component: 'LS_SIGNER',
        signer: { recipientId: '<recipient-id>' }
      }
    }
  })
});

const { data } = await response.json();
const { token, sessionId } = data.generateComponentToken;

Yn arall, os oes gennych eisoes sessionId o alwad flaenorol:

variables: {
  input: {
    component: 'LS_SIGNER',
    signer: { sessionId: '<session-id>' }
  }
}

Opsiwn 2: REST API

const response = await fetch(
  `https://eu-api.legalesign.com/api/v1/signer/${signerId}/component-token/`,
  {
    headers: {
      Authorization: `Bearer ${process.env.LEGALESIGN_API_KEY}`,
    },
  }
);

const { token, sessionId } = await response.json();

Paswch token fel private-key a sessionId fel session-id i’r gydran.

Nodweddion Gorfodol

Nodwedd	Math	Disgrifiad
recipient-id	string	Dynodwr derbynnydd (base64, cychwynnol rec, neu UUID)
private-key	string	Tocyn a ddychwelwyd gan generateComponentToken
session-id	string	ID sesiwn a ddychwelwyd gan generateComponentToken

Nodweddion Dewisol

Nodwedd	Math	Rhagosodedig	Disgrifiad
colour	string	blue	Enw lliw thema (gweler Theming)
style	string	``	Newidiadau arddull (gweler Customer CSS)
branding	boolean	true	Dileu brandio Legalesign
language	string	—	Gorfodi iaith benodol a cuddio newidydd iaith (gweler Internationalisation)

Digwyddiadau

Digwyddiad cydran gwe	Prop React	eventType	Pryd
signingSuccess	onSuccess	"success"	Dogfen wedi ei llofnodi’n llwyddiannus
signingFail	onFail	"failure"	Methiant llofnodi, gwrthodwyd, wedi dod i ben, wedi cael ei ganslo, ei ddileu, neu ei dynnu
fieldChange	onChange	"ready"	Dogfen a delweddau wedi’u llwytho’n llawn
fieldChange	onChange	"save"	Gwerth maes wedi’i arbed
fieldChange	onChange	"select"	Maes wedi’i ddewis neu ei ganolbwyntio

signingSuccess / onSuccess

{
  eventType: 'success';
  documentId: string;
  recipientId: string;
}

signingFail / onFail

{
  eventType: 'failure';
  failureReason: FailureReason;
  error: string;
  documentId?: string;
  recipientId: string;
}

failureReason	Achos
documentExpired	Mae’r ddogfen wedi dod i ben neu mae’r dyddiad dod i ben yn y gorffennol
sessionExpired	Dychwelwyd 401 neu 403 gan yr API
cancelled	Mae statws y ddogfen yn "cancelled"
deleted	Mae’r ddogfen wedi ei dileu
rejected	Gwrthododd y derbynnydd y ddogfen
removed	Dychwelwyd 404 gan yr API
signingError	unrhyw gamgymeriad arall yn ystod llwytho neu llofnodi

fieldChange / onChange

Mae’r tri gwerth eventType yn rhannu’r un digwyddiad. Defnyddiwch eventType i wahaniaethu:

// eventType: 'ready' — document fully loaded
{ eventType: 'ready'; document: { documentId, name, state, recipientId, pageCount, expires?, isApprover, isWitness, canReassign, doOfferReject } }

// eventType: 'save' — field value saved
{ eventType: 'save'; uuid: string; saved: boolean; field: Record<string, any> }

// eventType: 'select' — field selected or focused
{ eventType: 'select'; uuid: string; field: Record<string, any> }

Props React

Mae’r cydran React yn defnyddio props yn camelCase a props galw’n ôl yn lle digwyddiadau DOM:

Prop	Math	Gorfodol	Disgrifiad
recipientId	string	✅	Dynodwr derbynnydd
privateKey	string	✅	Allwedd breifat o’r mutation generateComponentToken
sessionId	string	✅	Dynodwr sesiwn
colour	LsSignerColour	❌	Lliw thema
branding	boolean	❌	Dangos brandio Legalesign. Rhagosodedig i true.
language	string	❌	Gorfodi iaith benodol (gweler Internationalisation)
onSuccess	(data: { eventType: 'success'; documentId: string; recipientId: string }) => void	❌	Cael ei alw ar llofnodi llwyddiannus
onFail	(data: { eventType: 'failure'; failureReason: FailureReason; error: string; documentId?: string; recipientId: string }) => void	❌	Cael ei alw ar fethiant llofnodi
onChange	(data: { eventType: 'ready' | 'save' | 'select'; document?: DocumentSummary; uuid?: string; saved?: boolean; field?: Record<string, any> }) => void	❌	Cael ei alw ar ddigwyddiadau maes a dogfen yn barod

Handleri catch-all (datrys problemau a prototeipio)

Gan fod pob digwyddiad yn cynnwys eventType, gallwch gysylltu un swyddogaeth i bob digwyddiad:

React:

const handleSignerEvent = (e) => {
  switch (e.eventType) {
    case 'success': console.log('Signed:', e.documentId); break;
    case 'failure': console.log('Failed:', e.failureReason, e.error); break;
    case 'ready':   console.log('Ready:', e.document?.name); break;
    case 'save':    console.log('Saved field:', e.uuid, e.saved); break;
    case 'select':  console.log('Selected field:', e.uuid); break;
  }
};

<LsSigner
  onSuccess={handleSignerEvent}
  onFail={handleSignerEvent}
  onChange={handleSignerEvent}
/>

Cydran Gwe:

const handleSignerEvent = (e) => {
  switch (e.detail.eventType) {
    case 'success': console.log('Signed:', e.detail.documentId); break;
    case 'failure': console.log('Failed:', e.detail.failureReason, e.detail.error); break;
    case 'ready':   console.log('Ready:', e.detail.document?.name); break;
    case 'save':    console.log('Saved field:', e.detail.uuid, e.detail.saved); break;
    case 'select':  console.log('Selected field:', e.detail.uuid); break;
  }
};

signer.addEventListener('signingSuccess', handleSignerEvent);
signer.addEventListener('signingFail', handleSignerEvent);
signer.addEventListener('fieldChange', handleSignerEvent);

Thema

Gosodwch thema lliw gyda’r prop colour. Fe’i dynnir yn awtomatig i bob lliw a’i gysgodi.

Lliwiau Ar Gael

pink · blue · purple · indigo · teal · green · lightblue · burnt · aubergine · red · yellow · cyan · lime · trueGreen

Peidiwch â rhoi prop i gael y glas diofyn.

<ls-signer colour="pink" ...></ls-signer>

<LsSigner colour="pink" ... />

Mae’r prop colour yn sefydlu nodwedd data-ls-theme ar wraidd y gydran. Mae priodoleddau CSS arferol yn diffinio graddfa cysgodi 10–100 i bob lliw:

Cysgodi	Defnydd
10	Cefndiroedd golau, llenwi ysgafn
20	Ffiniau ysgafn
30	Rhigol ffocws
60	Lliw craidd (botymau, dolenni, cyflwr gweithredol)
70	Cyflwr ar symud y llygoden (hover)
80	Accennau tywyll/cryf

CSS Custom

Mae’r gydran yn datgelu priodoleddau CSS arferol y gellir eu diwygio i addasu’r ymddangosiad y tu hwnt i thema lliw. Mae’r set hwn o briodoleddau’n gyfyngedig ar hyn o bryd, cysylltwch â ni am fwy.

<ls-signer
  style="--ls-font-family: 'Inter', sans-serif; --ls-color-primary-60: #e91e63;"
  recipient-id="abc123"
  private-key="key"
  session-id="session"
></ls-signer>

Priodoleddau Ar Gael

Priodoledd	Rhagosodedig	Disgrifiad
--ls-font-family	'IBM Plex Sans', sans-serif	Teulu ffont blaenoriaeth
--ls-color-primary-10 i --ls-color-primary-100	—	Graddfa lliw craidd lawn (yn disodli thema)
--ls-color-error	#f64a44	Lliw cyflwr gwall
--ls-color-error-light	#fff0f0	Cefndir gwall
--ls-color-success	#46dbaa	Lliw cyflwr llwyddiant
--ls-color-success-light	#effff9	Cefndir llwyddiant
--ls-color-warning	#fad232	Lliw cyflwr rhybudd
--ls-color-warning-light	#fffcef	Cefndir rhybudd
--ls-color-border	#d8d9dc	Lliw ffin defaith
--ls-color-border-subtle	#e0e2e5	Lliw ffin ysgafn
--ls-color-bg-subtle	#f7f8fa	Lliw cefndir ysgafn

Nodyn: Ar gyfer chwistrellu CSS custom llawn (targedu elfennau mewnol yn uniongyrchol, disodli meintiau ffont, trwch ffin, gofod, ac ati), mae hwn yn nodwedd arfaethedig ar gyfer y dyfodol. Os ydych yn ddiddorol, cysylltwch â ni.

Rhyngwladoli

Mae’r gydran yn cefnogi 17 o ieithoedd gyda chyfieithiadau wedi’u pecynnu yn y adeilad. Canfyddir yr iaith yn awtomatig o’r porwr. Mae newidydd iaith adeiledig yn y UI llofnodi yn caniatáu i’r derbynnydd newid iaith ar unrhyw adeg.

Gosodwch yr awgrym language i orfodi iaith benodol. Pan gânt eu darparu, bydd y newidydd iaith adeiledig yn cael ei guddio ac fe fydd canfod y porwr yn cael ei ddiystyru.

<ls-signer language="fr" recipient-id="abc123" private-key="key" session-id="session"></ls-signer>

<LsSigner language="fr" recipientId="abc123" privateKey="key" sessionId="session" />

Trefn flaenoriaeth: prop language → iaith porwr → Saesneg fel diffyg.

Cod	Iaith	Cod	Iaith
en	Saesneg	nl	Iseldireg
fr	Ffrangeg	fi	Ffinneg
bg	Bwlgareg	it	Eidaleg
es	Sbaeneg	he	Hebraeg
de	Almaeneg	sv	Swedeg
gs	Gaeleg yr Alban	cy	Cymraeg
ar	Arabeg	is	Icelandeg
el	Groeg	iw	Hebraeg (traddodiadol)
pt	Portiwgaleg
ro	Rhwmaniaeg

Fersiynu CDN

Mae’r URL CDN yn cefnogi fersiynau latest a rhifau fersiwn sefydlog:

<!-- Always get the most recent version (recommended) -->
<script type="module" src="https://cdn.legalesign.io/signer/latest/ls-signer.esm.js"></script>

<!-- Pin to a specific version -->
<script type="module" src="https://cdn.legalesign.io/signer/v1.1.0/ls-signer.esm.js"></script>

Rydym yn argymell defnyddio latest — mae hyn yn sicrhau bod eich integreiddiad yn derbyn trwsio bygiau, phaciau diogelwch, a nodweddion newydd yn awtomatig. Defnyddiwch fersiwn sefydlog os oes angen i chi gloi ar ryddhad sy’n hysbys yn ystod rhewi QA neu lansiad rheoledig. Gweler y hanes fersiwn llawn ar npm am fersiynau ar gael.

Enghraifft Gynhwysfawr

<!DOCTYPE html>
<html>
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>Document Signing</title>
    <script type="module" src="https://cdn.legalesign.io/signer/latest/ls-signer.esm.js"></script>
  </head>
  <body>
    <ls-signer
      recipient-id="abc123"
      private-key="key"
      session-id="session"
      colour="teal"
    ></ls-signer>

    <script>
      const signer = document.querySelector('ls-signer');

      signer.addEventListener('signingSuccess', (event) => {
        console.log('Document signed:', event.detail.documentId);
        window.location.href = '/thank-you';
      });

      signer.addEventListener('signingFail', (event) => {
        console.error('Signing failed:', event.detail.failureReason, event.detail.error);
      });

      signer.addEventListener('fieldChange', (event) => {
        if (event.detail.eventType === 'ready') {
          console.log('Ready to sign:', event.detail.document.name);
        }
      });
    </script>
  </body>
</html>

Cefnogaeth Porwr

• Chrome/Edge (wythnosolaf)
• Firefox (wythnosolaf)
• Safari (wythnosolaf)
• Poryddion symudol (iOS Safari, Chrome Mobile)

Adnoddau

• Pecyn NPM
• Widget Authorization
• Dogfennaeth API GraphQL
• Symud o llofnodi iframe
• Cymorth

Fideo: Symud o iframe i’r gydran Signer