This guide explains how to migrate your Scandit SDK for the Web implementation from 4.x to 5.x.
Overview
There were a few breaking changes between 4.x and 5.x as stated in our release notes:
- Removed previously deprecated event listener related functions (like BarcodePicker.onScan(), BarcodePicker.removeScanListener(), BarcodePicker.removeScanErrorListeners(), ...), now replaced by the new syntax functions
- Single Image Mode and Scanner improvements
- scanResult's imageData property changes for improved memory management
- Other minor breaking changes on the following functions: BarcodePicker.setTorchEnabled(), BarcodePicker.setZoom(), SymbologySettings.getActiveSymbolCounts(), SymbologySettings.getEnabledChecksums(), SymbologySettings.getEnabledExtensions().
- The configure() promise now needs to be properly awaited to ensure its completion before further library operations
Removal of deprecated event listener related functions
Use the table below to simply replace the event listener related functions on the BarcodePicker and Scanner objects you use by their newer counterparts.
BarcodePicker listener related functions
|
Previously deprecated function |
Function to be used in 5.x |
|
onReady(...) |
on("ready", ...) |
|
onScan(...) |
on("scan", ...) |
|
onSubmitFrame(...) |
on("submitFrame", ...) |
|
onProcessFrame(...) |
on("processFrame", ...) |
|
onScanError(...) |
on("scanError", ...) |
|
removeScanListener(...) |
removeListener("scan", ...) |
|
removeSubmitFrameListener(...) |
removeListener("submitFrame", ...) |
|
removeProcessFrameListener(...) |
removeListener("processFrame", ...) |
|
removeScanErrorListener(...) |
removeListener("scanError", ...) |
|
removeScanListeners() |
removeAllListeners("scan") |
|
removeSubmitFrameListeners() |
removeAllListeners("submitFrame") |
|
removeProcessFrameListeners() |
removeAllListeners("processFrame") |
Scanner listener related functions
|
Previously deprecated function |
Function to be used in 5.x |
|
onReady(...) |
on("ready", ...) |
|
|
removeListener("ready", ...) |
|
|
removeAllListeners("ready") |
Single Image Mode / Scanner Improvements
SingleImageMode option
The singleImageMode option of the barcodePicker's create() method is now replaced by the singleImageModeSettings option of the same method.
For example,
singleImageMode: {
desktop: { always: false, allowFallback: true },
mobile: { always: true, allowFallback: true }
}
should now be:
singleImageModeSettings: {
desktop: {
usageStrategy: SingleImageModeSettings.UsageStrategy.FALLBACK
},
mobile: {
usageStrategy: SingleImageModeSettings.UsageStrategy.ALWAYS
}
}
Interaction with the Single Image Mode UI and/or Scanner object
If you were interacting with the Single Image Mode UI and/or the Scanner object, be aware of two key changes:
- Single Image Mode's UI has been changed substantially.
- Data passed to Scanner.processImage() is "detached"/"neutered" becoming unusable as it's being passed to the external Scandit Engine library. Note that you can still access the same data once it's returned in the ScanResult object's imageData property as before.
scanResult.imageData changes
We changed the way we handle the scanResult.imageData property to ensure improved memory management. If you were using it, have a look at the below to make sure it does not break your current behavior:
- scanResult.imageData will now be overwritten with the next video frame data after being returned and made available in all submitFrame/processFrame/scan event listeners for the current frame (the underlying data structure is reused). If the data is needed after the listener has finished executing, a copy should be made.
- scanResult.imageData is now given as an Uint8Array (instead of Uint8ClampedArray). In case the old data format is required, the data view (type) can easily be changed with new Uint8ClampedArray(imageData.buffer).
Other breaking changes
In case you were using the following methods, please have a look at the changes to make sure they do not break your app's behavior:
- BarcodePicker.setTorchEnabled() and BarcodePicker.setZoom() functions now return a promise resolving to the BarcodePicker object instance instead of directly the instance; this is due to the fact that the function needs to access the camera again.
- SymbologySettings.getActiveSymbolCounts() now always returns the full list of active symbol counts, also for the default cases.
- SymbologySettings.getEnabledChecksums() now returns all enabled optional checksums, including any default ones.
- SymbologySettings.getEnabledExtensions() now returns all enabled optional extensions, including any default ones.
Proper handling of the configure() promise
This is not strictly speaking a breaking change as the ScanditSDK.configure() method was already a promise expected to be awaited in previous versions. However, 5.x is stricter in the requirement of correctly handling the promise, e.g. adding the rest of the code using our SDK in a .then() after the configure() method has been used (or calling it with await).
Please find below an example:
ScanditSDK.configure("license_key", {engineLocation: "build"})
.then(function() {
ScanditSDK.BarcodePicker.create(...)
...
})
.catch(function(error) {
alert(error);
});