Ready-to-Use UI
We've improved the Ready-to-Use UI Components of our iOS and Android Barcode Scanner SDKs, which makes it even easier to provide your users with an intuitive scanning interface without having to build it yourself!
The Ready-To-Use UI (RTU UI) is an easy-to-integrate and highly customizable high-level UI component that can handle most barcode scanning use cases and tasks.
The design and behavior of this component are based on our many years of experience as well as the feedback from our SDK customers.
Although the main idea of the RTU UI is to provide simple-to-integrate and simple-to-configure components, its customization capabilities are numerous and should suit most of your needs. To achieve an even higher degree of customization, you can implement a custom UI and business-logic using our Classic UI components.
Import
To use the RTU UI component please import startBarcodeScanner
function and all related configurations and results from react-native-scanbot-barcode-scanner-sdk/ui_v2
.
Example:
import {
BarcodeScannerConfiguration,
startBarcodeScanner,
} from 'react-native-scanbot-barcode-scanner-sdk/ui_v2';
async function statRtuUiV2WithDefaultConfiguration() {
// Create the default configuration object.
const config = new BarcodeScannerConfiguration();
// See further customization configs...
const result = await startBarcodeScanner(config);
}
Returns
result.status
-OK
If the scanning is completed,CANCELED
if the user has canceled the operation (tapped on the "cancel" button).result.data?.items
- Optional List of recognized barcodes as items. See the barcode item structure below.
Barcode item structure:
type
- Recognized barcode symbology.count
- Number of recognized barcodes of this symbology and value.text
- Recognized value of the barcode.textWithExtension
- Recognized barcode value with extension (if available).rawBytes
- Representation of the raw data that is contained the recognized barcode.parsedDocument
- The parsed known document format (if parsed successfully).
Change the visuals to suit your needs
In addition to a fresh new design, the RTU UI v.2.0 comes with new configuration options that enable you to quickly adapt its visual appearance:
Palette
Using the new palette feature, you can change the UI components' colors to match your brand design.
import {BarcodeScannerConfiguration} from 'react-native-scanbot-barcode-scanner-sdk/ui_v2';
function rtuUiV2PaletteConfiguration() {
// Create the default configuration object.
const config = new BarcodeScannerConfiguration();
// Simply alter one color and keep the other default.
config.palette.sbColorPrimary = 'c86e19';
// ... or set an entirely new palette.
config.palette.sbColorPrimary = '#C8193C';
config.palette.sbColorPrimaryDisabled = '#F5F5F5';
config.palette.sbColorNegative = '#FF3737';
config.palette.sbColorPositive = '#4EFFB4';
config.palette.sbColorWarning = '#FFCE5C';
config.palette.sbColorSecondary = '#FFEDEE';
config.palette.sbColorSecondaryDisabled = '#F5F5F5';
config.palette.sbColorOnPrimary = '#FFFFFF';
config.palette.sbColorOnSecondary = '#C8193C';
config.palette.sbColorSurface = '#FFFFFF';
config.palette.sbColorOutline = '#EFEFEF';
config.palette.sbColorOnSurfaceVariant = '#707070';
config.palette.sbColorOnSurface = '#000000';
config.palette.sbColorSurfaceLow = '#00000026';
config.palette.sbColorSurfaceHigh = '#0000007A';
config.palette.sbColorModalOverlay = '#000000A3';
}
Localization
Using the new localization feature, you can easily localize the strings that are displayed on buttons, labels and text fields.
import {BarcodeScannerConfiguration} from 'react-native-scanbot-barcode-scanner-sdk/ui_v2';
function rtuUiV2LocalizationConfiguration() {
// Create the default configuration object.
const config = new BarcodeScannerConfiguration();
// Configure localization parameters.
config.localization.barcodeInfoMappingErrorStateCancelButton = 'Custom Cancel title';
config.localization.cameraPermissionCloseButton = 'Custom Close title';
// Configure other strings as needed.
// Configure other parameters as needed.
}
User Guidance
Text elements like the on-screen user guidance can be adapted in form and color.
import {BarcodeScannerConfiguration} from 'react-native-scanbot-barcode-scanner-sdk/ui_v2';
async function statRtuUiV2WithUserGuidanceConfiguration() {
// Create the default configuration object.
const config = new BarcodeScannerConfiguration();
// Hide/unhide the user guidance.
config.userGuidance.visible = true;
// Configure the title.
config.userGuidance.title.text = 'Move the finder over a barcode';
config.userGuidance.title.color = '#FFFFFF';
// Configure the background.
config.userGuidance.background.fillColor = '#0000007A';
// Configure other parameters as needed.
}
Top bar
You can choose how to display the top bar in your app: hidden, solid or gradient.
import {BarcodeScannerConfiguration} from 'react-native-scanbot-barcode-scanner-sdk/ui_v2';
function rtuUiV2TopBarConfiguration() {
// Create the default configuration object.
const config = new BarcodeScannerConfiguration();
// Configure the top bar.
// Set the top bar mode.
config.topBar.mode = 'GRADIENT';
// Set the background color which will be used as a gradient.
config.topBar.backgroundColor = '#C8193C';
// Configure the status bar look. If visible - select DARK or LIGHT according to your app's theme color.
config.topBar.statusBarMode = 'HIDDEN';
// Configure the Cancel button.
config.topBar.cancelButton.text = 'Cancel';
config.topBar.cancelButton.foreground.color = '#FFFFFF';
// Configure other parameters as needed.
}
Action Bar
The zoom and flashlight buttons and a button to switch cameras are now included out of the box.
import {BarcodeScannerConfiguration} from 'react-native-scanbot-barcode-scanner-sdk/ui_v2';
function rtuUiV2ActionBarConfiguration() {
// Create the default configuration object.
const config = new BarcodeScannerConfiguration();
// Configure the action bar.
// Hide/unhide the flash button.
config.actionBar.flashButton.visible = true;
// Configure the inactive state of the flash button.
config.actionBar.flashButton.backgroundColor = '#0000007A';
config.actionBar.flashButton.foregroundColor = '#FFFFFF';
// Configure the active state of the flash button.
config.actionBar.flashButton.activeBackgroundColor = '#FFCE5C';
config.actionBar.flashButton.activeForegroundColor = '#000000';
// Hide/unhide the zoom button.
config.actionBar.zoomButton.visible = true;
// Configure the inactive state of the zoom button.
config.actionBar.zoomButton.backgroundColor = '#0000007A';
config.actionBar.zoomButton.foregroundColor = '#FFFFFF';
// Zoom button has no active state - it only switches between zoom levels (for configuring those please refer to camera configuring).
// Hide/unhide the flip camera button.
config.actionBar.flipCameraButton.visible = true;
// Configure the inactive state of the flip camera button.
config.actionBar.flipCameraButton.backgroundColor = '#0000007A';
config.actionBar.flipCameraButton.foregroundColor = '#FFFFFF';
// Flip camera button has no active state - it only switches between front and back camera.
// Configure other parameters as needed.
}
Barcode sheet mode
The bottom sheet used to display previews of the scanned barcodes has two modes: COLLAPSED_SHEET
and BUTTON
. In COLLAPSED_SHEET
mode, the bottom sheet is visible and collapsed and can be expanded by dragging it up. In addition, the button can show the overall barcode count.
import {
BarcodeScannerConfiguration,
MultipleScanningMode,
} from 'react-native-scanbot-barcode-scanner-sdk/ui_v2';
function rtuUiV2PreviewModeConfiguration() {
// Create the default configuration object.
const config = new BarcodeScannerConfiguration();
// Initialize the use case for multiple scanning.
config.useCase = new MultipleScanningMode();
// Set the sheet mode for the barcodes preview.
config.useCase.sheet.mode = 'COLLAPSED_SHEET';
// Set the height for the collapsed sheet.
config.useCase.sheet.collapsedVisibleHeight = 'LARGE';
// Configure the submit button on the sheet.
config.useCase.sheetContent.submitButton.text = 'Submit';
config.useCase.sheetContent.submitButton.foreground.color = '#000000';
// Configure other parameters, pertaining to multiple-scanning mode as needed.
// Configure other parameters as needed.
}
Use cases
Single scan with confirmation dialog
The single scan mode is optimized for scanning single barcodes and easily configurable according to your needs. It comes with the option of showing a confirmation sheet after the barcode is scanned. The confirmation sheet is also highly customizable, offering the ability to configure the barcode title, the barcode subtitle, the cancel button, and the submit button.
try {
/**
* Check license status and return early
* if the license is not valid
*/
if (!(await checkLicense())) {
return;
}
/**
* Instantiate a configuration object of BarcodeScannerConfiguration and
* start the barcode scanner with the configuration
*/
const config = new BarcodeScannerConfiguration();
// Initialize the use case for single scanning.
config.useCase = new SingleScanningMode();
// Enable and configure the confirmation sheet.
config.useCase.confirmationSheetEnabled = true;
config.useCase.sheetColor = '#FFFFFF';
// Hide/unhide the barcode image.
config.useCase.barcodeImageVisible = true;
// Configure the barcode title of the confirmation sheet.
config.useCase.barcodeTitle.visible = true;
config.useCase.barcodeTitle.color = '#000000';
// Configure the barcode subtitle of the confirmation sheet.
config.useCase.barcodeSubtitle.visible = true;
config.useCase.barcodeSubtitle.color = '#000000';
// Configure the cancel button of the confirmation sheet.
config.useCase.cancelButton.text = 'Close';
config.useCase.cancelButton.foreground.color = '#C8193C';
config.useCase.cancelButton.background.fillColor = '#00000000';
// Configure the submit button of the confirmation sheet.
config.useCase.submitButton.text = 'Submit';
config.useCase.submitButton.foreground.color = '#FFFFFF';
config.useCase.submitButton.background.fillColor = '#C8193C';
// Configure other parameters, pertaining to single-scanning mode as needed.
// Set an array of accepted barcode types.
config.recognizerConfiguration.barcodeFormats = acceptedBarcodeFormats;
config.recognizerConfiguration.acceptedDocumentFormats = acceptedBarcodeDocumentFormats;
// Configure other parameters as needed.
const result = await startBarcodeScanner(config);
/**
* Handle the result if result status is OK
*/
if (result.status === 'OK' && result.data) {
navigation.navigate(Screens.BARCODE_RESULTS, result.data);
}
} catch (e: any) {
errorMessageAlert(e.message);
}
Multiple scanning
The multiple scanning mode is very flexible and allows you to configure each component in several ways.
Firstly, it offers two display modes: one with a collapsed list of scanned barcodes and one with just a toggle button that brings up the list.
Secondly, there is an option to configure the counting mode. The counting mode can either be COUNTING
or UNIQUE
. In COUNTING
mode, the scanner
scans barcodes with the same value again and counts the number of items. In the UNIQUE
mode, the scanner only scans barcodes with unique values.
If another barcode has the same value, it won't be scanned again.
Additionally the countingRepeatDelay
can be used to set the time interval in milliseconds that must pass before counting a barcode again.
try {
/**
* Check license status and return early
* if the license is not valid
*/
if (!(await checkLicense())) {
return;
}
/**
* Instantiate a configuration object of BarcodeScannerConfiguration and
* start the barcode scanner with the configuration
*/
const config = new BarcodeScannerConfiguration();
// Initialize the use case for multiple scanning.
config.useCase = new MultipleScanningMode();
// Set the counting mode.
config.useCase.mode = 'COUNTING';
// Set the sheet mode for the barcodes preview.
config.useCase.sheet.mode = 'COLLAPSED_SHEET';
// Set the height for the collapsed sheet.
config.useCase.sheet.collapsedVisibleHeight = 'LARGE';
// Enable manual count change.
config.useCase.sheetContent.manualCountChangeEnabled = true;
// Set the delay before same barcode counting repeat.
config.useCase.countingRepeatDelay = 1000;
// Configure the submit button.
config.useCase.sheetContent.submitButton.text = 'Submit';
config.useCase.sheetContent.submitButton.foreground.color = '#000000';
// Implement mapping for the barcode item information
config.useCase.barcodeInfoMapping.barcodeItemMapper = (barcodeItem, onResult, onError) => {
/** TODO: process scan result as needed to get your mapped data,
* e.g. query your server to get product image, title and subtitle.
*
* Note: The built-in fetch API won't work properly in this case.
* To request from the server, please use XMLHttpRequest API or another 3rd party library such as axios.
*
* See example below.
*/
const title = `Some product ${barcodeItem.textWithExtension}`;
const subtitle = barcodeItem.type ?? 'Unknown';
// If image from URL is used, on Android platform INTERNET permission is required.
const image = 'https://avatars.githubusercontent.com/u/1454920';
// To show captured barcode image use BarcodeMappedData.barcodeImageKey
// const image = BarcodeMappedData.barcodeImageKey;
/** Call onError() in case of error during obtaining mapped data. */
if (barcodeItem.textWithExtension === 'Error occurred!') {
onError();
} else {
onResult(new BarcodeMappedData({title: title, subtitle: subtitle, barcodeImage: image}));
}
};
// Configure other parameters, pertaining to multiple-scanning mode as needed.
// Set an array of accepted barcode types.
config.recognizerConfiguration.barcodeFormats = acceptedBarcodeFormats;
config.recognizerConfiguration.acceptedDocumentFormats = acceptedBarcodeDocumentFormats;
// Configure other parameters as needed.
const result = await startBarcodeScanner(config);
/**
* Handle the result if result status is OK
*/
if (result.status === 'OK' && result.data) {
navigation.navigate(Screens.BARCODE_RESULTS, result.data);
}
} catch (e: any) {
errorMessageAlert(e.message);
}
Find and Pick scanning
Using the Find and Pick scanning mode, you can set a list of expected barcodes to be scanned. In the list, you can provide for each barcode its value
, title
, image
, and count
.
The count
simply means, the number of times a barcode needs to be scanned. You also have the flexibility of setting the allowPartialScan
property of the use case to complete
the scanning with partial results. The find and pick use case also makes it possible to provide an extensively elaborated visual experience using AR Overlays by providing the ability to
properly distinguish between different barcodes (not expected, expected but partially or fully scanned). The bottom sheet is also highly customizable and provides information of
the current state of the barcodes. You can also manually change the count of each barcode from the list, incrementally or by tapping the count and manually typing in the number.
try {
/**
* Check license status and return early
* if the license is not valid
*/
if (!(await checkLicense())) {
return;
}
/**
* Instantiate a configuration object of BarcodeScannerConfiguration and
* start the barcode scanner with the configuration
*/
const config = new BarcodeScannerConfiguration();
// Initialize the use case for find and pick scanning.
config.useCase = new FindAndPickScanningMode();
// Set the sheet mode for the barcodes preview.
config.useCase.sheet.mode = 'COLLAPSED_SHEET';
// Enable/Disable the automatic selection.
config.useCase.arOverlay.automaticSelectionEnabled = false;
// Set the height for the collapsed sheet.
config.useCase.sheet.collapsedVisibleHeight = 'LARGE';
// Enable manual count change.
config.useCase.sheetContent.manualCountChangeEnabled = true;
// Set the delay before same barcode counting repeat.
config.useCase.countingRepeatDelay = 1000;
// Configure the submit button.
config.useCase.sheetContent.submitButton.text = 'Submit';
config.useCase.sheetContent.submitButton.foreground.color = '#000000';
// Configure other parameters, pertaining to findAndPick-scanning mode as needed.
// Set the expected barcodes.
config.useCase.expectedBarcodes = [
new ExpectedBarcode({
barcodeValue: '123456',
title: 'numeric barcode',
count: 4,
image: 'https://avatars.githubusercontent.com/u/1454920',
}),
new ExpectedBarcode({
barcodeValue: 'SCANBOT',
title: 'value barcode',
count: 3,
image: 'https://avatars.githubusercontent.com/u/1454920',
}),
];
// Set an array of accepted barcode types.
config.recognizerConfiguration.barcodeFormats = acceptedBarcodeFormats;
config.recognizerConfiguration.acceptedDocumentFormats = acceptedBarcodeDocumentFormats;
// Configure other parameters as needed.
const result = await startBarcodeScanner(config);
/**
* Handle the result if result status is OK
*/
if (result.status === 'OK' && result.data) {
navigation.navigate(Screens.BARCODE_RESULTS, result.data);
}
} catch (e: any) {
errorMessageAlert(e.message);
}
AR Overlay
The Barcode AR Overlay can be enabled to display and select recognized barcodes in an augmented-reality fashion. Each recognized barcode will be presented on the barcode overlay by a colored frame and text. The style of the frame and text can be customized for scanned and not-yet-scanned barcodes. Barcodes can be selected automatically or by tapping on the barcode overlay.
try {
/**
* Check license status and return early
* if the license is not valid
*/
if (!(await checkLicense())) {
return;
}
/**
* Instantiate a configuration object of BarcodeScannerConfiguration and
* start the barcode scanner with the configuration
*/
const config = new BarcodeScannerConfiguration();
// Configure the usecase.
config.useCase = new MultipleScanningMode();
config.useCase.mode = 'UNIQUE';
config.useCase.sheet.mode = 'COLLAPSED_SHEET';
config.useCase.sheet.collapsedVisibleHeight = 'SMALL';
// Configure AR Overlay.
config.useCase.arOverlay.visible = true;
config.useCase.arOverlay.automaticSelectionEnabled = false;
// Configure other parameters, pertaining to use case as needed.
// Set an array of accepted barcode types.
config.recognizerConfiguration.barcodeFormats = acceptedBarcodeFormats;
config.recognizerConfiguration.acceptedDocumentFormats = acceptedBarcodeDocumentFormats;
// Configure other parameters as needed.
const result = await startBarcodeScanner(config);
/**
* Handle the result if result status is OK
*/
if (result.status === 'OK' && result.data) {
navigation.navigate(Screens.BARCODE_RESULTS, result.data);
}
} catch (e: any) {
errorMessageAlert(e.message);
}
Display product information right in your scanning interface
Some use cases require the data connected to a barcode's value to be displayed to the user directly. That is why we have added the option to visualize this data in the scanning interface. For example, you can show a product image next to the article number encoded by the barcode.
This feature is also available for the SDK's AR Overlay, making it even easier for users to identify a barcode's contents in real time.
import {
BarcodeMappedData,
BarcodeScannerConfiguration,
SingleScanningMode,
} from 'react-native-scanbot-barcode-scanner-sdk/ui_v2';
function rtuUiV2MappingItemConfiguration() {
// Create the default configuration object.
const config = new BarcodeScannerConfiguration();
config.useCase = new SingleScanningMode();
config.useCase.barcodeInfoMapping.barcodeItemMapper = (barcodeItem, onResult, onError) => {
/** TODO: process scan result as needed to get your mapped data,
* e.g. query your server to get product image, title and subtitle.
*
* Note: The built-in fetch API won't work properly in this case.
* To request from the server, please use XMLHttpRequest API or another 3rd party library such as axios.
*
* See example below.
*/
const title = `Some product ${barcodeItem.textWithExtension}`;
const subtitle = barcodeItem.type ?? 'Unknown';
// If image from URL is used, on Android platform INTERNET permission is required.
const image = 'https://avatars.githubusercontent.com/u/1454920';
// To show captured barcode image use BarcodeMappedData.barcodeImageKey
// const image = BarcodeMappedData.barcodeImageKey;
/** Call onError() in case of error during obtaining mapped data. */
if (barcodeItem.textWithExtension === 'Error occurred!') {
onError();
} else {
onResult(
new BarcodeMappedData({
title: title,
subtitle: subtitle,
barcodeImage: image,
}),
);
}
};
// Configure other parameters as needed.
}
Full example source code of the RTU UI Barcode Scanner
You can refer to a full example implementation in our source code demo.
Full API reference
You can find the full API reference for all classes using this link.
Want to scan longer than one minute?
Generate a free trial license to test the Scanbot SDK thoroughly.
Get your free Trial LicenseWhat do you think of this documentation?
What can we do to improve it? Please be as detailed as you like.