Skip to main content

Installation

This page describes how to integrate the Scandit Data Capture SDK into your web project. You can add the Scandit Data Capture SDK Web packages in two ways: as an external resource from a CDN in HTML, or as a package dependency via npm.

Scandit Data Capture SDKs are distributed as npm packages.

You need to add the scandit-web-datacapture-core package, which contains the shared functionality used by the other data capture packages.

If you’re using barcodecapture-related functionalities, make sure to also add the scandit-web-datacapture-barcode package. In addition you need a add scandit-web-datacapture-id - the ScanditIdCapture API - if you want to scan personal identification documents, such as identity cards, passports or visas.

note

You can safely remove barcode or id dependencies if you are not going to use their features.

Prerequisites​

Before you begin, make sure you have the following prerequisites in place:

  • The latest stable version of Node.js and npm (required only if including and building the SDK as part of an app, instead of just including it as an external resource from a CDN in HTML).
  • Valid Scandit Data Capture SDK license, sign up for a free trial if you don't already have a license key
warning

Devices running the Scandit Data Capture SDK need to have a GPU and run a browser capable of making it available (requires WebGL - current support? and OffscreenCanvas - current support?) or the performance will drastically decrease.

CDN​

You can use the jsDelivr or UNPKG CDN to specify a certain version (range) and include and import from our library as follows (example for barcode capture):

<!-- polyfill browsers not supporting import maps. use the latest version from here https://github.com/guybedford/es-module-shims -->
<script async src="https://ga.jspm.io/npm:es-module-shims@1.10.0/dist/es-module-shims.js"></script>
<script type="importmap">
    {
      "imports": {
        "scandit-web-datacapture-core": "https://cdn.jsdelivr.net/npm/scandit-web-datacapture-core@[version]/build/js/index.js",
        "scandit-web-datacapture-barcode": "https://cdn.jsdelivr.net/npm/scandit-web-datacapture-barcode@[version]/build/js/index.js",
        "scandit-web-datacapture-barcode/": "https://cdn.jsdelivr.net/npm/scandit-web-datacapture-barcode@[version]/",
        "scandit-web-datacapture-core/": "https://cdn.jsdelivr.net/npm/scandit-web-datacapture-core@[version]/"
      }
    }
</script>

<script type="module">
 // Import only needed items
 import { DataCaptureContext, Camera } from 'scandit-web-datacapture-core';
 import { BarcodeCapture } from 'scandit-web-datacapture-barcode';
 
 // OR import everything
 import * as SDCCore from 'scandit-web-datacapture-core';
 import * as SDCBarcode from 'scandit-web-datacapture-barcode'; 

 // Insert your code here
</script>
note

The alternative link(s) for UNPKG are be here for Core and here for Barcode.

Alternatively, you can also put the same JavaScript/TypeScript code in a separate file via:

<script type="module" src="script.js"></script>

npm​

To add the packages via npm, you run the following command from your project’s root folder:

npm install --save scandit-web-datacapture-core scandit-web-datacapture-barcode
note

You can also specify a version @<version>.

Then import the package in your JavaScript/TypeScript code by using:

// Import everything
import * as SDCCore from 'scandit-web-datacapture-core';
import * as SDCBarcode from 'scandit-web-datacapture-barcode';

// And/or import only needed items (examples)
import { DataCaptureContext, Camera } from 'scandit-web-datacapture-core';
import { BarcodeCapture } from 'scandit-web-datacapture-barcode';

// Insert your code here

Additional Information

note

When using the Scandit Data Capture SDK you will want to set the camera as the frame source for various capture modes. The camera permissions are handled by the browser, can only be granted if a secure context is used and have to be accepted by the user explicitly when needed.

For Progressive Web App(PWA)​

You can easily configure the scanner to work offline making the web app progressive (Progressive Web App). There are some settings to consider though. If you use workbox , or you’re using a tool that use workbox under the hood like Vite PWA , you must consider to set these options:

{
  globPatterns: ["**/*.{css,html,ico,png,svg,woff2}", "**/*.{wasm,js}"], // Be sure to add also .wasm
  maximumFileSizeToCacheInBytes: 6 * 1024 * 1024, // Increase size cache up to 6mb
  ignoreURLParametersMatching: [/^v/], // Ignore ?v=x.x.x query string param when using importScripts
}

With these settings in place and the service worker correctly configured, you will be able to have a full offline scanning experience.

warning

On iOS there’s a persisting issue while accessing the video stream inside a progressive web app.

Electron​

You can easily configure the web sdk to work into an Electron app. There are some extra steps though. The register method must be called inside the main.ts file passing down some dependencies and the publicKey. The publicKey will be used to decrypt the encrypted license key file that must be placed into the ConfigureOptions.licenseDataPath option:

// electron main.ts
import { register, unregister } from 'scandit-web-datacapture-core/build/electron/main';
import { app, BrowserWindow, ipcMain } from 'electron';
import fs from 'node:fs/promises';
import crypto from 'node:crypto';
import path from 'node:path';

const mainWindow = new BrowserWindow({
    ...,
});

register({ fs, ipcMain, app, path, crypto }, publicKey);

app.on('window-all-closed', () => {
  if (process.platform !== 'darwin') {
    app.quit()
    unregister()
  }
});
// preload.ts
import { ipcRenderer } from 'electron';
import { preloadBindings } from 'scandit-web-datacapture-core/build/electron/preload';
preloadBindings(ipcRenderer);
// renderer.ts
await configure({
  // in Electron context the license will be decrypted internally.
  // The path of the encrypted file is path.join(app.getAppPath(), licenseDataPath)
  licenseDataPath: './out/renderer/data/sdc-license.data',
  libraryLocation: new URL('library/engine/', document.baseURI).toString(),
  moduleLoaders: [barcodeCaptureLoader()]
});

You can easily encrypt your license key with this small nodejs script. Then you should copy the sdc-license.data file in the licenseDataPath in order to be correctly read at runtime in the configure phase. You can also check the related sample.

const crypto = require('node:crypto')
const fs = require('node:fs/promises')

;(async function createLicenseAndPublicKey() {

  const data = process.env.SDC_LICENSE_KEY
  if (data == null || data === '') {
    throw new Error('could not encrypt empty or null string')
  }

  const key = crypto.randomBytes(32)
  const iv = crypto.randomBytes(16)
  const keyAndIV = `${key.toString('base64')}:${iv.toString('base64')}`

  const cipher = crypto.createCipheriv('aes-256-cbc', key, iv)
  let encryptedText = cipher.update(text, 'utf8', 'hex')
  encryptedText += cipher.final('hex')

  await fs.writeFile('sdc-license.data', Buffer.from(encryptedText), 'utf8')
  // Save the key to a file
  await fs.writeFile(
    'sdc-public-key',
    keyAndIV,
    'utf8'
  )
})();
warning

It is recommended to NOT store the public key locally. We also recommended you enable source code protection with bytenode.