@pixelverse/strichjs-sdk
Version:
STRICH JavaScript Barcode Scanning SDK
1,082 lines (1,054 loc) • 37.7 kB
TypeScript
/**
* Fine-grained audio feedback configuration object
*/
export declare interface AudioFeedbackConfiguration {
/**
* Toggle audible beep upon successful scan.
*
* @remarks
* Uses the WebAudio API to emit a "cash register"-like beep. Beeping is done on a best-effort
* basis and should not be relied upon. If the browser does not support the WebAudio API,
* beeping will not work, and no error will be thrown.
*
* @defaultValue true
*/
enabled?: boolean;
/**
* Explicitly set the AudioSession type used for audible feedback.
*
* See https://github.com/w3c/audio-session/blob/main/explainer.md#api-design for a list of acceptable values.
*
* By default, the value `transient` is used if the AudioSession API is available.
* Setting this value to `null` will disable setting the AudioSession type.
*/
audioSessionType?: string | null;
}
/**
* BarcodeReader is the primary interface of the STRICH SDK.
*/
export declare class BarcodeReader {
/**
* App-supplied barcode detection handler.
*/
detected?: DetectionHandler;
/**
* Optional app-supplied camera selector.
*
* The callback receives a list of available cameras as its argument and must return one of the objects.
* In all other cases, the callback's result will be ignored and the default camera selection logic will apply
*
* The callback must be set before calling {@link BarcodeReader#initialize} to have an effect.
*
* @remarks
* This is an advanced property and should only be used in special circumstances where you really need to
* force a specific camera to be used.
*/
cameraSelector?: CameraSelector;
/**
* Optional app-supplied error callback, invoked by the BarcodeReader if an unexpected error occurred while
* processing frames.
*/
onError?: (error: Error) => (void);
/**
* Create a new BarcodeReader using a {@link Configuration} object.
*
* @remarks
* This will perform some basic checks, such as if the SDK was initialized, the browser supports the required APIs
* and the host element is visible and has a non-zero size. This will not access the camera yet, that happens
* in the {@link BarcodeReader#initialize} method.
*
* @param configuration - A configuration object.
*/
constructor(configuration: Configuration);
/**
* Initialize the BarcodeReader instance.
*
* @remarks
* This will attempt to acquire a camera stream, so it is essential that the returned Promise is awaited, and that
* measures are taken so that the returned BarcodeReader instance is destroyed when it is no longer need. That
* will free the camera stream for subsequent use.
*
* If you are getting camera-related initialization errors, the most likely cause is that you are
* attempting to initialize a BarcodeReader and the camera feed has not been released yet.
*
* @returns A promise resolving to an initialized BarcodeReader instance, or an {@link SdkError} object.
*/
initialize(): Promise<BarcodeReader>;
/**
* Start barcode recognition.
*
* @remarks
* The BarcodeReader instance must have previously been successfully initialized using the
* {@link BarcodeReader#initialize} method.
*/
start(): Promise<void>;
/**
* Stop barcode recognition.
*
* @remarks
* This will suspend camera frame processing/barcode recognition, but will not release the camera stream.
* If you no longer intend to use the BarcodeReader instance, call {@link BarcodeReader#destroy} afterward.
*
* If you intend to only temporarily stop recognition of barcodes and resume later, call
* {@link BarcodeReader#start} again.
*/
stop(): Promise<void>;
/**
* Destroy this BarcodeReader instance, making it unusable.
*
* @remarks
* This will release all associated resources, including the camera stream, and should be called whenever an
* application no longer needs the BarcodeReader.
*
* @returns Promise that resolves when the BarcodeReader and its associated resources are fully destroyed.
*/
destroy(): Promise<void>;
/**
* Show or hide the BarcodeReader instance.
*
* @remarks
* This will not release the camera stream.
*
* @param visible - True to display the BarcodeReader, false to hide it
*/
setVisible(visible: boolean): Promise<void>;
/**
* @returns the current visibility of this BarcodeReader instance
*/
getVisible(): boolean;
/**
* Programmatically zoom the camera feed if the device supports it.
*
* @remarks
* This method will do nothing if the BarcodeReader is not initialized or has been destroyed.
*
* @param enabled - True to enable zoom, false to disable it
*/
setZoom(enabled: boolean): Promise<void>;
/**
* Programmatically toggle the flashlight if the device supports it.
*
* @remarks
* This method will do nothing if the BarcodeReader is not initialized or has been destroyed.
*
* @param enabled - True to enable the flashlight, false to disable it
*/
setFlashlight(enabled: boolean): Promise<void>;
}
/**
* Representation of a camera device.
*/
export declare class CameraDevice {
deviceId: string;
label: string;
toString(): string;
}
/**
* App-supplied callback that is passed a list of available cameras and returns one of them.
*
* The callback must return one of the objects in the list argument. In all other cases, the callback's result will
* be ignored and the default camera selection logic will apply.
*/
export declare type CameraSelector = (cameraDevices: CameraDevice[]) => CameraDevice | undefined;
/**
* A code detection reported by the STRICH SDK.
*/
export declare interface CodeDetection {
/**
* The textual data contained in the code.
*/
data: string;
/**
* The type of detected code.
*/
typeName: string;
/**
* The bounding rectangle in which the code was detected.
*
* Note: this might not be precise, especially for 1D barcodes.
*/
boundingRect: Rect;
/**
* The quadrilateral in which the code was detected.
*
* For rotated or warped codes, this might contain a more precise location estimate than boundingRect.
*/
quadrilateral: Quadrilateral;
/**
* The time of detection.
*/
time: number;
/**
* The raw contained bytes contained in the code.
*/
rawData: Uint8Array;
/**
* The ISO/IEC 15424 symbology identifier.
*/
symbologyIdentifier: string;
}
/**
* BarcodeReader configuration object.
*/
export declare interface Configuration {
/**
* CSS Selector or reference to the HTML element that will host the visible elements of the BarcodeReader.
*
* @remarks
* When using a selector, make sure the selector only matches a single element, e.g. by using an ID.
* When using the popup scanner, do not pass a selector.
*/
selector: string | HTMLElement | undefined;
/**
* Mode: can be 'immediate' (default) for always-on scanning, and 'touch', to only scan when a touch occurs.
*
* @defaultValue immediate
*/
mode?: 'immediate' | 'touch';
/**
* Frame source configuration
*/
frameSource?: FrameSourceConfiguration;
/**
* Locator configuration
*/
locator?: LocatorConfiguration;
/**
* Engine configuration
*/
engine?: EngineConfiguration;
/**
* Overlay configuration
*/
overlay?: OverlayConfiguration;
/**
* Feedback configuration
*/
feedback?: FeedbackConfiguration;
}
/**
* Type for barcode detection handler.
*
* @remarks
* This handler is called synchronously when one or more barcodes are detected, so it should avoid performing any
* expensive operations. STRICH currently tries to detect a barcode as quickly as possible, it may occasionally
* return multiple detections simultaneously.
*/
export declare type DetectionHandler = (detections: CodeDetection[]) => DetectionHandlerResult;
/**
* Result type for barcode detection handler.
*
* The handler can either return nothing (in versions prior to 1.12 this was the only option), or a boolean or array of
* booleans indicating whether the app handled the detections.
*
* Detections that are returned as unhandled (indicate by a `false` return value) will not be highlighted in the
* overlay, even if {@link OverlayConfiguration#showDetections} is set to true. No audio or vibration feedback will
* be emitted either.
*
* @remarks
* Returning `false` from the handler does not influence the usage in quota-based plans. All detections are always
* counted, regardless if they were handled or not.
*/
export declare type DetectionHandlerResult = void | boolean | boolean[];
/**
* Engine configuration
*/
export declare interface EngineConfiguration {
/**
* The enabled barcode symbologies.
*
* See https://docs.strich.io/supported-symbologies.html for an exhaustive list of supported symbologies.
*
* @remarks
* It is highly recommended to configure only the symbologies required by your application.
* An empty array or undefined is interpreted as 'all symbologies enabled'.
*
* @example ['qr', 'code128']
*
* @defaultValue
* `undefined`
* (all symbologies enabled - NOT RECOMMENDED)
*/
symbologies?: (SymbologyName | SymbologySpec)[];
/**
* The number of scanlines that need to decoded successfully for a valid decode.
*
* @remarks
* Increasing this parameter reduces the possibility of a misread, but
* makes it more likely for degraded codes to not be read at all.
*
* The default value is two scanlines and usually should not be changed.
*
* @defaultValue 2
*/
minScanlinesNeeded?: number;
/**
* Toggle recognition of inverted barcodes (light print on dark background).
*
* @remarks
* This should only be enabled if you need to detect these barcodes, as additional processing will take place.
*
* @defaultValue false
*/
invertedCodes?: boolean;
/**
* Time interval in milliseconds during which multiple detections of the same code are not repeated.
*
* @remarks It is recommended to set a duplicateInterval as scans are metered except in Enterprise subscriptions.
* @defaultValue 750
*/
duplicateInterval?: number;
/**
* Set the minimum occurrence count for 1D barcodes with weak checksums in a given time window for it be accepted.
*
* @remarks
* Setting this parameter to 0 disables hysteresis (default behavior for versions up to 1.1.0)
*
* @defaultValue 2
*/
hysteresisMinCount?: number;
/**
* Set the duration of the hysteresis window in milliseconds.
*
* @defaultValue 350
*/
hysteresisInterval?: number;
}
/**
* User feedback configuration
*/
export declare interface FeedbackConfiguration {
/**
* Toggle audible beep upon successful scan.
*
* @remarks
* Uses the WebAudio API to emit a "cash register"-like beep. Beeping is done on a best-effort
* basis and should not be relied upon. If the browser does not support the WebAudio API, and in iOS
* PWAs, an HTML5 audio element will be used instead.
*
* @defaultValue true
*/
audio?: boolean | AudioFeedbackConfiguration;
/**
* Toggle vibration upon successful scan, if supported by device.
*
* @defaultValue true
*/
vibration?: boolean;
}
/**
* Configuration for the frame source (camera).
*/
export declare interface FrameSourceConfiguration {
/**
* Video frame resolution.
*
* @remarks
* The default resolution is 720p, which is usually enough for good quality
* barcodes. You can try higher resolutions if you have very fine or
* degraded codes, at the expense of higher computational requirements.
*
* @defaultValue hd
*/
resolution?: 'hd' | 'full-hd' | 'auto';
/**
* Remember the camera that was last used to successfully scan a code.
*
* @remarks
* When set to true, the frame source will remember the camera used for the last
* successful scan and attempt to use the same camera when re-initializing the frame source.
* The remembered camera is cleared when a device is selected explicitly through the camera selector.
*
* The mechanism relies on the browser returning stable device IDs from calls to
* [enumerateDevices](https://developer.mozilla.org/en-US/docs/Web/API/MediaDevices/enumerateDevices) and
* related APIs. For privacy reasons, browsers will occasionally rotate these device IDs to make them
* non-stable to prevent fingerprinting. Some browsers like Samsung Internet even change them
* on every page load. This is a best-effort mechanism.
*
* @defaultValue false
*/
rememberCameraDeviceId?: boolean;
/**
* Allow passing in exact constraints for camera device selection via
* [getUserMedia](https://developer.mozilla.org/en-US/docs/Web/API/MediaDevices/getUserMedia#constraints).
* If set, will override the {@link FrameSourceConfiguration.resolution} property and any other camera-related properties.
*
* @example
* In the example below, a camera device is explicitly selected by ID. Audio is explicitly not requested (never
* used by STRICH) and an HD-like resolution preference is specified by range.
*
* ```js
* constraints: {
* video: {
* deviceId: {
* exact: '2d122f8e0630b5a6a19c157f066e13e05115f12f7d4dfb29e5560b4acefe7308'
* },
* width: {min: 800, ideal: 1280, max: 1600},
* height: {min: 600, ideal: 720, max: 900}
* },
* audio: false
* }
* ```
*
* @remarks
* This is an advanced option, and should only be used if you are familiar with the
* [Media Capture and Streams API](https://developer.mozilla.org/en-US/docs/Web/API/MediaDevices/getUserMedia)
* and have to build your own camera selection workflow.
*
* @defaultValue undefined
*/
constraints?: MediaStreamConstraints;
}
/**
* Configuration object for {@link ImageScanner}.
*
* Specify which kind of 1D/2D barcodes should be detected using the
* {@link EngineConfiguration.symbologies} field.
*
* @example
* To read a QR Code from an image, use this configuration:
*
* ```javascript
* const cfg = {
* engine: { symbologies: ['qr'] }
* }
* ```
*/
export declare interface ImageConfiguration {
/**
* Engine configuration
*/
engine?: EngineConfiguration;
}
/**
* Scanner for static images, typically provided via an HTML input element.
*
* @remarks
* Make sure that the input image is sharp, and that the code to be scanned is in focus. Some images might not scan
* using ImageScanner, but can be scanned using camera-based scanning (BarcodeReader, PopupScanner). This is due to
* more frames being available for decoding, increasing the chances of getting a good quality sample.
*
* @example
* HTML:
* ```html
* <input id="image-input" type="file" accept="image/*" />
* ```
*
* JavaScript:
* ```javascript
* const imageInput = document.getElementById('image-input');
* imageInput.onchange = async () => {
* const detections = await ImageScanner.scan(image.files[0], {
* engine: { symbologies: ['qr'] }
* });
* }
* ```
*/
export declare class ImageScanner {
/**
* Decode a barcode in a static image.
*
* @remarks
* By default, a single barcode is detected. In a future release, an option to detect multiple barcodes
* will be added.
*
* @param image - The image source, can be a HTMLImageElement, ImageData, ImageBitmap, File, Blob or a data URL.
* @param cfg - The engine configuration to use for barcode detection.
*/
static scan(image: ImageSource, cfg: ImageConfiguration): Promise<CodeDetection[]>;
}
/**
* The types of image input {@link ImageScanner.scan} can process.
*/
export declare type ImageSource = HTMLImageElement | ImageData | ImageBitmap | File | Blob | string;
/**
* Locator configuration
*/
export declare interface LocatorConfiguration {
/**
* The region of interest in viewport coordinates.
*
* @remarks if no region of interest is specified, an appropriate one will automatically be selected at run-time
* depending on the configured symbologies.
*/
regionOfInterest?: RegionOfInterest;
/**
* Disregard colorful areas, assume barcodes are printed black on white.
*
* @remarks This is an advanced setting and should normally not be changed.
* @defaultValue false
*/
chromaReject?: boolean;
/**
* The locator implementation to use.
*
* @remarks This is an advanced setting and should normally not be changed. It used to be possible to force WebGL 1,
* but starting with 1.5, WebGL1 is no longer supported. This property might be used in the future to switch to a
* WebGPU-powered locator.
* @defaultValue auto
*/
impl?: 'auto' | 'webgl2';
/**
* Disable asynchronous reads from GPU when using `webgl2` {@link LocatorConfiguration.impl}.
*
* @remarks Some older iOS versions have issues with WebGL2 asynchronous reads. There is usually no need to change
* this setting from its default.
* @defaultValue false
*/
forceSyncReadback?: boolean;
}
/**
* Overlay configuration
*/
export declare interface OverlayConfiguration {
/**
* Indicate if a horizontal line should be drawn to aid in positioning 1D barcodes.
*
* @defaultValue true
*/
showTargetingLine?: boolean;
/**
* Indicate if the overlay should draw the bounding boxes of detected barcodes on top of the camera preview.
*
* @defaultValue true
*/
showDetections?: boolean;
/**
* Indicate if the camera selector should be shown in the overlay.
*
* @defaultValue true
*/
showCameraSelector?: boolean;
/**
* Filter cameras returned by the browser.
*
* If set to true, only cameras that are deemed appropriate for barcode scanning will be
* offered in the camera selector.
*
* @defaultValue true
*/
filterCameras?: boolean;
/**
* Indicate if the flashlight toggle should be shown in the overlay.
*
* @remarks Flashlight functionality is not supported in some browsers.
* @defaultValue true
*/
showFlashlight?: boolean;
/**
* Indicate if single-tapping the overlay should attempt to trigger autofocus.
*
* @remarks Triggering autofocus is currently only available on Android devices.
* @defaultValue true
*/
focusOnTap?: boolean;
/**
* Color to use for drawing UI elements such as the viewfinder and camera selector. Must be specified in rgb()
* format, with the color components given as integers with no separating whitespace.
*
* @defaultValue rgb(255,255,255)
*/
primaryColor?: string;
/**
* Color to use for filling area of detected barcodes. Must be specified in rgb() format, with the color
* components given as integers with no separating whitespace. The fill will become transparent when the
* detection becomes stale.
*
* @remarks Only has an effect if {@link OverlayConfiguration.showDetections} is true.
* @defaultValue rgb(0,0,255)
*/
detectionFillColor?: string;
/**
* Color to use for drawing a border around the area of detected barcodes. Must be specified in rgb() format,
* with the color components given as integers with no separating whitespace. The border will become transparent
* when the detection becomes stale.
*
* @remarks Only has an effect if {@link OverlayConfiguration.showDetections} is true.
* @defaultValue undefined
*/
detectionBorderColor?: string;
/**
* The border width in pixels to use for drawing a border around the area of detected barcodes.
*
* @remarks
* The allowed range is 0 to 4 pixels. Values outside the range are clamped.
*
* @defaultValue 0
*/
detectionBorderWidth?: number;
/**
* Color to use for drawing the horizontal targeting line when a barcode was detected.
* Must be specified in rgb() format, with the color components given as integers with no separating whitespace.
*
* @defaultValue rgb(255,0,0)
*/
targetingLineActiveColor?: string;
/**
* Corner radius in pixels for rectangular elements such as viewfinder and camera selector.
*
* The allowed range of the corner radius is 0 to 8 pixels.
*
* @defaultValue 0
*/
cornerRadius?: number;
/**
* Border width in pixels of the viewfinder, the rectangle around the region of interest.
*
* @remarks
* The allowed range is 1 to 20 pixels. Values outside the range are clamped.
*
* @defaultValue 1
*/
viewfinderBorderWidth?: number;
/**
* Corner radius in pixels of the viewfinder, the rectangle around the region of interest.
*
* This property applies only to the viewfinder and overrides the {@link OverlayConfiguration.cornerRadius} property.
*
* The allowed range of the corner radius is 0 to 20 pixels.
*
* @defaultValue 0
*/
viewfinderCornerRadius?: number;
/**
* Color to use for de-emphasizing the area around the viewfinder.
*
* The color will be used to create a mask around the viewfinder/region of interest to aid the user in focusing
* the camera on the barcode.
*
* A semi-translucent dark color works best, e.g. rgba(0,0,0,0.5) would use a semi-translucent black.
*
* @defaultValue undefined
*/
maskColor?: string;
/**
* Indicate if the zoom control should be shown in the overlay.
*
* @remarks
* This is only supported for browsers that support the 'zoom' constraint, see:
* https://developer.mozilla.org/en-US/docs/Web/API/MediaTrackConstraints#zoom
* Notably, Safari versions earlier than 17.4 and Firefox do not support this feature.
*
* @defaultValue true
*/
showZoom?: boolean;
/**
* Indicate if double-tapping the overlay should cause the camera to zoom in.
*
* @remarks
* This is only supported for browsers that support the 'zoom' constraint, see:
* https://developer.mozilla.org/en-US/docs/Web/API/MediaTrackConstraints#zoom
* Notably, Safari versions earlier than 17.4 and Firefox do not support this feature.
*
* @defaultValue true (where supported)
*/
zoomOnDoubleTap?: boolean;
/**
* Override the STRICH logo displayed in the bottom-right corner with a custom image.
*
* This capability is only available for Enterprise licenses. Please note that
* attempting to hide or replace the STRICH logo by other means is a violation of the License Agreement.
*
* The image should ideally be supplied in SVG format, either inline as a data URL or as an absolute HTTPS URL.
*
* The image will be rendered at its intrinsic size (pixel size = CSS size), which can lead to blurriness
* on high-density screens if the image is not supplied in SVG format.
*
* Setting the property to `null` will display no logo at all.
*/
customLogoSrc?: string | null;
/**
* The size (in CSS pixels) used to render the custom logo.
*
* Example:
*
* ```ts
* configuration.overlay.customLogoSize = { width: 80, height: 20 };
* ```
*
* When providing a custom logo in a raster image format such as PNG, JPEG or WEBP, the image will be
* scaled to fit the specified dimensions. In this case, it's recommended to provide a high-resolution (2x or 3x)
* raster image.
*/
customLogoSize?: Size;
}
/**
* A point in two-dimensional space.
*
* The y coordinate origin starts at the top.
*/
export declare interface Point {
/**
* The x-coordinate in pixels.
*/
x: number;
/**
* The y-coordinate in pixels.
*/
y: number;
}
/**
* Popup scanner configuration
*/
export declare interface PopupConfiguration {
/**
* The barcode symbologies that should be detected.
*
* See {@link EngineConfiguration#symbologies} for details.
*/
symbologies: (SymbologyName | SymbologySpec)[];
/**
* An optional handler for detections.
*
* Receives barcode detections and must return `true` if scanning should stop, or `false` if scanning should
* continue. Any truthy value will be interpreted as `true`.
*/
detectionHandler?: (detections: CodeDetection[]) => boolean;
/**
* The camera resolution to use.
*
* @defaultValue hd
*/
resolution?: 'hd' | 'full-hd';
/**
* Optional overrides for textual content.
*/
labels?: {
/**
* The text to display in the dialog header area.
*
* @remarks
* If no value is supplied, a locale-dependent default text will be used.
*/
title?: string;
/**
* The text to display on the cancel button in the dialog bottom area.
*
* @remarks
* If no value is supplied, a locale-dependent default text will be used.
*/
cancel?: string;
};
/**
* Optional overrides for title area and cancel button.
*/
style?: {
/**
* Background color to use for title. Must be specified in rgb() or rgba() notation.
*
* @defaultValue rgba(15,42,66,0.9)
*/
titleBackgroundColor?: string;
/**
* Background color to use for title text. Must be specified in rgb() notation.
*
* @defaultValue rgb(236,237,237)
*/
titleColor?: string;
/**
* Background color to use for cancel button. Must be specified in rgb() or rgba() notation.
*
* @defaultValue transparent
*/
cancelButtonBackgroundColor?: string;
/**
* Color to use for cancel button outline and text. Must be specified in rgb() or rgba() notation.
*
* @defaultValue rgba(15,42,66,0.9)
*/
cancelButtonColor?: string;
};
/**
* Optional Frame source configuration, will override {@link PopupConfiguration.resolution} setting.
*/
frameSource?: FrameSourceConfiguration;
/**
* Optional Overlay configuration.
*/
overlay?: OverlayConfiguration;
/**
* Optional configuration for audible and haptic feedback.
*/
feedback?: FeedbackConfiguration;
}
/**
* Pre-built modal scanning interface, intended for simple use cases that do not require a lot of customization.
*
* For more advanced use cases and user interface customization, you can provide your own host element and integrate
* a {@link BarcodeReader} directly.
*
* @remarks
* Requires browser support for the <dialog> element, which is widely available since early 2022.
*/
export declare class PopupScanner {
/**
* Scan barcodes using a pre-built, modal popup interface.
*
* @remarks
* Scanning is active until one or more barcodes of the configured symbologies
* (see {@link PopupConfiguration.symbologies}) are detected. If a detection handler is provided
* (see {@link PopupConfiguration.detectionHandler}), scanning will continue until the detection
* handler returns a truthy value.
*
* @param configuration - The popup scanner configuration
* @returns Promise that resolves into the detected barcodes or undefined (user cancellation)
*/
static scan(configuration: PopupConfiguration): Promise<CodeDetection[] | undefined>;
}
/**
* A non-intersecting polygon with four points.
*/
export declare interface Quadrilateral {
/**
* The 4 points forming the quadrilateral.
*/
points: Point[];
}
/**
* An axis-aligned rectangle in two-dimensional space.
*/
export declare interface Rect {
/**
* The origin of the rectangle.
*/
origin: Point;
/**
* The size of the rectangle.
*/
size: Size;
}
/**
* The region of interest is specified as an inset between screen edge and RoE on each side,
* expressed as a fractional value (between 0 and 0.5).
*
* For instance, to have an area that occupies the middle 80% horizontal area and 50% vertical area, you would
* specify the region of interest as follows:
*
* ```json
* { left: 0.1, right: 0.1, top: 0.25, bottom: 0.25 }
* ```
* (10% width inset on each side, 25% height inset on each side)
*/
export declare interface RegionOfInterest {
/**
* Left inset, relative [0 .. 0.5].
*
* @example 0.1
*/
left: number;
/**
* Top inset, relative [0 .. 0.5].
*
* @example 0.25
*/
top: number;
/**
* Right inset, relative [0 .. 0.5].
*
* @example 0.1
*/
right: number;
/**
* Bottom inset, relative [0 .. 0.5]
*
* @example 0.25
*/
bottom: number;
}
/**
* STRICH SDK error class
*/
export declare class SdkError extends Error {
/**
* Flag indicating if this error is related to camera access.
*/
duringCameraAccess: boolean;
/**
* A localized error message, if available, otherwise this will contain the non-localized message.
*/
localizedMessage: string;
/**
* An optional underlying error that caused this error.
*/
cause?: Error;
/**
* An optional detail message to display to disambiguate multiple errors (not-translated)
*/
detailMessage?: string;
constructor(keyOrMessage: string, cause?: Error);
}
/**
* The size of a bounding box, represented by its width and height.
*/
export declare interface Size {
/**
* The width in pixels.
*/
width: number;
/**
* The height in pixels.
*/
height: number;
}
/**
* Main entrypoint for the STRICH Barcode Scanning SDK, containing initialization and utility methods.
*
* The SDK has to be initialized with a license key using the {@link StrichSDK.initialize} method before barcodes may be scanned.
*/
export declare class StrichSDK {
/**
* @returns The semantic version of the SDK, as MAJOR.MINOR.PATCH
*/
static version(): string;
/**
* @returns True if the SDK was successfully initialized, false otherwise
*/
static isInitialized(): boolean;
/**
* One-time initialization of the SDK
*
* @remarks
* For online licenses, this will invoke an HTTPS call to our license service. If possible, we recommend calling
* this method early in the lifecycle of your scanning flow, to avoid any delay at the time a {@link BarcodeReader}
* instance is required.
*
* @param licenseKey - The license key obtained from the Customer Portal.
* @returns A Promise that resolves when the SDK was initialized successfully, or an {@link SdkError} instance.
*/
static initialize(licenseKey: string): Promise<void>;
/**
* Set a custom ID for additional context.
*
* @remarks
* The custom ID is independent of the device ID, and can be used for custom device
* identifiers, location identifiers or anonymous user identifiers.
* Unless you opt out of usage tracking (an Enterprise-only capability), the custom ID will also be
* available in the CSV export of your scans.
*
* The custom ID is not a per-scan identifier.
*
* USING THE CUSTOM ID TO TRANSMIT PERSONALLY IDENTIFYING DATA IS FORBIDDEN AND
* CONSTITUTES A BREACH OF THE TERMS OF THE LICENSE AGREEMENT.
*
* @param customId - The custom ID. Use `null` to unset the custom ID.
*/
static setCustomId(customId: string | null): void;
/**
* Override the language of built-in error messages shown in the scanning UI.
* By default, browser's language (navigator.language) will be used.
*
* @param lang - The lower-case ISO language code, e.g. 'en'
*/
static setLanguage(lang: string): void;
/**
* Override the preferred audio implementation used to emit audible feedback (beeps). By default, the SDK will
* automatically select an appropriate implementation.
*
* @remarks
* Using this method should only be necessary in specialized environments.
* Selecting an unsupported implementation will still fall back to an available one.
*
* @param impl - The audio implementation to use, either 'webaudio' for the WebAudio API, or 'html5' for an HTML5 Audio element
*/
static setAudioImpl(impl: 'webaudio' | 'html5'): void;
/**
* Check if the browser has access to a camera device, which is required for scanning barcodes.
*
* @remarks
* This can be used as a check if a BarcodeReader should be presented, or a fallback to a manual input method
* or error page should be displayed.
*
* @returns A Promise that resolves to a boolean value indicating if a camera is available. The Promise will reject
* if the check fails for any reason (including missing/denied permissions).
*/
static hasCameraDevice(): Promise<boolean>;
/**
* Return the current state of the camera permission.
*
* Uses the Permissions API (https://developer.mozilla.org/en-US/docs/Web/API/Permissions_API) to determine
* if the user has granted or denied camera permission or if a prompt will occur when the camera is accessed.
* In all other cases, the value 'unknown' is returned.
*
* @remarks
* The Permissions API is currently not available on Firefox: 'unknown' will be returned.
*
* @returns A Promise resolving to the current state of the camera permission: 'granted' if it is granted, 'denied'
* if it is denied, 'prompt' if a prompt will occur, and 'unknown' if it could not be determined for any reason.
*/
static getCameraPermissionState(): Promise<'denied' | 'granted' | 'prompt' | 'unknown'>;
}
/**
* The supported symbologies.
*
* For more information, please visit https://docs.strich.io/supported-symbologies.html
*/
export declare type SymbologyName = 'ean13' | 'ean8' | 'upca' | 'upce' | 'databar' | 'databar-exp' | 'code39' | 'code93' | 'code128' | 'i25' | 'codabar' | 'msi-plessey' | 'qr' | 'aztec' | 'datamatrix' | 'pdf417' | 'microqr';
/**
* For variable-length symbologies, min/max length can be specified in addition to the symbology.
*/
export declare type SymbologySpec = {
/**
* The name of the 1D barcode symbology.
*/
name: 'ean13' | 'ean8' | 'upca' | 'upce' | 'databar' | 'databar-exp' | 'code39' | 'code93' | 'code128' | 'i25' | 'codabar' | 'msi-plessey';
/**
* The minimum length of the barcode, only has an effect for variable-length symbologies.
*/
minLen?: number;
/**
* The maximum length of the barcode, only has an effect for variable-length symbologies.
*/
maxLen?: number;
/**
* The minimum length of the leading and trailing quiet zone for this symbology, expressed as multiples of X.
*
* @remarks
* There is rarely a need to change the default.
*/
qz?: number;
/**
* The mode to use for symbologies which support an optional checksum mechanism.
*
* Setting the mode to `0` or leaving it unset disables processing of the checksum.
* `1` will expect the check digit to be present, validate the barcode data against it, and strip it from the
* transmitted data.
* `2` will validate and also transmit the check digit along with the data portion.
*
* @remarks
* Setting this option to `1` or `2` requires that all barcodes of this symbology include a check digit.
* Barcodes that lack the check digit will not be readable anymore.
*
* @defaultValue 0
*/
checksumMode?: number;
} | {
/** The name of the QR Code symbology */
name: 'qr';
/**
* Enable detection of QR Codes with rounded finder patterns.
*
* @remarks
* The finder patterns of a QR Code are nominally square with straight edges. The straight edges
* are useful in optimizing the detection of finder pattern triplets and mapping of the QR Code.
* The ISO specification mandates square finder patterns, but rounded finder patterns are used
* in practice, especially outside of industrial use cases.
*
* @defaultValue false
*/
roundedFPs?: boolean;
/**
* Enable detection of QR Codes on curved/bent surfaces.
*
* @remarks
* More advanced algorithms will be used to read QR Codes from curved or bent surfaces. This option
* incurs extra processing time and only makes sense if your QR Codes are printed on curved surfaces
* such as bottles, barrels, and other cylindrical or spherical items.
*
* @defaultValue false
*/
curved?: boolean;
} | {
/** The name of the 2D symbology */
name: 'aztec' | 'datamatrix' | 'pdf417' | 'microqr';
};
export { }