Add the SDK to Your App

This guide shows you how to add the Scandit Data Capture SDK to current existing project.

Prerequisites

  • 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).

  • A valid Scandit Data Capture SDK license key. You can sign up for a free test account at ssl.scandit.com.

Note

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.

Get a License Key

  1. Sign up or Sign in to your Scandit account

  2. Create a project

  3. Create a license key

If you have a paid subscription, please reach out to support@scandit.com if you need a new license key.

Add the SDK

Currently we support adding the Scandit Data Capture SDK Web library to your project in two ways. You can either add it as an external resource from a CDN in HTML, or add it as a package dependency via npm to your project to be built.

The scandit-web-datacapture-core npm package is always required and contains the shared functionality used by the other data capture modules. Depending on your use-case, you may then add dependencies to scandit-web-datacapture-barcode to scan barcodes, or scandit-web-datacapture-id to scan ID documents for example. You will find all the npm packages providing data capture functionality under this npm link.

Add the Scandit Data Capture SDK as an external resource

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  -->
<script async src="https://ga.jspm.io/npm:es-module-shims@1.7.3/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"
    }
  }
</script>

<script type="module">
  // 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
</script>

Note

The alternative link(s) for UNPKG would be https://unpkg.com/scandit-web-datacapture-core@6.x and https://unpkg.com/scandit-web-datacapture-barcode@6.x.

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

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

Add the Scandit Data Capture SDK via npm

To add our library via npm, you can run this 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>.

You can then import and use whatever is needed from the library 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

  • 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.

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.

Note: 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:ElectronBarcodeCaptureSimpleSample

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

;(async function createLicenseAndPublicKey() {
  const cryptoKeyPairOptions = {
    modulusLength: 8192,
    publicKeyEncoding: {
      type: 'spki',
      format: 'pem'
    },
    privateKeyEncoding: {
      type: 'pkcs8',
      format: 'pem'
    }
  }
  console.log('Encrypting could take a while...')
  const data = process.env.SDC_LICENSE_KEY
  if (data == null || data === '') {
    throw new Error('could not encrypt empty or null string')
  }
  const { privateKey, publicKey } = crypto.generateKeyPairSync('rsa', cryptoKeyPairOptions)

  const encrypted = crypto.privateEncrypt(privateKey, Buffer.from(data))

  await fs.writeFile('sdc-license.data', encrypted, 'utf8')
  // save it as base64 to facilitate the loading as string
  await fs.writeFile(
    'sdc-public-key',
    Buffer.from(publicKey, 'utf-8').toString('base64')},
    'utf8'
  )
})();

Note

It’s recommended to NOT store the public key locally. It’s also recommended to enable source code protection with bytenode.

Next steps

To add single barcode scanning to your app:

To add ID scanning to your app:

To add multi-barcode scanning to your app: