SDK Initialization | Web Document 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 });
}

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

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

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 });
}

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() {
        this.sdk = await ScanbotSDK.initialize({ licenseKey: myLicenseKey });
    }
}

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 should first add the dependency script tag to the end your main index.html:

<script src="https://cdn.jsdelivr.net/npm/scanbot-web-sdk@latest/bundle/ScanbotSDK.min.js"></script>

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

window.onload = async () => {
    scanbotSDK = await ScanbotSDK.initialize({ licenseKey: myLicenseKey });
}

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 });
}

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

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 Location

Specifying engine can lead to a smaller SDK size and better performance. Scanbot Barcode-scanner-only binary will be approximately 3x smaller than the full SDK.

If you only use specific features of the SDK, e.g. barcode scanning, you can use the barcode only binary within ScanbotSDK's npm package.

In order to do that you can specify the engine location (optional property), as follows:

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

In order to get the barcode scanner binary, you can copy it from the node_modules folder to your public folder. different engines are located in: node_modules/scanbot-web-sdk/bundle/bin/

For example, here is a convenient bash script to copy barcode scanner binary to your public folder:

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

If you're not using npm as your package manager, you can download the correct binaries from our CDN url. Here's a convenient bash script to achieve that:

BASE_URL=https://cdn.jsdelivr.net/npm/scanbot-web-sdk@${VERSION}/bundle/
COMPLETE_WASM_BINARY_URL=${BASE_URL}bin/complete/

curl ${BASE_URL}ScanbotSDK.min.js -o wasm/ScanbotSDK.min.js
curl ${COMPLETE_WASM_BINARY_URL}ScanbotSDK.Asm.wasm -o wasm/ScanbotSDK.Asm.wasm
curl ${COMPLETE_WASM_BINARY_URL}ScanbotSDK.Core.js -o wasm/ScanbotSDK.Core.js

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;
}

Want to scan longer than one minute?

Generate your free "no-strings-attached" Trial License and properly test the Scanbot SDK.

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.

---