Leum gu prìomh susbaint

Integrate Legalesign Signer into Your Website

Enable for your team

Tha feum air an eileamaid Signer a chuir an gnìomh. Cuir fios gu taic airson a chur an gnìomh airson do sgioba.

An dreachd làithreach: v1.1.7 — log-atharrachaidhean

Is e eileamaid lìn coileanta agus neo-eisimeileach air àrd-ùrlar a th’ ann an Legalesign Signer a bheir seachad eòlas iomlan, rèidh air clàradh sgrìobhainnean taobh a-staigh do app fhèin. Tha e ag obair le HTML vanilla, React, Vue, Angular, no frèam-lìn sam bith eile.

Embed am pìos seo far a bheil feum aig do luchd-cleachdaidh air sgrìobhainnean a shoidhnigeadh — taobh a-staigh CRM, portal cleachdaiche, no tagradh sam bith a tha a’ riochdachadh HTML.

Installation​

Luchdaich gu dìreach bhon CDN (chan fheumar stàladh):

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

React installation​

Stàlaich tro mhanaidsear pacaid:

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

Basic Integration​

HTML & 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)}
/>
);
}

Feumaidh React react agus react-dom (v18 no v19) mar eisimeileachdan co-aoisean.

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

Ma chleachdas tu Vue le Vite, cuir isCustomElement: (tag) => tag.startsWith('ls-') ris an rèiteachadh plugan Vue agad gus rabhadh eileamaidean neo-aithnichte a sheachnadh.

rabhadh

Tha Vue 3 a’ dol an ìre mhath ann an ainmichean tachartasan air eileamaidean sònraichte, agus mar sin chan obraich @signingSuccess. Cleachd addEventListener air an eileamaid ref mar a chithear gu h-àrd.

Nuxt 3

Enclose <ls-signer> ann an <ClientOnly> gus mearachdan SSR a sheachnadh. Cuir an rèiteachadh eileamaid sònraichte ris ann an nuxt.config.ts:

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

Authentication​

Feumaidh an eileamaid signer token beaga-ùine bhon chùl-raon agad. Tha dà roghainn ann:

  1. GraphQL generateComponentToken — Cuir fòn le component: LS_SIGNER agus recipientId no sessionId anns an raon signer (toirt seachad aon dhiubh, chan an dà chuid).
  2. REST API — Cuir fòn GET /signer/{signerId}/component-token/ leis an iuchair API agad.

Bidh an dà chuid a’ tilgeil air ais a’ token agus sessionId a tha feumail don eileamaid. Faic Ùghdarras Widget airson an sruth token iomlan air taobh an fhrithealaiche.

Option 1: GraphQL (Node.js)​

A’ cleachdadh recipientId (as cumanta — cleachd nuair a tha fios agad cò an neach an dèidh ach chan eil pròiseas fosgailte fhathast):

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;

Gu h-alternatif, ma tha sessionId agad mu thràth bho ghairm roimhe:

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

Option 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();

Cuir token mar private-key agus sessionId mar session-id dhan eileamaid.

Required Attributes​

AtributSeòrsaTuairisgeul
recipient-idstringAithnichear an neach-fhaighinn (base64, ro-ràdh rec, no UUID)
private-keystringToken air a thoirt air ais le generateComponentToken
session-idstringID seisean air a thoirt air ais le generateComponentToken

Optional Attributes​

AtributSeòrsaClàr-amaisTuairisgeul
colourstringblueAinm a’ chuspair dath (faic Cuspair)
stylestring``Atharraichean stoidhle (faic CSS Luchd-cleachdaidh)
brandingbooleantrueSeall suaicheantas Legalesign. Suidhich gu false airson a thoirt air falbh.
languagestring—Thoir oirnn cànan sònraichte agus falaich an inneal-taghadh cànain (faic Eadar-nàiseantachd)

Events​

Prop ReactTachartas eileamaid lìneventTypeCuin
onSuccesssigningSuccess"success"Sgrìobhainn air a shoidhnigeadh gu soirbheachail
onFailsigningFail"failure"Dh’fhàillig soidhnigeadh sgrìobhainn, chaidh a dhiùltadh, a dh'fhalbh, a chunntas, a dh’fhalbh, no air a chrìochnachadh mu thràth ann àite eile
onChangefieldChange"ready"Tha sgrìobhainn agus ìomhaighean làn luchdaichte
onChangefieldChange"save"Chaidh luach raon a shàbhaladh
onChangefieldChange"select"Chaidh raon a thaghadh no a chuir fòcas air

onSuccess / signingSuccess​

Thathas a’ losgadh nuair a nì an neach-fhaighinn comas sgrìobhainn a shoidhnigeadh gu soirbheachail.

{
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);
}}
/>

Eileamaid lìn:

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

onFail / signingFail​

Thathas a’ losgadh nuair a dh’fhàillig an soidhnigeadh — mar thoradh air diùltadh sgrìobhainn no mearachd rè pròiseas an soidhnigeadh (mar eisimpleir mearachd lìonra, seisean a dh’fhalbh, còmhstri steat sgrìobhainn).

{
eventType: 'failure';
failureReason: FailureReason;
error: string; // Human-readable error message
documentId?: string; // UUID of the document (if available)
recipientId: string; // UUID of the recipient
}
failureReasonAdhbhar
documentExpiredTha state an sgrìobhainn "expired" no tha ceann-latha expires san àm a dh'fhalbh
sessionExpiredThug an API air ais 401 no 403 fhad ‘s a bha am prògram a’ luchdachadh sgrìobhainn
cancelledTha state an sgrìobhainn "cancelled"
deletedTha am briog is_deleted air a shuidheachadh gu true
rejectedDh’iarr an neach a fhuair e air an sgrìobhainn (is_rejected true)
removedThug an API air ais 404 — chan eil an sgrìobhainn ann tuilleadh
documentCompletedThug an API soidhnachaidh air ais completed — tha an sgrìobhainn air a bhith air a shoidhnigeadh mu thràth, is dòcha air brobhsair no inneal eile. Tha am pìos a’ sealltainn teachdaireachd fiosrachail don neach-fhaighinn seach mearachd.
signingErrorMearachd sam bith eile rè luchdachaidh no soidhnigeadh

React:

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

Eileamaid lìn:

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​

Tha na trì luachan eventType a’ roinn an aon tachartas. Cleachd eventType airson eadar-dhealachadh.

eventType: "ready"​

Thathas a’ losgadh aon turas nuair a bhios an sgrìobhainn agus na h-ìomhaighean air gach duilleag air an luchdachadh gu tur agus tha an eadar-aghaidh soidhnigeadh deiseil airson eadar-obrachadh.

{
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);
}
}}
/>

Eileamaid lìn:

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

eventType: "save"​

Thathas a’ losgadh aon turas às dèidh luach raon a bhith air a shàbhaladh air an fhrithealaiche.

{
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);
}
}}
/>

Eileamaid lìn:

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

eventType: "select"​

Thathas a’ losgadh nuair a bhios raon air a thaghadh no air a chur fòcas air — air a chuir an gnìomh le cliog neach-cleachdaidh, seòladh meur-chlàr, gluasad fèin-ghluasadach, no eadar-obrachadh san taobh-bhanaid.

{
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);
}
}}
/>

Eileamaid lìn:

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

Field Properties​

Tha am pìos field a thèid a thoirt leis na tachartasan save agus select a’ toirt a-steach na seòrsachan a leanas:

SeilbhSeòrsaTuairisgeul
uuidstringAithnichear raon gun samhail
fieldtypestringSeòrsa raon (m.e. "text", "signature", "date", "checkbox")
valuestringLuach raon làithreach
statebooleanA bheil an raon air a shàbhaladh gu soirbheachail
optionalbooleanA bheil am raon roghnach
pagenumberÀireamh an duilleig far a bheil am raon
labelstringLabel an raon (ma tha e air a shuidheachadh)
validationnumberCòd seòrsa dearbhaidh
logicactionstringSeòrsa gnìomh loidsigeach ("1" = rèidio, "2" = cruinneachadh, "3" = suidheachadh)
logicgroupstringAithnichear buidheann loidsigeach
maptostringBuidheann targaid airson loidsig (raointean smachd)
autobooleanA bheil an raon air a lìonadh gu fèin-ghluasadach
dirtybooleanA bheil atharrachaidhean ionadail neo-shàbhalaichte aig an raon

React Props​

Tha eileamaid React a’ cleachdadh propan ann an cruth camelCase agus callback props an àite tachartasan DOM:

PropSeòrsaRiatanachTuairisgeul
recipientIdstring✅Aithnichear an neach-fhaighinn
privateKeystring✅Iuchair phrìobhaideach bho atharrachadh generateComponentToken
sessionIdstring✅Aithnichear an t-seisein
colourLsSignerColour❌Dath a’ chuspair
brandingboolean❌Seall suaicheantas Legalesign. Airson an àbhaist gu true.
languagestring❌Thoir oirnn cànan sònraichte (faic Eadar-nàiseantachd)
onSuccess(data: { eventType: 'success'; documentId: string; recipientId: string }) => void❌Ga ghairm nuair a thèid soidhnigeadh gu soirbheachail
onFail(data: { eventType: 'failure'; failureReason: FailureReason; error: string; documentId?: string; recipientId: string }) => void❌Ga ghairm nuair a dh’fhàillig an soidhnigeadh
onChange(data: { eventType: 'ready' | 'save' | 'select'; document?: DocumentSummary; uuid?: string; saved?: boolean; field?: Record<string, any> }) => void❌Ga ghairm air tachartasan raon agus sgrìobhainn deiseil

Catch-all handler (debugging & prototyping)​

Leis gun tèid eventType a thoirt ann an gach tachartas, faodaidh tu aon ghnìomh a cheangal ri gach tachartas:

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

Eileamaid lìn:

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​

Suidhich cuspair dath leis an prop colour. Bidh a h-uile sgàileadh air an dèanamh fèin-ghluasadach.

Available Colours​

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

Thoir air falbh am prop airson an dath gorm àbhaisteach.

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

Bidh am prop colour a’ suidheachadh an data-ls-theme air freumh an eileamaid. Thèid propachdan gnàthaichte CSS a chleachdadh airson sgèile sgàilean 10–100 airson gach dath:

SgàilCleachdadh
10Cùl-fhiosrachaidhean aotrom, lìonana caol
20Crìochan caol
30Fàinneachan fòcas
60Dath prìomh (putanan, cheanglaichean, steatan gnìomhach)
70Steàt hover
80Cuideam dorcha / làidir

Custom CSS​

Tha am pìos a’ tabhann propachdan CSS gnàthaichte a ghabhas atharrachadh airson coltas a ghnàthachadh nas fhaide na cuspair dath. Tha an t-sreath seo sa mhionaid chuingealaichte, cuir fios thugainn airson barrachd.

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

Available Properties​

PropertyDefaultTuairisgeul
--ls-font-family'IBM Plex Sans', sans-serifTeaghlach font prìomh
--ls-color-primary-10 gu --ls-color-primary-100—Sgèile dath prìomh làn (a’ cur thairis cuspair)
--ls-color-error#f64a44Dath steàt mearachd
--ls-color-error-light#fff0f0Cùl-fhiosrachadh mearachd
--ls-color-success#46dbaaDath steàt soirbheachais
--ls-color-success-light#effff9Cùl-fhiosrachadh soirbheachais
--ls-color-warning#fad232Dath steàt rabhadh
--ls-color-warning-light#fffcefCùl-fhiosrachadh rabhaidh
--ls-color-border#d8d9dcDath crìoch àbhaisteach
--ls-color-border-subtle#e0e2e5Dath crìoch caol
--ls-color-bg-subtle#f7f8faDath cùl-fhiosrachaidh caol

Nota: Airson cruthachadh làn aig CSS gnàthaichte (a’ cuimseachadh gu dìreach air eileamaidean a-staigh, a’ cur thairis meudan font, radius crìoch, àite, msaa), tha seo na fheart San àm ri teachd. Cuir fios thugainn ma tha ùidh agad (faic taic).

Internationalisation​

Tha an eileamaid a’ toirt taic do 17 cànan le eadar-theangachaidhean air am pacadh a-steach don togail. Tha an cànan air a lorg gu fèin-ghluasadach bho bhrabhsair. Tha inneal-taghadh cànan togte ann an UI a’ shoidhnigheadair a’ leigeil leis an neach-fhaighinn cànan atharrachadh uair sam bith.

Suidhich am feart language gus cànan sònraichte a fhòcasachadh. Nuair a thèid a thoirt seachad, tha an inneal-taghadh cànain togte air a chòmhdach agus thathar a’ seachnadh lorg cànan bhon bhrabhsair.

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

Òrdugh prìomhachas: prop language → cànan an bhrabhsair → Ath-nuadhachadh Beurla.

CòdCànanCòdCànan
enBeurlanlDanmhairgis
frFraingisfiFionnlannais
bgBulgàirisitEadailtis
esSpàinntisheEabhrais
deGearmailtissvSuaidise
gsGàidhlig na h-AlbacyCàrnais
arArabaisisInnis-Tìreachais
elGreugaisiwEabhrais (ailteasg)
ptPortagailis
roRòmanach

CDN Versioning​

Tha URL CDN a’ toirt taic do latest agus àireamhan dreach ceangailte:

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

Tha sinn a’ moladh latest a chleachdadh — tha seo a’ dèanamh cinnteach gu bheil an eadar-theangachadh agad a’ faighinn ceartachaidhean bhiteagan, pasgain tèarainteachd agus feartan ùra gu fèin-ghluasadach. Cleachd dreach ceangailte ma tha feum agad air sleamhnachadh ri tionndadh obrach aithnichte rè reothadh QA no a’ cur air bhog gu smachdichte. Faic eachdraidh làn de dhreachan air npm (seall an liosta làn air npm).

Complete Example​

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

Browser Support​

  • Chrome/Edge (an dreach as ùire)
  • Firefox (an dreach as ùire)
  • Safari (an dreach as ùire)
  • Brobhsairean gluasadach (iOS Safari, Chrome gluasadach)

Changelog​

DreachCeann-làGeàrr-chunntas
v1.1.720 Dàmhair 2026Adhbhar fàilligeadh documentCompleted; leasachadh sàbhaladh raon; rèiteachadh suidheachaidh; leasachadh glacadh tachartasan fàilligeadh
v1.1.022 Iuchar 2026Tachartas onChange / fieldChange; prop language; raointean suidheachail; gluasad fèin-ghluasadach; QES
v1.0.1220 Iuchar 2026Tachartas onChange / fieldChange le ready, save, select; luachan failureReason; dearbhadh regex
v1.0.1115 Iuchar 2026Prop language; raointean suidheachail, dropdown, bogsa-sgrìobhainn; cuir a-steach fòn; òrdugh raon
v1.0.69 Ògmhios 2026Prop branding air a chur ris
v1.0.315 Cèitean 2026Prop colour; propachdan gnàthaichte CSS; ceartachaidhean mearachd
v1.0.011 Cèitean 2026Leigeil a-mach seasmhach tùsail

Resources​

Video: Migrating from iframe to the Signer component​