How Web Document Scanning Works

A web page cannot directly call a Windows TWAIN or WIA scanner driver. A browser intentionally isolates the page from local hardware. Web document scanning therefore needs a small local component that speaks to the driver and exposes a controlled interface to the browser.

ScanBridge divides the job into four parts:

1. the scanner and its Windows driver acquire the page;
2. a per-user helper communicates with TWAIN or WIA;
3. the web application calls the helper on 127.0.0.1;
4. the browser receives the image or finished PDF and passes it to your code.

Why JavaScript alone cannot open a TWAIN scanner

TWAIN and WIA are operating-system interfaces. Browser JavaScript runs inside a security sandbox and has no general API for enumerating those drivers or invoking their native scan dialogs.

File upload does not solve the same problem. It lets a user select a file that already exists. It does not select a scanner, configure duplex or a feeder, acquire pages or return the result to the record currently open in the application.

The local helper

ScanBridge installs a 1.5 MB background helper into the current Windows user profile. The installer itself does not require administrator rights. The helper listens only on the loopback address and chooses the first free port from 18625 through 18688.

The browser client checks that range, finds the helper and remembers the responding port. The integrator does not configure a fixed port.

The public contract contains six endpoints:

Except for /status, requests require an origin-specific pairing token.

What happens during a scan

The application first renders the ready-made scanner-widget or calls the local API through its own interface. When the user starts a scan:

1. the helper asks the selected TWAIN or WIA driver for its capabilities;
2. the interface shows only settings reported by that device;
3. the driver acquires the page;
4. the helper returns the image to the browser;
5. the browser displays, edits and combines pages according to the licensed features;
6. the saved event returns a PDF Blob or an array of image pages.

For PDF output, the document is assembled in the browser. ScanBridge does not upload the scanned file to create it.

What leaves the workstation

The document does not travel to ScanBridge. The only outbound product request is licence refresh data sent to license.scanbridge.dev. It contains the licence key, application origin, a one-way machine identifier and product version.

Your own application may upload the saved file after it receives the Blob. That request is part of your code, storage architecture and privacy policy.

Where the web component fits

The custom element is the shortest integration path:

<scanner-widget
  license-key="SB-XXXX-XXXX-XXXX"
  file-type="pdf"
  lang="en">
</scanner-widget>

const scanner = document.querySelector('scanner-widget')

scanner.addEventListener('saved', event => {
  upload(event.detail.blob)
})

The component is a client of the same local interface. Teams can replace its UI and use the endpoints directly when their workflow requires it.

Requirements and limits

• Windows 10 or Windows 11;
• Chrome, Edge or Firefox;
• a device with a working TWAIN or WIA driver;
• the per-user helper installed on the same workstation as the browser;
• a valid application licence.

ScanBridge does not currently provide a macOS, Linux or mobile helper. RDP, Citrix and multi-user terminal server deployments are not certified configurations. Test the exact workstation, scanner driver and browser during the trial.

For package installation and the complete event payload, continue with the integration guide. For platform boundaries, see compatibility.