How to Upgrade DBR-JS from v9.x to v10.x

Version 10 of the Dynamsoft Barcode Reader JavaScript edition has undergone a comprehensive overhaul to align with the Dynamsoft Capture Vision architecture. To understand the advantages of this new architecture, please refer to these resources:

Additionally, it’s important to note that Dynamsoft’s ongoing enhancements will be based on this updated architecture. By upgrading to version 10 and adopting the new framework concurrently, you will gain access to the latest features and enhanced performance.

Due to these significant changes, a substantial rewrite of your existing code will be necessary to transition to the new version. This document will provide guidance throughout this upgrading process.

NOTE

In this guide, we assume the following

The BarcodeReader or BarcodeScanner instance is called reader or scanner respectively;

The CaptureVisionRouter instance is called cvRouter;

The CameraEnhancer instance is called cameraEnhancer;

The CameraView instance is called cameraView.

Change the way to reference the SDK

In version 9.x, you only need one line of code:

<script src="https://cdn.jsdelivr.net/npm/dynamsoft-javascript-barcode@9.6.42/dist/dbr.js"></script>

In version 10.x, you need to reference several modules:

<script src="https://cdn.jsdelivr.net/npm/dynamsoft-core@3.4.20/dist/core.js"></script>
<script src="https://cdn.jsdelivr.net/npm/dynamsoft-license@3.4.21/dist/license.js"></script>
<script src="https://cdn.jsdelivr.net/npm/dynamsoft-utility@1.4.20/dist/utility.js"></script>
<script src="https://cdn.jsdelivr.net/npm/dynamsoft-barcode-reader@10.4.20/dist/dbr.js"></script>
<script src="https://cdn.jsdelivr.net/npm/dynamsoft-capture-vision-router@2.4.21/dist/cvr.js"></script>
<script src="https://cdn.jsdelivr.net/npm/dynamsoft-camera-enhancer@4.1.0/dist/dce.js"></script>

In version 10.0.21 and above, you can also just use this line for simplicity:

<script src="https://cdn.jsdelivr.net/npm/dynamsoft-barcode-reader-bundle@10.4.2001/dist/dbr.bundle.js"></script>

Change the APIs for initializing

License

IMPORTANT INFORMATION

Users with a time-limited license for version 8 or newer can utilize their existing license for version 10. However, if you possess a permanent license or a time-limited license for version 7 or earlier, a license update may be required. For further details, please reach out to Dynamsoft Sales.

In version 10, license control is taken over by the “License” module:

API in v9.x	API in v10.x
`Dynamsoft.DBR.BarcodeReader.license`	Dynamsoft.License.LicenseManager.initLicense()
`Dynamsoft.DBR.BarcodeReader.deviceFriendlyName`	Dynamsoft.License.LicenseManager.setDeviceFriendlyName()

The new module also added the following method:

Dynamsoft.License.LicenseManager.getDeviceUUID()

Others

APIs for setting up the SDK have been taken over by the new classes CaptureVisionRouter, CaptureVisionRouterModule or BarcodeReaderModule:

API in v9.x	API in v10.x
`Dynamsoft.DBR.BarcodeReader.engineResourcePath` or `Dynamsoft.DBR.BarcodeScanner.engineResourcePath`	Dynamsoft.Core.CoreModule.engineResourcePaths
`Dynamsoft.DBR.BarcodeReader.loadWasm()` or `Dynamsoft.DBR.BarcodeScanner.loadWasm()`	Dynamsoft.Core.CoreModule.loadWasm([“cvr”, “dbr”])
`Dynamsoft.DBR.BarcodeReader.isWasmLoaded()` or `Dynamsoft.DBR.BarcodeScanner.isWasmLoaded()`	Dynamsoft.Core.CoreModule.isModuleLoaded(‘dbr’)
`Dynamsoft.DBR.BarcodeReader.version` or `Dynamsoft.DBR.BarcodeScanner.version`	Dynamsoft.DBR.BarcodeReaderModule.getVersion()
`Dynamsoft.DBR.BarcodeReader.detectEnvironment()` or `Dynamsoft.DBR.BarcodeScanner.detectEnvironment()`	Dynamsoft.Core.CoreModule.detectEnvironment()
`Dynamsoft.DBR.BarcodeReader.onWarning` or `Dynamsoft.DBR.BarcodeScanner.onWarning`	Dynamsoft.Core.CoreModule.onWarning and Dynamsoft.DCE.CameraEnhancer.onWarning
`Dynamsoft.DBR.BarcodeReader.createInstance()`or `Dynamsoft.DBR.BarcodeScanner.createInstance()`	Dynamsoft.CVR.CaptureVisionRouter.createInstance()

API in v9.x	API in v10.x
`reader.destroyContext()` or `scanner.destroyContext()`	cvRouter.dispose()
`reader.isContextDestroyed()` or `scanner.isContextDestroyed()`	cvRouter.disposed

Change the APIs for image processing

Single-Image processing

API in v9.x	API in v10.x
`reader.decode()` or `scanner.decode()`	cvRouter.capture() that specifies a template for barcode reading.

Multiple-Image processing

API in v9.x	API in v10.x
`reader.setImageSource()`	cvRouter.setInput()
`reader.onImageRead` or `scanner.onFrameRead`	`let resultReceiver = new Dynamsoft.CVR.CapturedResultReceiver();` `resultReceiver.onDecodedBarcodesReceived = result => { };` `cvRouter.addResultReceiver(resultReceiver)`
`reader.onUniqueRead` or `scanner.onUniqueRead`	`let filter = new MultiFrameResultCrossFilter();` `filter.enableResultDeduplication(EnumCapturedResultItemType.CRIT_BARCODE, true);` `cvRouter.addResultFilter(filter);` `let resultReceiver = new Dynamsoft.CVR.CapturedResultReceiver();` `resultReceiver.onDecodedBarcodesReceived = result => { };` `cvRouter.addResultReceiver(resultReceiver);`
`reader.startScanning()` or `scanner.show()`	`let cameraView = await Dynamsoft.DCE.CameraView.createInstance();` `cameraEnhancer = await Dynamsoft.DCE.CameraEnhancer.createInstance(cameraView);` `//"cameraViewContainer" is usually an HTMLDivElement` `cameraViewContainer.append(cameraView.getUIElement());` `cvRouter.setInput(cameraEnhancer);` `cameraEnhancer.open();` `cvRouter.startCapturing("SPECIFY-A-TEMPLATE")`
`reader.stopScanning()` or `scanner.hide()`	cvRouter.stopCapturing() `cameraEnhancer.close();` `cameraViewContainer.style.display = "none"`
`reader.resumeScanning()`	cvRouter.startCapturing(‘SPECIFY-A-TEMPLATE’)

Process Settings

The following assumes ScanSettings is the object returned by reader.getScanSettings() or scanner.getScanSettings() and SimplifiedCaptureVisionSettings is returned by cvRouter.getSimplifiedSettings('SPECIFY-A-TEMPLATE').

API in v9.x	API in v10.x
`reader.getScanSettings()` or `scanner.getScanSettings()`	No equivalent.
`reader.updateScanSettings()` or `scanner.updateScanSettings()`	No equivalent.
`ScanSettings.intervalTime`	SimplifiedCaptureVisionSettings.minImageCaptureInterval
`ScanSettings.duplicateForgetTime`	`let filter = new MultiFrameResultCrossFilter();` `filter.setDuplicateForgetTime();` `cvRouter.addResultFilter(filter)`
`ScanSettings.whenToPlaySoundforSuccessfulRead`	No equivalent. Use Dynamsoft.DCE.Feedback.beep() when appropriate.
`ScanSettings.soundOnSuccessfullRead`	Dynamsoft.DCE.Feedback.beepSoundSource
`ScanSettings.whenToVibrateforSuccessfulRead`	No equivalent. Use Dynamsoft.DCE.Feedback.vibrate() when appropriate.
`ScanSettings.vibrateDuration`	Dynamsoft.DCE.Feedback.vibrateDuration
`ScanSettings.captureAndDecodeInParallel`	Equivalent to setting SimplifiedCaptureVisionSettings.minImageCaptureInterval to -1 or 0.
`ScanSettings.autoZoom`	cameraEnhancer.enableEnhancedFeatures(EnumEnhancedFeatures.EF_AUTO_ZOOM)
`ScanSettings.autoFocus`	cameraEnhancer.enableEnhancedFeatures(EnumEnhancedFeatures.EF_ENHANCED_FOCUS)
`ScanSettings.autoSuggestTip`	No equivalent.

Algorithm Settings

API in v9.x	API in v10.x
`reader.getRuntimeSettings()` or `scanner.getRuntimeSettings()`	cvRouter.getSimplifiedSettings(‘SPECIFY-A-TEMPLATE’)
`reader.initRuntimeSettingsWithString('SPECIFY-A-TEMPLATE-STRING')` or `scanner.initRuntimeSettingsWithString('SPECIFY-A-TEMPLATE-STRING')`	cvRouter.initSettings(‘SPECIFY-A-TEMPLATE-STRING’)
`reader.updateRuntimeSettings('SPECIFY-THE-SETTINGS')` or `scanner.updateRuntimeSettings('SPECIFY-THE-SETTINGS')`	cvRouter.updateSettings(‘SPECIFY-A-TEMPLATE’, ‘SPECIFY-THE-SETTINGS’)
`reader.resetRuntimeSettings()` or `scanner.resetRuntimeSettings()`	cvRouter.resetSettings()
`reader.outputRuntimeSettingsToString()` or `scanner.outputRuntimeSettingsToString()`	Use cvRouter.outputSettings() which returns an object instead of a string.

Change the APIs for user interface customization

API in v9.x	API in v10.x
`scanner.getUIElement()`	cameraView.getUIElement()
`scanner.setUIElement()`	cameraView.setUIElement()
`Dynamsoft.DBR.BarcodeScanner.defaultUIElementURL="THE-URL-TO-THE-HTML"`	Dynamsoft.DCE.CameraView.createInstance(“THE-URL-TO-THE-HTML”)
`scanner.barcodeFillStyle` `scanner.barcodeStrokeStyle` `scanner.barcodeLineWidth`	Change the preset style `STYLE_GREEN_STROKE` (ID = 2).
`scanner.barcodeFillStyleBeforeVerification` `scanner.barcodeStrokeStyleBeforeVerification` `scanner.barcodeLineWidthBeforeVerification`	Change the preset style `STYLE_GREEN_STROKE_TRANSPARENT` (ID = 10).
`scanner.regionMaskFillStyle` `scanner.regionMaskStrokeStyle` `scanner.regionMaskLineWidth`	cameraView.setScanRegionMaskStyle()
`scanner.setVideoFit()`	cameraView.setVideoFit()
`scanner.getVideoFit()`	cameraView.getVideoFit()
`scanner.ifShowScanRegionMask`	cameraView.setScanRegionMaskVisible()

Change the APIs for camera control

API in v9.x	API in v10.x, by the independent `CameraEnhancer` instance
`scanner.open()`	cameraEnhancer.open() cvRouter.startCapturing(‘SPECIFY-A-TEMPLATE’)
`scanner.close()`	cvRouter.stopCapturing() cameraEnhancer.close()
`scanner.isOpen()`	cameraEnhancer.isOpen()
`scanner.singleFrameMode`	cameraEnhancer.singleFrameMode
`scanner.ifSkipCameraInspection`	cameraEnhancer.ifSkipCameraInspection
`scanner.ifSaveLastUsedCamera`	cameraEnhancer.ifSaveLastUsedCamera
`scanner.getAllCameras()`	cameraEnhancer.getAllCameras()
`scanner.getCurrentCamera()`	cameraEnhancer.getSelectedCamera()
`scanner.setCurrentCamera()`	cameraEnhancer.selectCamera()
`scanner.getResolution()`	cameraEnhancer.getResolution()
`scanner.setResolution()`	cameraEnhancer.setResolution()
`scanner.getVideoSettings()`	cameraEnhancer.getVideoSettings()
`scanner.updateVideoSettings()`	cameraEnhancer.updateVideoSettings
`Dynamsoft.DBR.Barcodescanner.testCameraAccess()`	Dynamsoft.DCE.CameraEnhancer.testCameraAccess()
`scanner.play()`	cameraEnhancer.open() or cameraEnhancer.resume() if paused.
`scanner.onPlayed`	cameraEnhancer.on(“played”, fn)
`scanner.pauseScan()`	cvRouter.stopCapturing() while camera is still playing.
`scanner.resumeScan()`	cvRouter.startCapturing(‘SPECIFY-A-TEMPLATE’) when camera is already playing.
`scanner.pause()`	cameraEnhancer.pause()
`scanner.stop()`	cameraEnhancer.close()
`scanner.videoSrc`	cameraEnhancer.videoSrc
`scanner.getCapabilities()`	cameraEnhancer.getCapabilities()
`scanner.getCameraSettings()`	cameraEnhancer.getCameraSettings()
`scanner.getFrameRate()`	cameraEnhancer.getFrameRate()
`scanner.setFrameRate()`	cameraEnhancer.setFrameRate()
`scanner.turnOnTorch()`	cameraEnhancer.turnOnTorch()
`scanner.turnOffTorch()`	cameraEnhancer.turnOffTorch()
`scanner.getZoomSettings()`	cameraEnhancer.getZoomSettings()
`scanner.setZoom()`	cameraEnhancer.setZoom()
`scanner.resetZoom()`	cameraEnhancer.resetZoom()
`scanner.getFocusSettings()`	cameraEnhancer.getFocusSettings()
`scanner.setFocus()`	cameraEnhancer.setFocus()
`scanner.enableTapToFocus()`	cameraEnhancer.enableEnhancedFeatures(EnumEnhancedFeatures.EF_TAP_TO_FOCUS)
`scanner.disableTapToFocus()`	cameraEnhancer.disableEnhancedFeatures(EnumEnhancedFeatures.EF_TAP_TO_FOCUS)
`scanner.isTapToFocusEnabled()`	No equivalent.
`scanner.getColorTemperature()`	cameraEnhancer.getColorTemperature()
`scanner.setColorTemperature()`	cameraEnhancer.setColorTemperature()
`scanner.getExposureCompensation()`	cameraEnhancer.getExposureCompensation()
`scanner.setExposureCompensation()`	cameraEnhancer.setExposureCompensation()

API Changes for RuntimeSettings and Templates

Previously, in v9.x of DBR JS, there were several ways to change the settings of the BarcodeReader or BarcodeScanner instance. The first and most popular was to use the RuntimeSettings interface, and the second was to use JSON Templates. In this section of the upgrade guide, we will detail the API changes that have been made to these two configurations.

Migrate Your Templates

The template system is upgraded. The template you used for the previous version can’t be directly recognized by the new version. Please download the TemplateConverter tool (only Windows) or contact us to upgrade your template.

Once you have the new template, please use the new template-based API as follows:

Old APIs	New APIs
`reader.initRuntimeSettingsWithString()`	cvRouter.initSettings()
`reader.outputRuntimeSettingsToString()`	cvRouter.outputSettings()

Note: Like v9.x, the JavaScript edition of the Barcode Reader only allows for JSON strings to be used as templates. JSON files cannot be used to initiate the settings in the JavaScript edition.

Changes to the RuntimeSettings

The second way in which the settings can be defined in v9.x was to use the RuntimeSettings interface. In v10.x, the RuntimeSettings have been refactored. It retains commonly used properties while removing the previously complex property settings, which are now exclusively supported through templates. The APIs for accessing and updating RuntimeSettings has been adjusted as follows:

Old APIs	New APIs
`scanner.getRuntimeSettings()`	cvRouter.getSimplifiedSettings()
`scanner.updateRuntimeSettings()`	cvRouter.updateSettings()

Migrate to SimplifiedCaptureVisionSettings

The following properties are replaced by similar properties under SimplifiedCaptureVisionSettings. They can also be set via a template string. These properties, compared to the ones in SimplifiedBarcodeReaderSettings that are in the next section, are shared across all of the Capture Vision products, so they are not specific to just the Barcode Reader.

RuntimeSettings Property	SimplifiedCaptureVisionSettings Parameter	Template File Parameter
`region`	`roi` & `roiMeasuredInPercentage`	`TargetROIDef.Location.Offset`
`timeout`	Deprecated and no longer available	Deprecated and no longer available

Migrate to SimplifiedBarcodeReaderSettings

The following properties are replaced by similar properties under SimplifiedBarcodeReaderSettings. The majority of them can also be set via a template file(String).

RuntimeSettings Property	SimplifiedBarcodeReaderSettings Property	Template File Parameter
`minBarcodeTextLength`	`minBarcodeTextLength`	`BarcodeFormatSpecification.BarcodeTextLengthRangeArray`
`minResultConfidence`	`minResultConfidence`	`BarcodeFormatSpecification.MinResultConfidence`
`localizationModes`	`localizationModes`	`BarcodeReaderTaskSetting.LocationModes`
`expectedBarcodesCount`	`expectedBarcodesCount`	`BarcodeReaderTaskSetting.ExpectedBarcodesCount`
`barcodeFormatIds`	`barcodeFormatIds`	`BarcodeReaderTaskSetting.BarcodeFormatIds`
`barcodeFormatIds_2`	`barcodeFormatIds`	`BarcodeReaderTaskSetting.BarcodeFormatIds`
`deblurModes`	`deblurModes`	`BarcodeReaderTaskSetting.DeblurModes`
`deblurLevel`	`deblurModes`	`BarcodeReaderTaskSetting.DeblurModes`
`maxAlgorithmThreadCount`	`maxThreadsInOneTask`	`BarcodeReaderTaskSetting.MaxThreadsInOneTask`

Remarks:

The 2 groups of barcode formats are merged.

DeblurLevel is deprecated. You can use DeblurModes instead.

FurtherModes Property	SimplifiedBarcodeReaderSettings Property	Template File Parameter
`grayscaleTransformationModes`	`grayscaleTransformationModes`	`ImageParameter.GrayscaleTransformationModes`
`imagePreprocessingModes`	`grayscaleEnhancementModes`	`ImageParameter.GrayscaleEnhancementModes`

Remarks: The mode IPM_MORPHOLOGY of imagePreprocessingModes is migrated to BinarizationModes. The mode arguments MorphOperation, MorphOperationKernelSizeX, MorphOperationKernelSizeY, MorphShape are now available for all modes of BinarizationModes.

Migrate to Template

So far, we mentioned the settings that have been included in the SimplifiedCaptureVisionSettings and the SimplifiedBarcodeReaderSettings. However, not all of the RuntimeSettings were moved to either of these interfaces. Some settings have to be defined via a template. Here is a list of all the settings and their corresponding Template File Parameter:

RuntimeSettings Property	Template File Parameter
`scaleDownThreshold`	`ImageParameter.ScaleDownThreshold`
`binarizationModes`	`ImageParameter.BinarizationModes`
`textResultOrderModes`	`BarcodeReaderTaskSetting.TextResultOrderModes`
`returnBarcodeZoneClarity`	`BarcodeReaderTaskSetting.ReturnBarcodeZoneClarity`
`scaleUpModes`	`ImageParameter.ScaleUpModes`
`barcodeZoneMinDistanceToImageBorders`	`BarcodeFormatSpecification.BarcodeZoneMinDistanceToImageBorders`
`terminatePhase`	`BarcodeReaderTaskSetting.TerminateSettings`

FurtherModes Property	Template File Parameter
`colourConversionModes`	`ImageParameter.ColourConversionModes`
`regionPredetectionModes`	`ImageParameter.RegionPredetectionModes`
`textureDetectionModes`	`ImageParameter.TextureDetectionModes`
`textFilterModes`	`ImageParameter.TextDetectionMode` & `ImageParameter.IfEraseTextZone`
`dpmCodeReadingModes`	`BarcodeReaderTaskSetting.DPMCodeReadingModes`
`deformationResistingModes`	`BarcodeReaderTaskSetting.DeformationResistingModes`
`barcodeComplementModes`	`BarcodeReaderTaskSetting.BarcodeComplementModes`
`barcodeColourModes`	`BarcodeReaderTaskSetting.BarcodeColourModes`

Other API changes

API in v9.x	API in v10.x
`scanner.convertToPageCoordinates()`	cameraEnhancer.convertToPageCoordinates()
`scanner.convertToClientCoordinates()`	cameraEnhancer.convertToClientCoordinates()
`scanner.showTip()`	cameraEnhancer.setTipConfig() cameraEnhancer.setTipVisible(true)
`scanner.hideTip()`	cameraEnhancer.setTipVisible(false)
`scanner.onTipSuggested()`	No equivalent.
`scanner.updateTipMessage()`	cameraView.updateTipMessage()
`reader.getModeArgument()` `reader.setModeArgument()`	No equivalent.
`scanner.ifSaveOriginalImageInACanvas` `scanner.getOriginalImageInACanvas()`	`settings = cvRouter.getSimplifiedSettings('SPECIFY-A-TEMPLATE');` `settings.capturedResultItemTypes += Dynamsoft.Core.EnumCapturedResultItemType.CRIT_ORIGINAL_IMAGE;` `await cvRouter.updateSettings("detect-document-boundaries", settings);` `const resultReceiver = new Dynamsoft.CVR.CapturedResultReceiver();` `resultReceiver.onOriginalImageResultReceived = result => { // GET-THE-ORIGINAL-IMAGE //};` `cvRouter.addResultReceiver(resultReceiver)`