Integrate Legalesign Signer into Your Website
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>
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.
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.
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:
- GraphQL
generateComponentToken— Cuir fòn lecomponent: LS_SIGNERagusrecipientIdnosessionIdanns an raon signer (toirt seachad aon dhiubh, chan an dà chuid). - 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
| Atribut | Seòrsa | Tuairisgeul |
|---|---|---|
recipient-id | string | Aithnichear an neach-fhaighinn (base64, ro-ràdh rec, no UUID) |
private-key | string | Token air a thoirt air ais le generateComponentToken |
session-id | string | ID seisean air a thoirt air ais le generateComponentToken |
Optional Attributes
| Atribut | Seòrsa | Clàr-amais | Tuairisgeul |
|---|---|---|---|
colour | string | blue | Ainm a’ chuspair dath (faic Cuspair) |
style | string | `` | Atharraichean stoidhle (faic CSS Luchd-cleachdaidh) |
branding | boolean | true | Seall suaicheantas Legalesign. Suidhich gu false airson a thoirt air falbh. |
language | string | — | Thoir oirnn cànan sònraichte agus falaich an inneal-taghadh cànain (faic Eadar-nàiseantachd) |
Events
| Prop React | Tachartas eileamaid lìn | eventType | Cuin |
|---|---|---|---|
onSuccess | signingSuccess | "success" | Sgrìobhainn air a shoidhnigeadh gu soirbheachail |
onFail | signingFail | "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 |
onChange | fieldChange | "ready" | Tha sgrìobhainn agus ìomhaighean làn luchdaichte |
onChange | fieldChange | "save" | Chaidh luach raon a shàbhaladh |
onChange | fieldChange | "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
}
failureReason | Adhbhar |
|---|---|
documentExpired | Tha state an sgrìobhainn "expired" no tha ceann-latha expires san àm a dh'fhalbh |
sessionExpired | Thug an API air ais 401 no 403 fhad ‘s a bha am prògram a’ luchdachadh sgrìobhainn |
cancelled | Tha state an sgrìobhainn "cancelled" |
deleted | Tha am briog is_deleted air a shuidheachadh gu true |
rejected | Dh’iarr an neach a fhuair e air an sgrìobhainn (is_rejected true) |
removed | Thug an API air ais 404 — chan eil an sgrìobhainn ann tuilleadh |
documentCompleted | Thug 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. |
signingError | Mearachd 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:
| Seilbh | Seòrsa | Tuairisgeul |
|---|---|---|
uuid | string | Aithnichear raon gun samhail |
fieldtype | string | Seòrsa raon (m.e. "text", "signature", "date", "checkbox") |
value | string | Luach raon làithreach |
state | boolean | A bheil an raon air a shàbhaladh gu soirbheachail |
optional | boolean | A bheil am raon roghnach |
page | number | Àireamh an duilleig far a bheil am raon |
label | string | Label an raon (ma tha e air a shuidheachadh) |
validation | number | Còd seòrsa dearbhaidh |
logicaction | string | Seòrsa gnìomh loidsigeach ("1" = rèidio, "2" = cruinneachadh, "3" = suidheachadh) |
logicgroup | string | Aithnichear buidheann loidsigeach |
mapto | string | Buidheann targaid airson loidsig (raointean smachd) |
auto | boolean | A bheil an raon air a lìonadh gu fèin-ghluasadach |
dirty | boolean | A 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:
| Prop | Seòrsa | Riatanach | Tuairisgeul |
|---|---|---|---|
recipientId | string | ✅ | Aithnichear an neach-fhaighinn |
privateKey | string | ✅ | Iuchair phrìobhaideach bho atharrachadh generateComponentToken |
sessionId | string | ✅ | Aithnichear an t-seisein |
colour | LsSignerColour | ❌ | Dath a’ chuspair |
branding | boolean | ❌ | Seall suaicheantas Legalesign. Airson an àbhaist gu true. |
language | string | ❌ | 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àil | Cleachdadh |
|---|---|
| 10 | Cùl-fhiosrachaidhean aotrom, lìonana caol |
| 20 | Crìochan caol |
| 30 | Fàinneachan fòcas |
| 60 | Dath prìomh (putanan, cheanglaichean, steatan gnìomhach) |
| 70 | Steàt hover |
| 80 | Cuideam 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
| Property | Default | Tuairisgeul |
|---|---|---|
--ls-font-family | 'IBM Plex Sans', sans-serif | Teaghlach 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 | #f64a44 | Dath steàt mearachd |
--ls-color-error-light | #fff0f0 | Cùl-fhiosrachadh mearachd |
--ls-color-success | #46dbaa | Dath steàt soirbheachais |
--ls-color-success-light | #effff9 | Cùl-fhiosrachadh soirbheachais |
--ls-color-warning | #fad232 | Dath steàt rabhadh |
--ls-color-warning-light | #fffcef | Cùl-fhiosrachadh rabhaidh |
--ls-color-border | #d8d9dc | Dath crìoch àbhaisteach |
--ls-color-border-subtle | #e0e2e5 | Dath crìoch caol |
--ls-color-bg-subtle | #f7f8fa | Dath 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òd | Cànan | Còd | Cànan |
|---|---|---|---|
en | Beurla | nl | Danmhairgis |
fr | Fraingis | fi | Fionnlannais |
bg | Bulgàiris | it | Eadailtis |
es | Spàinntis | he | Eabhrais |
de | Gearmailtis | sv | Suaidise |
gs | Gàidhlig na h-Alba | cy | Càrnais |
ar | Arabais | is | Innis-Tìreachais |
el | Greugais | iw | Eabhrais (ailteasg) |
pt | Portagailis | ||
ro | Rò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
| Dreach | Ceann-là | Geàrr-chunntas |
|---|---|---|
| v1.1.7 | 20 Dàmhair 2026 | Adhbhar fàilligeadh documentCompleted; leasachadh sàbhaladh raon; rèiteachadh suidheachaidh; leasachadh glacadh tachartasan fàilligeadh |
| v1.1.0 | 22 Iuchar 2026 | Tachartas onChange / fieldChange; prop language; raointean suidheachail; gluasad fèin-ghluasadach; QES |
| v1.0.12 | 20 Iuchar 2026 | Tachartas onChange / fieldChange le ready, save, select; luachan failureReason; dearbhadh regex |
| v1.0.11 | 15 Iuchar 2026 | Prop language; raointean suidheachail, dropdown, bogsa-sgrìobhainn; cuir a-steach fòn; òrdugh raon |
| v1.0.6 | 9 Ògmhios 2026 | Prop branding air a chur ris |
| v1.0.3 | 15 Cèitean 2026 | Prop colour; propachdan gnàthaichte CSS; ceartachaidhean mearachd |
| v1.0.0 | 11 Cèitean 2026 | Leigeil a-mach seasmhach tùsail |