Skip to main content

Vehicle Identification Number (VIN) Scanner | Web Document Scanner

The Scanbot SDK provides the ability to scan and verify Vehicle Identification Numbers (VIN). As the result of scanning, the user gets the VIN that was extracted from the frame.

Integrating the VIN Scanner UI​

Scanbot SDK VIN Scanner takes an instance of VINScannerConfiguration as its argument. This is your main object for configuration options, styling and receiving the results.

VINScannerConfiguration has the following base options, which are similar to the ones found on the other scanners:

  • containerId – The id of the containing HTML element where the VIN Scanner will be initialized. Required
  • mirrored - Whether the screen should be mirrored. Useful when using a user-facing camera. Optional, false by default
  • preferredCamera - Camera label or camera device id. If not available, a default camera is used as fallback
  • onError – Callback when something went wrong. Optional

Additionally, VINScannerConfiguration has the following options specific for VIN scanning:

  • onTextDetected?: (e: TextDataScannerResult) => void – Your callback function for receiving detection results
  • ocrResolutionLimit?: number - The image will be downscaled to the given value during the processing. This variable affects the performance of the scanning process. The higher the size limit - the better the quality, but the recognition is slower. 0 for no rescaling. Optional, 0 by default
  • style?: ViewFinderConfiguration - Controls the visual appearance of the scanner. See the Styling section below for details. Optional

The user gets the TextDataScannerResult through onTextDetected callback, that contains the following fields:

text?: string; // Resulting VIN-text
confidence?: number; // The confidence value of the recognized text, from low to high, 0 to 1
validated?: boolean; // If true, the scanner captured the same text across multiple frames

Styling​

Scanbot SDK VIN Scanner has the following style options (default values shown):

configuration.style = {
    window: {
        aspectRatio: 6,
        widthProportion: 0.8,
        borderColor: "white",
        left: "50%",
        top: "50%",
        transform: "translate(-50%, -50%)",
        width: undefined,
        height: undefined
    },
    text: {
        color: "white",
        size: "0.9em",
        weight: 300
    },
    hint: "Please hold the device over the vehicle identification number to start scanning",
    backgroundColor: "rgba(0, 0, 0, 0.7)"
}

The window element is used to configure the viewfinder.

  • width and height elements can be used for configuring the size of the viewfinder in pixels. However, aspectRatio and widthProportion elements can be used for configuring the size of the viewfinder in a more responsive way.
  • aspectRatio specifies the aspect ratio as width/height.
  • widthProportion specifies the proportional length of the viewfinder. (1 means full length of the visible area of the scanner.)

To change only a specific styling attribute, the style configuration option can be set partially, e.g.:

configuration.style = { window: { borderColor: "pink" } };

Opening the Scanner​

To open the VIN Scanner, simply call the relevant SDK function with the configuration object:

const configuration = {
    containerId: VIN_SCANNER_CONTAINER,
    onTextDetected: onTextDetected,
    onError: onError
};

const scanner = await scanbotSDK.createVINScanner(configuration);

You should store the VIN Scanner object in a globally accessible location, as additional VIN Scanner actions are functions of that object.

API​

To handle VIN Scanner results, ScanbotSDK offers the following convenient methods to pause and resume detection while you are processing the VIN data on your side:

resumeDetection(): void;
pauseDetection(): void;
isDetectionPaused(): boolean;

Switching between the front and rear camera​

swapCameraFacing(force?: boolean): void;

swapCameraFacing(true) indicates that only the swapped camera (e.g. front camera) is acceptable; if the swapped camera is not available, or the user declines the permission to use that camera, the media request will fail.

danger

Firefox on Android: Due to current Firefox browser limitations, we highly recommend checking the running browser and disabling this feature for Firebox browsers.

Switching to a specific available camera​

fetchAvailableCameras(): Promise<CameraInfo[]>;
switchCamera(deviceId: string, mirrored?: boolean): void;
getActiveCameraInfo(): CameraInfo | undefined;
interface CameraInfo {
    deviceId: string;
    label: string;
    facingMode?: CameraFacingMode;
    supportsTorchControl?: boolean;
}

type CameraFacingMode = 'front' | 'back' | 'unknown';

You can search for available cameras on the running browser by using fetchAvailableCameras method of a scanner. You can retrieve the label, device id and the camera facing mode information of the active camera of a scanner by using getActiveCameraInfo method. And, you can switch to another available camera by utilizing its device id, by using switchCamera method.

const cameras = await scanner.fetchAvailableCameras()
    if (cameras) {
      const currentCameraInfo = scanner.getActiveCameraInfo();
      if (currentCameraInfo) {
        const cameraIndex = cameras.findIndex((cameraInfo) => { return cameraInfo.deviceId == currentCameraInfo.deviceId });
        const newCameraIndex = (cameraIndex + 1) % (cameras.length);

        scanner.switchCamera(cameras[newCameraIndex].deviceId);
      }
    }

Controlling the torch (flashlight)​

On some mobile devices, the browser can control the torch (flashlight). Check scanner.getActiveCameraInfo().supportsTorchControl to see if the browser can control the torch for the currently active camera. If true, you can control the torch by using the setTorchState method of the scanner.

setTorchState(state: boolean): Promise<void>;
info

On Android devices, only Chrome supports torch control. Starting with iOS 17.4, all supported browsers on iOS offer torch control functionality.

Disposal​

As with the other scanners of Scanbot SDK, the VIN Scanner should also be properly disposed of when you have detected and processed the relevant VIN data:

await scanner.dispose();

Want to scan longer than one minute?

Generate your free "no-strings-attached" Trial License and properly test the Scanbot SDK.

Get your free Trial License

What do you think of this documentation?

On this page

Scroll to top