SDK Initialization | Web Barcode Scanner

Free Developer Support

We provide free "no-strings-attached" developer support for the implementation & 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 visit our Support Page.

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, "no-strings-attached" 7-day trial license, please submit the Trial License Form on our website.

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 ScanbotSDK injection immediately, but it's generally leads to a better user experience when SDK initialization is deferred to after the component has been mounted.

Also note that it's even possible to immediately await ScanbotSDK initialization in

main.ts, however, that will increase 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.

However, with the caveat that you do not want the server bundle to contain the SDK, as that'll 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 that it's a server-side rendering (SSR) framework, and similar to Vue.js in terms of it's onMount API.

As such, you want to make sure the SDK is not bundled into the SSR bundle, as that'll drastically incrase 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 the other flavors. The complete flavor should only be used if the features you need are not all 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	✅	❌	✅
PDF Generation	✅	❌	✅
TIFF Generation	✅	❌	❌
Text Data Scanner	✅	❌	❌
VIN Scanner	✅	❌	❌
MRZ Recognizer	✅	❌	❌
Document Quality Analyzer	✅	❌	✅

You need to make sure that the engine files are accessible by the browser. How to do this is dependent on your project setup. In the following, 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 {
    // Okay, Trial, FailureNotSet, FailureCorrupted, 
    // FailureWrongOS, FailureAppIDMismatch, FailureExpired
    status: string;
    // Human-readable description for the status
    description: string;
    // 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.

Want to scan longer than one minute?

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

Get your free Trial License

What do you think of this documentation?

What can we do to improve it? Please be as detailed as you like.

---