Initializing the Web Document Scanner SDK

Free Developer Support

We provide free technical support for the implementation and testing of the Scanbot SDK. If you encounter technical issues with integrating the Scanbot SDK or need advice on choosing the appropriate framework or features, please send us an email.

To run the Scanbot SDK plugin functionality within your production app, you have to purchase and use a valid Scanbot SDK license. The SDK will run for one minute in trial mode without a license.

const myLicenseKey = "";
scanbotSDK = await ScanbotSDK.initialize({
    licenseKey: myLicenseKey
});

Leave the license key empty to enter the trial mode of one minute.

To get a free 7-day trial license, please submit the trial license form.

The initializer also serves as the main entry point of the SDK, meaning that the scanbotSDK object returned upon initialize serves as your entry point to use any other SDK features.

Initialization location & timing

React

In your class-based client-side React project, you should initialize the SDK in the componentDidMount lifecycle method of your App.tsx component:

override async componentDidMount(): Promise<void> {
    const sdk = await ScanbotSDK.initialize({ licenseKey: myLicenseKey, enginePath: "see below" });
}

If you're using functional components, make use of the useEffect hook:

useEffect(() => {
    (async () => {
        const sdk = await ScanbotSDK.initialize({ licenseKey: myLicenseKey, enginePath: "see below" });
    })();
}, []);

Angular

In your Angular project, you have the option to initialize Scanbot SDK in the ngOnInit lifecycle method of your AppComponent:

async ngOnInit(): Promise<void> {
    await ScanbotSDK.initialize({ licenseKey: myLicenseKey, enginePath: "see below" });
}

However, in keeping more with the Angular way of doing things, you could also create an injectable service:

@Injectable()
export class ScanbotSdkService {
    public sdk: ScanbotSDK;

    constructor() {
        ScanbotSDK.initialize({ licenseKey: myLicenseKey, enginePath: "see below" }).then((result) => {
            this.sdk = result;
        });
    }
}

Then, you can inject this service into any component you need to use the SDK via:

@Component({
  selector: "app-root",
  templateUrl: "./app.component.html",
  styleUrls: ["./app.component.scss"],
})
export class AppComponent {
  SDK: ScanbotSdkService;

  router: Router;

  constructor(_router: Router, _sdk: ScanbotSdkService) {
    this.router = _router;
    this.SDK = _sdk;
  }
  ...
}

Vanilla JavaScript

If you're using vanilla JavaScript, you first need to download the SDK files. This can be done as follows:

mkdir -p scanbot-web-sdk/
cd scanbot-web-sdk
npm pack scanbot-web-sdk
tar -xf scanbot-web-sdk-*.tgz --strip-components=2 package/bundle
rm scanbot-web-sdk-*.tgz

The SDK files are now in the scanbot-web-sdk directory. You can add the SDK to your HTML page by adding the following script tag:

<script src="scanbot-web-sdk/ScanbotSDK.min.js"></script>

Then you can initialize the SDK in the window.onload function:

window.onload = async () => {
    scanbotSDK = await ScanbotSDK.initialize({ licenseKey: myLicenseKey, enginePath: "see below" });
}

Vue.js

In Vue.js, you have the option to create globally available objects via its provide-inject API.

First, you initialize the SDK in your main.ts file and provide it to the app:

const app = createApp(App)
const scanbotSDK = ScanbotSDK.initialize({ licenseKey: myLicenseKey, engine: enginePath });
app.provide("scanbotSDK", scanbotSDK);

And then you can have it available in any component via the inject function:

import { inject, onMounted } from "vue";
const scanbotSDK: Promise<ScanbotSDK> = inject("scanbotSDK")!;

And then initialize it after the component is mounted:

import { inject, onMounted } from "vue";
onMounted(async () => {
    const SDK =  await scanbotSDK;
});

Note that it's also possible to await the Scanbot SDK injection immediately, but deferring the SDK initialization to after the component has been mounted generally leads to a better user experience.

Also note that it's possible to immediately await the Scanbot SDK initialization in main.ts. However, that will increase the initial load time.

Next.js

Next.js is React-based, therefore initialization is similar to React, in the lifecycle methods componentDidMount or useEffect of your page.tsx, but with the caveat that you do not want the server bundle to contain the SDK, as that will drastically increase initial page load time. As such, we import the SDK dynamically inline:

override async componentDidMount(): Promise<void> {
    const reference = (await import('scanbot-web-sdk')).default;
    const sdk = await reference.initialize({ licenseKey: myLicenseKey, enginePath: "see below" });
}

useEffect(() => {
    (async () => {
        const reference = (await import('scanbot-web-sdk')).default;
        const sdk = await reference.initialize({ licenseKey: myLicenseKey, enginePath: "see below" });
    });
}, []);

Svelte

Svelte is similar to Next.js in terms of that it's a server-side rendering (SSR) framework and similar to Vue.js in terms of its onMount API.

As such, you want to make sure the SDK is not bundled into the SSR bundle, as that will drastically increase the initial page load time.

This is why we import the SDK dynamically inline. After that, initialize the SDK as you normally would, in your main +page.svelte>:

import { onMount } from 'svelte';

onMount(async () => {
    const reference = (await import('scanbot-web-sdk')).default;
    const sdk = await reference.initialize({ myLicenseKey: '' });
});

Engine flavor & location

The SDK needs additional JS and WASM files during runtime. These files will be loaded by the browser when the SDK is initialized.

During initialization, you need to specify the enginePath to point the browser to a location where it can download these files.

Assuming the files are available in the /wasm/ folder, you can initialize the SDK as follows:

scanbotSDK = await ScanbotSDK.initialize({
    // ...
    enginePath: "/wasm/"
});

The SDK WASM files come in three different flavors: complete, barcode-scanner, and document-scanner. Note that the WASM file sizes for the complete flavor are larger than for the other flavors.

You should only use the complete flavor if the features you need are not entirely covered by the barcode-scanner or document-scanner flavors.

The following table shows the features covered by each flavor:

Feature	complete	barcode-scanner	document-scanner
Barcode Scanner	✅	✅	❌
Document Scanner	✅	❌	✅
Image filters	✅	❌	✅
Document Quality Analyzer	✅	❌	✅
PDF generation	✅	❌	✅
TIFF generation	✅	❌	❌
Text Pattern Scanner	✅	❌	❌
MRZ Scanner	✅	❌	❌
Document Data Extractor	✅	❌	❌
VIN Scanner	✅	❌	❌
Check Scanner	✅	❌	❌

You need to make sure that the engine files are accessible by the browser. How to do this depends your project setup.

In the following sections, we provide examples for some common setups.

Option 1: Public folder

You can provide the engine files to the browser by placing them in a public folder that your web server can serve.

If you installed the SDK via npm, you can obtain the engine files from the node_modules folder. Assuming your public folder is public/wasm, you can copy the engine files as follows:

cp -R node_modules/scanbot-web-sdk/bundle/bin/barcode-scanner/* public/wasm/

You can add this command to your npm postinstall scripts to automatically copy the engine files after installing updates to the SDK.

If you are not using npm in your project, you can still use npm as a one-time command to download the binaries:

# Use npm pack to download the SDK package as a tarball
npm pack scanbot-web-sdk

# Extract the tarball to get the engine files
tar -xf scanbot-web-sdk-*.tgz

Option 2: Webpack

For webpack-based projects, you can use the CopyWebpackPlugin (webpack 5 and newer) or the File-Loader Plugin (webpack 4 and older) to copy the necessary files to the public folder.

Please refer to the respective documentation for more information on how to use these plugins.

Option 3: Vite

For Vite-based projects, you can use the vite-plugin-static-copy plugin to automatically copy the necessary files to the public folder.

After installing this plugin, extend your vite.config.js as follows:

export default defineConfig({
   // ...,
  plugins: [
    // ...,
    viteStaticCopy({
      // Make the files necessary for running the Scanbot SDK WebAssembly modules available as static files
      targets: [
        {
          src: 'node_modules/scanbot-web-sdk/bundle/bin/complete/*',
          dest: 'wasm'
        }
      ],
      structured: false
    })
  ],
  // ...
})

License check in production apps

If your Scanbot SDK license has expired, any call to the Scanbot SDK API will terminate your app or result in an error.

To prevent this, you should always check for license expiration during the runtime by calling the method scanbotSDK.getLicenseInfo().

This method returns a LicenseInfo object as a result. You can use the method isValid() to check validity of the license.

const licenseInfo = await scanbotSDK.getLicenseInfo();
const isValid = licenseInfo.isValid();

if (isValid) {
    // You can now safely make calls to Scanbot SDK API
}

If the result of the isValid() method returns false, you should disable any usage of the Scanbot SDK functions or UI components in your app.

class LicenseInfo {
    // String representing the license status, e.g. "OKAY", "TRIAL", "FAILURE_NOT_SET".
    status: LicenseStatus;
    // Human-readable description for the status
    licenseStatusMessage: string;
    // When your license will expire, seconds since epoch
    expirationTimestamp: number;
    // Returns true only if the status equals Okay or Trial.
    // The license status changes to FailureNotSet when the trial period is over.
    isValid(): boolean;
}

Cache busting

When updating to the latest version of the SDK, we want to avoid any issues arising from browsers caching resources. To this end, we use a cache-busting mechanism that appends a request parameter to the requests of any resources loaded by the SDK. E.g., by default, we request the file ScanbotSDK.Asm.wasm as ScanbotSDK.Asm.wasm?VERSION (where the VERSION is the current version of the SDK). This behavior can be configured or disabled using the requestSuffix config option during SDK initialization.

scanbotSDK = await ScanbotSDK.initialize({
    requestSuffix: "?v=1.2.3"
});

The parameter requestSuffix defaults to ?VERSION, where VERSION is the current version of the SDK.

Content-Security-Policy header

If your site uses a Content-Security-Policy (CSP) header, you need to allow the following resources:

• script-src needs to allow:
  • wasm-unsafe-eval
  • The scripts that are inside the enginePath directory (see above). E.g., if you load the SDK from the same domain as your HTML page, this could be covered by 'self' or your domain name.
• worker-src needs to allow:
  • blob:
  • data:
  • The scripts that are inside the enginePath directory (see above), same as for script-src.

Here is an example of a CSP header that allows the Scanbot SDK to work:

Content-Security-Policy: script-src 'self' 'wasm-unsafe-eval'; worker-src 'self' blob: data:;
``

Want to scan longer than one minute?

Generate a free trial license to test the Scanbot SDK thoroughly.

Get free trial license

Scanbot SDK is part of the Apryse SDK product family

A mobile scan is just the start. With Apryse SDKs, you can expand mobile workflows into full cross‑platform document processing. Whether you need to edit PDFs, add secure digital signatures, or use a fast, customizable document viewer and editor, Apryse gives you the tools to build powerful features quickly.

Learn more

Was this helpful?