edatalia-websign
v3.2.2
Published
JavaScript library for handwritten digital signatures from a web browser and/or using Wacom STU and DTU tablets.
Downloads
403
Readme
WebSign
WebSign is a JavaScript library developed by Edatalia for integrating handwritten digital signatures into PDF documents from any modern web browser. It supports native browser signing as well as advanced integration with Wacom STU and DTU signature tablets.
Important: WebSign works exclusively over HTTPS and with UTF-8 encoding.
✨ Features
- Handwritten PDF signing via browser, STU, or DTU tablets
- Signature positioning via fixed coordinates or float (text search)
- Certified PDF signatures with OCSP and timestamp support
- EBP templates for Wacom
- Supports Salesforce and restricted environments
- Multi-language support
- Custom signature widget appearance and metadata
- Multi-document signature
📦 Installation
Install via NPM:
npm install edatalia-websignThen, import it in your JavaScript application:
import 'edatalia-websign';This will globally register the
WebSignconstructor in the browser context.
In your HTML or SPA component, place the following container:
<div id="web-sign"></div>🚀 Basic Usage
Example using a file input:
WebSign comes with default parameter values, but it's recommended to set them to your desired value depending on your needs. Also you need a bearer token to be able to sign.
<!doctype html>
<html lang="en">
<head>
<meta charset="UTF-8" />
<link rel="icon" type="image/svg+xml" href="/vite.svg" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>websign-npm</title>
<!-- Descomment next line if use with CDN-->
<!-- <script src="https://cdn.jsdelivr.net/npm/edatalia-websign@latest/web-sign-core.min.js"></script> -->
</head>
<body>
<div id="app"></div>
<input type="file" id="fileInput" />
<div id="web-sign"></div>
<script type="module">
import 'edatalia-websign' //comment this line if you use with CDN
document.getElementById("fileInput").addEventListener("change", (e) => {
const file = e.target.files[0];
const config = {
bearerToken: "Your bearer Token",
signatureEnvironment: "SANDBOX", //can be PRO
signatureType: "display", // other values are: stu, dtu, auto
language: "es",
viewPDF: true,
mainContainerHeight: "800px",
widget: {
type: "fixed",
width: 160,
height: 100,
x: 100,
y: 100
},
wacom: {
enableScreenSaver: true,
blackAndWhiteScreenSaver: "https://cdn.jsdelivr.net/npm/[email protected]/dist/default-ebp/blackAndWhiteScreenSaver.png",
colorScreenSaver: "https://cdn.jsdelivr.net/npm/[email protected]/dist/default-ebp/colorScreenSaver.png",
enableEbp: true,
blackAndWhiteEbp: "https://cdn.jsdelivr.net/npm/[email protected]/dist/default-ebp/blackAndWhiteEbp.ebp",
colorEbp: "https://cdn.jsdelivr.net/npm/[email protected]/dist/default-ebp/colorEbp.ebp",
varEbp: "Titulo=Título de STU|||Subtitulo=Subtítulo de STU|||Nombre=Edatalia|||AreaFirma=Firma a continuación",
enableInitialEbp: false,
blackAndWhiteInitialEbp: "https://cdn.jsdelivr.net/npm/[email protected]/dist/default-ebp/blackAndWhiteInitialEbp.ebp",
colorInitialEbp: "https://cdn.jsdelivr.net/npm/[email protected]/dist/default-ebp/colorInitialEbp.ebp",
varInitialEbp: "Titulo=Título inicial|||Subtitulo=Subtítulo inicial|||Nombre=Edatalia|||TextoPrevio=Estoy de acuerdo con el documento a firmar",
}
}
const webSign = new WebSign(file, config, (event) => {
switch (event.type) {
case "signed":
console.log("Signed PDF:", event.data);
break;
case "signed-multiple":
console.log("Signed PDFs:", event.data);
break;
case "error":
console.log(event.error);
break;
default:
break;
}
});
});
</script>
</body>
</html>
WebSign constructor requires three parameters:
1. PDF INPUT FILE
2. CONFIG OBJECT
3. CALLBACK📄 PDF Input Formats
You can provide the PDF to WebSign in three formats:
- HTML file input
const file = input.files[0]; // can be multi-document- Base64 string
const base64String = "JVBERi0xLjQKJ...";- Salesforce-compatible structure
const pdfData = {
pdfB64: "base64_string",
pdfUrl: "https://url.to/your.pdf"
};⚙️ Configuration Parameters
All parameters below are part of the config object:
| Option | Type | Description |
|--------|------|-------------|
| bearerToken | string | Auth token for API communication |
| debug | boolean | To enable or disable error messages |
| requestPermissions | boolean | Request permissions for tablets via a button before launching the app. |
| mainContainerWidth | string | Width of the main container (e.g. "100%", "800px")|
| mainContainerHeight | string | Height of the main container (e.g. "100%", "800px") |
| signatureContainerWidth | string | Width of the signature container (e.g. "100%", "800px")|
| signatureContainerHeight | string | Height of the signature container (e.g. "100%", "800px") |
| signatureEnvironment | string | "SANDBOX" or "PRO" |
| signatureServiceUrl | string | Endpoint for signature |
| signatureType | string | "stu", "display", "dtu", or "auto" |
| signatureColorHex | string | Hex color of signature stroke |
| autoDownload | boolean | Auto-download the signed PDF. Compatible with single file |
| minPointsRequiredToSign | number | Minimum stroke points required |
| signatureThickness | number | Stroke thickness (1–30) |
| mouseEBP | boolean | Enable mouse EBP |
| viewPDF | boolean | Enable PDF preview |
| renderDefaultIndexPage | number | PDF page to show initially |
| requestedEncodingBits | number | EBP encoding quality (1, 16, 24) |
| language | string | UI language (e.g., "es", "en", "fr") |
| requestLocation | boolean | Include geolocation metadata |
| doPerformance | boolean | Enable performance tracking |
| dtuHtmlUrl | boolean | Html path for dtu |
| jsUrl | boolean | Js path for dtu |
| loadSignedPdf | boolean | Realoads the signed PDF upon completion of the signature on the viewer. Compatible with single file |
| encCertKey | string | Value to define the public key for the biometric data encryption certificate. By default, the edatalia encryption certificate will be used. |
| options | Object | Enable or disable timestamp and ocsp providers.
| timestampProvider | Object | Specifies timestamp values to make timestamp signatures (B-T). The includeTimestamp in options must be set to true. To use default timestamp provider omit this param or set to null |
| ocspProvider | Object | Specifies ocsp values to make long term validation signatures (B-LT). The includeOCSP in options must be set to true. And the timestamp must be set correctly. To use default ocsp provider omit this param or set to null |
| signatureTimeLimit | number | Time limit to be able to sign |
| widget | Object | Specifies signature positioning in coordinates or by text search, custom text for the signature, etc. |
| edataliaBaseUrl | string | Specifies base url to edatalia scripts, needed for viewer |
| wacom | Object | Specifies parameter for the wacom devices |
| properties | Object | Specifies pdf signature properties like author, reason, contact and location |
| authenticationUrl | string | Defines the authentication service endpoint for validating tokens. |
| displayCanvasSignatureButtonsInDTU | boolean | When set to true, this parameter enables display of signature action buttons directly within the DTU device canvas interface, allowing users to perform signature-related operations from the DTU screen itself |
| enableBridge | boolean | When set to true, this parameter tries to communicate with WebSign Bridge, see more in the corresponding section |
widget: {
type: "float", // can be 'fixed' (absolute position) or 'float' (based on text search)
width: 160, // width of the signature area
height: 100, // height of the signature area
x: 0, // X position on the PDF page (used if type is 'fixed')
y: 0, // Y position on the PDF page (used if type is 'fixed')
page: 0, // PDF page number where the signature will appear
customText: [ // text displayed on the PDF after signing
{
text: "Documento firmado digitalmente",
fontSize: 6
},
{
text: "Fecha y hora: ##TIMESTAMP##",
fontSize: 4
}
],
text: null, // if 'float', this text will be searched in the PDF to place the signature
fieldName: null, // optional name of the signature field
gapX: 0, // horizontal offset
gapY: 0 // vertical offset
},
wacom: {
ebpServiceUrl: //Service URL for the ebp translation service (only required for on-premise installations),
enableScreenSaver: //Enables the standby screen.
blackAndWhiteScreenSaver: // Path where the black and white Wacom standby screen image is located. Could be relative project public path like /assets/..
colorScreenSaver: // Path where the color Wacom standby screen image is located. Could be relative project public path like /assets/..
enableEbp: //Enables ebp in the project (display templates on Wacom).
enableInitialEbp: //Enables the pre-signature screen on Wacom. Could be relative project public path like /assets/..
varInitialEbp: //Template description that appears on the Wacom screen before signing. Separated by |||.
blackAndWhiteInitialEbp: // Path where the black and white Wacom initial image is located. Could be relative project public path like /assets/..
colorInitialEbp: // Path where the initial color image for Wacom is located. Could be relative project public path like /assets/..
varEbp: //Text values displayed in the EBP template for Wacom tablets at the time of signing. Variables are separated by three "|||" pipes.
},
Example: "varEbp": "Titulo=Título inicial|||Subtitulo=Subtítulo inicial|||Nombre=Edatalia|||TextoPrevio=Estoy de acuerdo con el documento a firmar",
📡 Events
options: {
includeTimestamp: false, //set to true if includes timestamp provider
includeOCSP: false, //set to true if includes ocsp provider
validateCertificate: false //verifies certificate validity at the time of signing
pdfCertifiedSignature: false //if true applies MDP certified type signature
},
timestampProvider: {
url: "https://..",
user: "...",
password: "...",
},
ocspProvider: {
url: "https://..",
user: "...",
password: "...",
},
properties: {
reason: "Reason ..",
author: "Author ..",
contact: "Contact .."
location: "Location .."
},
Websign Callback events
WebSign emits events via the callback function passed as the third argument:
| Event | Description |
|-------|-------------|
| signed | Signature complete, PDF in event.data |
| signed-multiple | Signature complete for multiple PDF in event.data |
| cancel | User canceled the process |
| error | An error occurred |
| no-device | No Wacom device detected |
| signature-timeout | Timeout waiting for user input |
💻 DTU Integration
WebSign supports Wacom DTU tablets via a dedicated HTML file rendered on the device screen. You must provide the following parameters:
const config = {
signatureType: "dtu",
jsUrl: "/your/path/web-sign.js",
dtuHtmlUrl: "/your/path/dtu.html", // only needed in salesforce
};
DTU signing is only supported in Google Chrome, Edge, and Opera.
🧩 WebSign Bridge (Desktop helper)
WebSign Bridge is a lightweight desktop companion that enhances WebSign with native capabilities via a local service. It enables high‑performance operations and access to the local environment when your app runs in the browser.
Why use the Bridge?
⚡ Speed-ups in signature workflows (reduced latency on device I/O and PDF handling)
🚀 Faster EBP loading on Wacom devices (STU/DTU)
🔐 Local certificate signing with certificates installed on the machine
🔗 Advanced WebSign features not available in pure browser mode — with more to come
Installation
1. Download & install the MSI for WebSign Bridge on the target workstation.
2. Complete the installer wizard — this sets up the local Bridge service.
3. Once installed, start the service (the installer usually starts it automatically). 💡 The Bridge runs a small local server that WebSign connects to when enabled.
Enable Bridge in your Web app
Use the param enableBridge : true in config
If enableBridge is true, the app will automatically route calls through WebSign Bridge.
If false or missing, WebSign operates in browser-only mode.
At the moment, when bridge is active, the viewPDF must be set to false.
Required for Bridge Signing
To sign documents using the WebSign Bridge, it is essential to configure the following parameter:
authenticationUrl
Specifies the endpoint used to authenticate the bearer token before enabling signing features. This URL must match your token’s environment:
Sandbox tokens: https://acceso.firmar.info
Production tokens: https://acceso.firmar.online
Runtime behavior
When Bridge is enabled and its local service is running, WebSign will seamlessly take advantage of its capabilities.
If Bridge is not installed or the service is stopped, WebSign falls back to standard browser behavior — no changes required in your code.
Troubleshooting
The app doesn’t use Bridge
- Verify the MSI is installed and the service is running on the machine.
- Confirm enableBridge is true in WebSign configuration
- Check corporate proxy/firewall rules that might block local loopback connections.
Certificates not detected
- Ensure the certificate is installed in the user/machine store and accessible to the running user session.
Performance isn’t improved
- Confirm Bridge is active (see logs) and that you’re using STU/DTU or operations benefiting from native I/O.
🧾 License
© 2025 Edatalia Data Solutions. All rights reserved.
Web-Sign is proprietary software. Use of this library is permitted exclusively under the conditions set forth by Edatalia Data Solutions.
Terms of Use This software may not be distributed, modified, or used without explicit permission from Edatalia Data Solutions.
Unauthorized redistribution is strictly prohibited.
For commercial licensing rights, please contact us at https://edatalia.com/contacto/.
Warranty and Liability This software is provided "as is", without any warranties of any kind. Edatalia Data Solutions is not liable for any damages arising from the use of this software.
For more information or to acquire a commercial license, visit https://edatalia.com/.
🏢 About
Developed by Edatalia, digital signatures, and biometric solutions for secure document processing.