API: Scan Using Front & Rear Camera
Triggers a scan of supported bar codes and QR codes using the device's native cameras, returning the unencoded data to your content. We recommend using the device's rear camera whenever possible as the front camera on an iPad can be unreliable for use with the open-source ZBar library used for scanning due to its lower resolution and focal distance.
Requirements
- Integration of our JavaScript API into your webpage
- Sample code to run within the app and download for integration into your own project is available here.
- Best practices for working with the JavaScript API are available here.
- App Settings
- Content > JavaScript API > Access JavaScript API = By Import
- Device Access > Front & Rear Camera > Camera = Back (recommended) or Front
- iOS/iPadOS Permissions
- Camera - more on enabling specific iOS/iPadOS permissions here
Triggers via API Functions
Check if Native Camera Scanning is Enabled
This function determines whether scanning is enabled in Kiosk Pro's settings.
| Format | kp_ZBarScanner_requestStateOfSupporting(); |
| Triggers | Kiosk Pro will immediately call kp_ZBarScanner_stateOfSupportingDidChange with the current status |
Start Basic Scan
This function starts the scanning process. Certain parameters, including whether to use the front or rear camera by default and the type of bar codes supported, are pulled from Kiosk Pro's settings.
| Format | kp_ZBarScanner_startScan(); |
| Triggers | If scan completes successfully, the app will call kp_ZBarScanner_scanDidFinishWithDataEx If scanning is manually canceled by the visitor, the app will call kp_ZBarScanner_scanDidCancel If no barcode is successfully recognized in 15 seconds, the app will call kp_ZBarScanner_scanDidFinishWithTimeout If an error occurs during scanning or scanning is not enabled in Kiosk Pro's settings, the app will call kp_ZBarScanner_scanDidFailWithError |
Start Customized Scan
This function starts the scanning process and allows you to define optional translations for the onscreen 'Cancel' and Done' buttons, as well as a custom image to show if the visitor taps the 'i' icon for help scanning. Certain parameters, including whether to use the front or rear camera by default and the type of bar codes supported, are pulled from Kiosk Pro's settings.
| Format | kp_ZBarScanner_startScan(config); |
| Parameters | config - [JSON object] representing the following customizations to on-screen buttons and/or help image:
|
| Triggers | If scan completes successfully, the app will call kp_ZBarScanner_scanDidFinishWithDataEx If scanning is manually cancelled by the visitor, the app will call kp_ZBarScanner_scanDidCancel If no barcode is successfully recognized in 15 seconds, the app will call kp_ZBarScanner_scanDidFinishWithTimeout If an error occurs during scanning or scanning is not enabled in Kiosk Pro's settings, the app will call kp_ZBarScanner_scanDidFailWithError |
Cancel Scan
This function cancels the current scanning process. If scanning is not in progress, this function effectively does nothing.
| Format | kp_ZBarScanner_cancelScan(); |
| Triggers | Kiosk Pro will immediately call kp_ZBarScanner_scanDidCancel |
Notifications via API Callbacks
When Scan is Complete
This callback is triggered when the app finishes the scanning process successfully.
If the source image being scanned contains a valid code but this code does not match a supported type of code (as defined in Kiosk Pro settings) or if the source image does not contain a valid code, then this callback will not be triggered and the image will be ignored.
| Format | kp_ZBarScanner_scanDidFinishWithDataEx(data, type); |
| Return values |
|
On Scanning Timeout
This callback is triggered when the camera is unable to recognize any camera input as a valid barcode for a period of 15 seconds.
| Format | kp_ZBarScanner_scanDidFinishWithTimeout(); |
On Scanning Failure
This callback is triggered when an error occurs.
If the source image contains a valid code but this code does not match a supported type of code (as defined in Kiosk Pro settings) or if the source image does not contain a valid code, then this callback will not be triggered and the image will be ignored.
| Format | kp_ZBarScanner_scanDidFailWithError(errorCode); |
| Return values |
|
When Visitor Cancels Scanning
This callback is triggered when scanning is manually cancelled by user.
| Format | kp_ZBarScanner_scanDidCancel(); |
When Scan Availability Changes
This callback is triggered when function kp_ZBarScanner_requestStateOfSupporting is called or when the user changes Kiosk Pro's settings
| Format | kp_ZBarScanner_stateOfSupportingDidChange(supported); |
| Return values |
|
Sample Code
- This sample code relies on the JavaScript APIs built into Kiosk Pro and will not run successfully in other browsers or within our in-app help interface.
- To run sample code, set the app's homepage to kioskgroup.com/front-rear-camera-scanning-api
- To download a .zip of sample code, click here.
Change Log
- Added in version 3.1. Ability to cancel a scan added in version 3.3.1. Ability to trigger customized scan added in version 9.5