Migrate from 1.x to 4.x

This guide explains how to migrate your Scandit SDK for the Web implementation from 1.x to 4.x.

Overview

There was only one breaking change between 1.x and 2.x as stated in our release notes:

• BarcodePicker.resumeScanning() function now returns a promise resolving to the object instance instead of directly to the instance; this is due to the fact that the method might need to access the camera again.

In addition to this, there were two breaking changes between 2.x and 3.x:

• UnsupportedBrowserError now has a new data property containing more details regarding the compatibility level of the used OS/browser in a new BrowserCompatibility object. The message property in the error object is now always the same generic message.
• Deprecated errors of type SourceUnavailableError that can happen on some older browsers when accessing the camera are now automatically mapped to the more recent type: NotReadableError.

Moreover, there were also two breaking changes between 3.x and 4.x:

• Removed ScanditSDK.configure()'s preloadCameras and preloadEngineLibrary options and ScanditSDK.loadEngineLibrary() function. Their functionality has been superseded by the (already previously existing) better possibility of calling ScanditSDK.CameraAccess.getCameras()(camera preloading) or creating and reusing a BarcodePicker/Scanner object in the background (engine library preloading); as explained in the README file.
• Replaced CameraSettings.ResolutionPreference numerical enumeration values in favor of string values for optional easier JavaScript usage (ex. CameraSettings.ResolutionPreference.FULL_HD is now "full-hd" instead of 0).

You will find below a more detailed description of how to change your code for each of these changes:

• BarcodePicker.resumeScanning()
• UnsupportedBrowserError changes
• SourceUnavailableError deprecation
• ScanditSDK.configure() options
• CameraSettings.ResolutionPreference enumeration

BarcodePicker.resumeScanning()

If you previously relied on the BarcodePicker instance returned directly from the BarcodePicker.resumeScanning() method you should now use the instance given by the method’s returned promise’s resolution instead. See the following example scenarios.

Old 3.x code:

var updatedBarcodePicker = barcodePicker.resumeScanning();

New 4.x code:

var updatedBarcodePicker;
barcodePicker.resumeScanning().then(function(barcodePicker) {
  updatedBarcodePicker = barcodePicker;
});
// Or (valid inside an async function)
var updatedBarcodePicker = await barcodePicker.resumeScanning();

Old 3.x code:

barcodePicker.resumeScanning().setVisible(true);

New 4.x code:

barcodePicker.resumeScanning().then(function(barcodePicker) {
  barcodePicker.setVisible(true);
});

Or (valid inside an async function):

await barcodePicker.resumeScanning();
barcodePicker.setVisible(true);

UnsupportedBrowserError changes

If you used UnsupportedBrowserError’s message property to get more detailed information about the compatibility level of the used OS/browser by checking string elements, then your code needs to be changed to use the BrowserCompatibility object given in the new data property of the error. Please refer to the documentation at https://docs.scandit.com/stable/web/modules/browsercompatibility.html to learn about the structure and all the information available in the object.

SourceUnavailableError deprecation

If you previously relied on checking whether an error thrown/rejected by the library was of type SourceUnavailableError to detect when an older browser would have issues accessing the camera, then your code needs to be changed to check for the more recent error type NotReadableError instead. The meaning of the error remains the same.

ScanditSDK.configure() options

The preloadEngineLibrary and preloadCameras options for the configure() function became obsolete and should be replaced by other (better performing) means. The options are ignored if they are still passed in newer versions of the library.

Old 3.x code:

ScanditSDK.configure(licenseKey: "my_license_key", {
  engineLocation: "build/",
  preloadEngineLibrary: true,
  preloadCameras: true
})

New 4.x code:

ScanditSDK.configure(licenseKey: "my_license_key", {
  engineLocation: "build/"
})

If you used preloadCameras: false or preloadEngineLibrary: false, then nothing needs to be done.

If you used preloadCameras: true, you can achieve the same behavior in 4.x by calling wherever needed in your code the following (only needed once, before a barcode picker is created):

ScanditSDK.CameraAccess.getCameras()

This will ask user permission if needed and cache the list of available cameras for later use.

If you used preloadEngineLibrary: true, you can achieve similar results (actually much better regarding speed optimization) in 4.x by creating a background (hidden and paused) BarcodePicker after the ScanditSDK.configure() function has resolved and using it later when needed. This is the recommended way to use the library and preload resources whenever a BarcodePicker is not immediately needed. A simple example follows:

var barcodePicker = ScanditSDK.BarcodePicker.create(
  document.getElementById("scandit-barcode-picker"),
  {
    accessCamera: false,
    visible: false
  }
);
[...]
barcodePicker.accessCamera().then(function() {
  barcodePicker.setVisible(true);
});

For instant scanning capabilities you could also instead do the following (keeping the camera active all the time):

var barcodePicker = ScanditSDK.BarcodePicker.create(
  document.getElementById("scandit-barcode-picker"),
  {
    scanningPaused: true,
    visible: false
  }
);
[...]
barcodePicker.resumeScanning().then(function() {
  barcodePicker.setVisible(true);
});

Please refer to the readme file and main documentation for more details. For a sample application, please refer to the example_background.html file included in the library.

CameraSettings.ResolutionPreference enumeration

If you used the CameraSettings.ResolutionPreference enumeration by using (as recommended) its members like CameraSettings.ResolutionPreference.HD, then nothing needs to be done.

If you used CameraSettings.ResolutionPreference mapped enumeration values directly (not recommended) by using numbers like 1, then your code needs to be changed to use the needed enumeration members like CameraSettings.ResolutionPreference.HD or its new string mapped values like "hd".