Integreiddio Arwyddwr Legalesign i’ch Gwefan

Galluogi ar gyfer eich tîm

Mae’n rhaid actifadu’r cydran Arwyddwr. Cysylltwch â chefnogaeth i’w alluogi ar gyfer eich tîm.

Fersiwn gyfredol: v1.1.7 — cofnodi newidiadau

Mae’r Arwyddwr Legalesign yn gydran gwe annibynnol ar lwyfannau sy’n darparu profiad llofnodi dogfennau cyflawn a llyfn o fewn eich app eich hun. Mae’n gweithio gyda vanilla HTML, React, Vue, Angular, neu unrhyw fframwaith gwe.

Mewnosodwch y cydran hon yn unrhyw le lle mae eich defnyddwyr angen llofnodi dogfennau — y tu mewn i CRM, porth cleientiaid, neu unrhyw raglen fewnol sy’n dangos 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

Integreiddiad 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 yn gofyn am react a react-dom (v18 neu v19) fel dibyniaethau cydgynhwysol.

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 cyfluniad ategyn Vue i atal rhybuddion elfennau anhysbys.

rhybudd

Mae Vue 3 yn troi enwau digwyddiadau i lythrennau bach ar elfennau arfer, felly ni fydd @signingSuccess yn gweithio. Defnyddiwch addEventListener ar y cyfeirnod elfen fel y dangosir uchod.

Nuxt 3

Amgylchynwch <ls-signer> gyda <ClientOnly> i atal gwallau SSR. Ychwanegwch y ffurfweddiad elfen arfer yn nuxt.config.ts:

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

Dilysu

Mae’r cydran arwyddwr yn gofyn am docyn tymor byr gan eich cefnwefan. Mae dau opsiwn:

1. GraphQL generateComponentToken — Galwch gyda component: LS_SIGNER a naill ai recipientId neu sessionId yn y cwmpawd arwyddwr (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’r sessionId sydd eu hangen ar y cydran. Gweler Awdurdodi Widget am y llif llawn o docynnau ochr gweinydd.

Opsiwn 1: GraphQL (Node.js)

Gan ddefnyddio recipientId (y mwyaf cyffredin — defnyddiwch pan rydych yn gwybod 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;

Fel arall, os ydych 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();

Trosglwyddwch token fel private-key a sessionId fel session-id i’r cydran.

Nodweddion Gorfodol

Nodwedd	Math	Disgrifiad
recipient-id	string	Gwidentydd derbynnydd (base64, ymlaenrybudd rec, neu UUID)
private-key	string	Tocyn a ddychwelwyd gan generateComponentToken
session-id	string	ID sesiwn wedi’i ddychwelyd gan generateComponentToken

Nodweddion Dewisol

Nodwedd	Math	Diofyn	Disgrifiad
colour	string	blue	Enw lliw thema (gweler Theming)
style	string	``	Newidiadau arddull (gweler Customer CSS)
branding	boolean	true	Dangos brandio Legalesign. Gosod i false i’w dynnu.
language	string	—	Gorfodi iaith benodol a chuddio’r newidydd iaith (gweler Internationalisation)

Digwyddiadau

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

onSuccess / signingSuccess

Yn sgorio pan fydd y derbynnydd yn llofnodi’r ddogfen yn llwyddiannus.

{
  eventType: 'success';
  documentId: string;   // UUID of the signed document
  recipientId: string;  // UUID of the recipient
}

React:

<LsSigner
  onSuccess={({ eventType, documentId, recipientId }) => {
    console.log(eventType);   // "success"
    console.log(documentId);
    console.log(recipientId);
  }}
/>

Cydran gwe:

signer.addEventListener('signingSuccess', (e) => {
  console.log(e.detail.eventType);   // "success"
  console.log(e.detail.documentId);
  console.log(e.detail.recipientId);
});

onFail / signingFail

Yn chwythu pan fydd llofnodi’n methu — naill ai oherwydd gwrthod dogfen neu wall yn ystod y broses llofnodi (e.e. gwall rhwydwaith, sesiwn wedi dod i ben, gwrthdaro statws dogfen).

{
  eventType: 'failure';
  failureReason: FailureReason;
  error: string;          // Human-readable error message
  documentId?: string;    // UUID of the document (if available)
  recipientId: string;    // UUID of the recipient
}

failureReason	Achos
documentExpired	Mae statws dogfen yn "expired" neu ddyddiad expires yn y gorffennol
sessionExpired	Mae’r API wedi dychwelyd 401 neu 403 wrth lwytho’r ddogfen
cancelled	Mae statws dogfen yn "cancelled"
deleted	Mae’r bwlch is_deleted mewn gwirionedd true
rejected	Derbynnydd wedi gwrthod y ddogfen (is_rejected yn wir)
removed	Mae’r API wedi dychwelyd 404 — nid yw’r ddogfen mwyach yn bodoli
documentCompleted	Mae’r API arwyddo wedi dychwelyd completed — roedd y ddogfen eisoes wedi’i llofnodi, tebygol mewn porwr neu ddyfais arall. Mae’r cydran yn dangos neges wybodaeth i’r derbynnydd yn hytrach nag error.
signingError	unrhyw wall arall yn ystod llwytho neu lofnodi

React:

<LsSigner
  onFail={({ eventType, failureReason, error, documentId, recipientId }) => {
    console.log(eventType);      // "failure"
    console.log(failureReason);  // e.g. "documentExpired"
    console.log(error);
  }}
/>

Cydran gwe:

signer.addEventListener('signingFail', (e) => {
  console.log(e.detail.eventType);      // "failure"
  console.log(e.detail.failureReason);  // e.g. "documentExpired"
  console.log(e.detail.error);
});

onChange / fieldChange

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

eventType: "ready"

Yn chwythu unwaith pan fydd y ddogfen a’r holl ddelweddau tudalen wedi’u llwytho’n llawn ac mae rhyngwyneb llofnodi yn barod ar gyfer rhyngweithio.

{
  eventType: 'ready';
  document: {
    documentId: string;      // UUID of the document
    name: string;            // Document name
    state: string;           // Document state (e.g. "signing")
    recipientId: string;     // UUID of the recipient
    recipientRole?: string;  // Role of the recipient (e.g. "witness")
    pageCount: number;       // Number of pages
    expires?: string;        // Expiry date (ISO string, if set)
    isApprover: boolean;     // Whether the recipient is an approver
    isWitness: boolean;      // Whether the recipient is a witness
    canReassign: boolean;    // Whether the recipient can reassign
    doOfferReject: boolean;  // Whether the reject option is shown
  };
}

React:

<LsSigner
  onChange={({ eventType, document }) => {
    if (eventType === 'ready') {
      console.log('Ready to sign:', document.documentId, document.name);
      console.log('Pages:', document.pageCount);
      console.log('Expires:', document.expires);
    }
  }}
/>

Cydran gwe:

signer.addEventListener('fieldChange', (e) => {
  if (e.detail.eventType === 'ready') {
    console.log('Ready to sign:', e.detail.document.documentId, e.detail.document.name);
  }
});

eventType: "save"

Yn chwythu ar ôl gwerth maes wedi’i gadw ar y gweinydd.

{
  eventType: 'save';
  uuid: string;                   // UUID of the field
  saved: boolean;                 // Whether the save was successful
  field: Record<string, any>;     // Full field object (see Field Properties below)
}

React:

<LsSigner
  onChange={({ eventType, uuid, saved, field }) => {
    if (eventType === 'save') {
      console.log(uuid, saved, field.value);
    }
  }}
/>

Cydran gwe:

signer.addEventListener('fieldChange', (e) => {
  if (e.detail.eventType === 'save') {
    console.log(e.detail.uuid, e.detail.saved, e.detail.field.value);
  }
});

eventType: "select"

Yn chwythu pan fydd maes wedi’i ddewis neu ganolbwyntio — wedi’i ysgogi gan glic gan y defnyddiwr, llywio allweddell, symud ymlaen awtomatig, neu rhyngweithio ochr-bar.

{
  eventType: 'select';
  uuid: string;                   // UUID of the selected field
  field: Record<string, any>;     // Full field object (see Field Properties below)
}

React:

<LsSigner
  onChange={({ eventType, uuid, field }) => {
    if (eventType === 'select') {
      console.log('selected', uuid, field.fieldtype);
    }
  }}
/>

Cydran gwe:

signer.addEventListener('fieldChange', (e) => {
  if (e.detail.eventType === 'select') {
    console.log('selected', e.detail.uuid, e.detail.field.fieldtype);
  }
});

Nodweddion Maes

Mae’r gwrthrych field sy’n cael ei gynnwys mewn digwyddiadau save a select yn cynnwys y nodweddion canlynol:

Nodwedd	Math	Disgrifiad
uuid	string	Gwidentydd unigryw maes
fieldtype	string	Math maes (e.e. "text", "signature", "date", "checkbox")
value	string	Gwerth maes presennol
state	boolean	Pa un a gafodd y maes ei gadw’n llwyddiannus
optional	boolean	Pa un a yw’r maes yn ddewisol
page	number	Rhif y dudalen lle mae’r maes yn ymddangos
label	string	Label y maes (os wedi’i osod)
validation	number	Cod math dilysu
logicaction	string	Math gweithred rhesymegol ("1" = radio, "2" = swm, "3" = amodol)
logicgroup	string	Gwidentydd grŵp rhesymegol
mapto	string	Grŵp targed ar gyfer rhesymeg (meysydd rheolydd)
auto	boolean	Pa un a yw’r maes yn cael ei lenwi’n awtomatig
dirty	boolean	Pa un a yw’r maes yn cynnwys newidiadau lleol heb eu cadw

Props React

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

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

Daliwr catch-all (dadansoddi a phrototeipio)

Gan fod pob digwyddiad yn cynnwys eventType, gallwch gael un swyddogaeth yn cysylltu â phob 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);

Theming

Gosod thema lliw gyda’r prop colour. Mae pob arlliw yn cael ei dynnu’n awtomatig.

Lliwiau Ar Gael

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

Peidiwch â rhoi’r prop i gael y lluniaf ddiofyn glas.

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

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

Mae’r prop colour yn gosod nodwedd data-ls-theme ar wraidd y cydran. Mae eiddo CSS arfer wedi’u diffinio ar gyfer sgôr 10–100 ar gyfer pob lliw:

Arlliw	Defnydd
10	Cefndiroedd ysgafn, llenwi ysgafn
20	Ffiniau ysgafn
30	Llyfrau canolbwyntio
60	Lliw blaenorol (botymau, dolenni, statws gweithredol)
70	Statws hofran
80	Accentau tywyll/cryf

CSS Custom

Mae’r cydran yn datgelu eiddo CSS arfer y gellir eu hailadrodd i bersonoli ymddangosiad y tu hwnt i’r thema lliw. Mae set o eiddo ar hyn o bryd yn gyfyngedig, cysylltwch â ni am ragor.

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

Eiddo Ar Gael

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

Nodyn: Ar gyfer chwythiad CSS custom llawn (targedu elfennau mewnol yn uniongyrchol, gwthio maint ffont, radiws ffin, gofod, ac ati), mae hwn yn nodwedd a gynlluniwyd ar gyfer y dyfodol. Cysylltwch â ni os oes gennych ddiddordeb trwy gysylltu.

Rhyngwladoli

Mae’r cydran yn cefnogi 17 o ieithoedd gyda chyfieithiadau wedi’u pacio i’r adeilad. Caiff iaith ei ganfod yn awtomatig o’r porwr. Mae newidydd iaith adeiledig yn rhyngwyneb llofnodi sy’n caniatáu i’r derbynnydd newid iaith ar unrhyw adeg.

Gosodwch y nodwedd language i orfodi iaith benodol. Pan fydd wedi’i darparu, mae’r newidydd iaith adeiledig yn cael ei guddio ac mae canfod y porwr yn cael ei osgoi.

<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 y porwr → iaith Saesneg fel opsiwn wrth gefn.

Cod	Iaith	Cod	Iaith
en	Saesneg	nl	Swinoaeg
fr	Ffrangeg	fi	Ffinneg
bg	Bwlgareg	it	Eidaleg
es	Sbaeneg	he	Hebraeg
de	Almaeneg	sv	Svedeg
gs	Gaeleg Yr Alban	cy	Cymraeg
ar	Arabeg	is	Iwslandi
el	Groeg	iw	Hebraeg (hen)
pt	Portiwgaleg
ro	Rwmaneg

Fersiynu CDN

Mae’r URL CDN yn cefnogi fersiwnau latest a rhifau fersiwn gwarchodedig:

<!-- 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.7/ls-signer.esm.js"></script>

Rydym yn argymell defnyddio latest — mae hyn yn sicrhau bod eich integreiddiad yn cael diweddariadau awtomatig ar gyfer trwsio bygiau, patchi diogelwch, a nodweddion newydd. Defnyddiwch fersiwn rhwystredig os oes angen i chi gloi i ryddhau sydd wedi’i brofi mewn cyfnod rewi QA neu ryddhau rheoledig. Gweler y hanes llawn fersiynau ar npm ar gyfer fersiynau ar gael.

Enghraifft Gyntaf

<!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 (cyfredol)
• Firefox (cyfredol)
• Safari (cyfredol)
• Porwr symudol (iOS Safari, Chrome Mobile)

Cofnodi Newidiadau

Fersiwn	Dyddiad	Crynodeb
v1.1.7	20 Hyd 2026	Reswm methiant documentCompleted; gwelliannau cadw maes; cywiriadau lleoli; gwell dal digwyddiadau methiant
v1.1.0	22 Gor 2026	Digwyddiad onChange/fieldChange; prop language; meysydd amodol; neidio awtomatig; QES
v1.0.12	20 Gor 2026	Digwyddiad onChange/fieldChange gyda ready, save, select; gwerthoedd failureReason; dilysu regex
v1.0.11	15 Gor 2026	Prop language; meysydd amodol, gostyngiad, blwch gwirio; mewnbwn ffôn; trefnu maes
v1.0.6	9 Mehefin 2026	Ychwanegwyd prop branding
v1.0.3	15 Mai 2026	Prop colour; eiddo CSS custom; trwsio bygiau
v1.0.0	11 Mai 2026	Rhyddhau sefydlog cychwynnol

Adnoddau

• Pecyn NPM
• Awdurdodi Widget
• Dogfen API GraphQL
• Mudo o lofnodi iframe
• Cefnogaeth

Fideo: Mudo o iframe i gydran yr Arwyddwr