JavaScript library for handwritten digital signatures from a web browser and/or using Wacom STU and DTU tablets.
npm install edatalia-websignbash
npm install edatalia-websign
`
Then, import it in your JavaScript application:
`js
import 'edatalia-websign';
`
> This will globally register the WebSign constructor in the browser context.
In your HTML or SPA component, place the following container:
`html
`
---
🚀 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.
`html
websign-npm
`
---
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:
1. HTML file input
`js
const file = input.files[0]; // can be multi-document
`
2. Base64 string
`js
const base64String = "JVBERi0xLjQKJ...";
`
3. Salesforce-compatible structure
`js
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 |
| 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 |
| useMiddleware | boolean | Routes signature data through an external middleware via callback before completing the flow |
| offlineMode | boolean | Enables offline signature capture using Service Worker |
| offlineModeAutoFetch | boolean | Auto-syncs pending requests in background without prompting the user |
---
`js
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
},
`
`js
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
`js
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
},
`
`js
timestampProvider: {
url: "https://..",
user: "...",
password: "...",
},
`
`js
ocspProvider: {
url: "https://..",
user: "...",
password: "...",
},
`
`js
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:
`js
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.
---
📴 Offline Mode
WebSign supports intermittent connectivity scenarios. Although it's called "offline mode", the user needs connection to receive the signed PDF. However, if connection is lost at the moment of signing, the request is stored locally and processed when WebSign is launched again.
$3
1. Copy the Service Worker file to your project root:
`bash
cp node_modules/edatalia-websign/dist/offline-sw.js ./public/
`
2. Enable offline mode in your config:
`js
const config = {
offlineMode: true,
offlineModeAutoFetch: true, // auto-sync pending requests without prompting
// ... other config
};
`
$3
- HTTPS with valid SSL certificate: Service Workers require a secure context. For local development, use tools like mkcert to generate a trusted certificate.
---
🧩 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.
$3
⚡ 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
$3
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.
$3
- 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.
$3
To sign documents using the WebSign Bridge, it is essential to configure the following parameter:
authenticationUrl`