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

Kiosk Pro Enterprise

  • 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 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


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:

  • cancelButtonTitle - [string] the text to be shown in lieu of the standard 'Cancel' button shown during scanning
  • helpScreenDoneButtonTitle - [string] the text to be shown in lieu of the standard 'Cancel' button shown during scanning
  • helpScreenImageName - [string] the filename for image to be shown when visitor touches the 'i' icon for assistance during scanning.  This image should be sized for the iPad being used and must be stored locally in the app's documents folder in a folder labeled 'KioskAssets'.
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
  • data - [string] the decrypted code as text
  • type - [integer] representing the type of bar code. The following codes are possible:
    • 0 = no symbol decoded
    • 1 = intermediate status
    • 2 = GS1 2-digit add-on
    • 5 = GS1 5-digit add-on
    • 8 = EAN-8
    • 9 = UPC-E
    • 10 = ISBN-10 (from EAN-13)
    • 12 = UPC-A
    • 13 = EAN-13
    • 14 = ISBN-13 (from EAN-13)
    • 15 = EAN/UPC composite
    • 34 = GS1 DataBar (RSS)
    • 35 = GS1 DataBar Expanded
    • 39 = Code 39
    • 57 = PDF417
    • 64 = QR Code
    • 93 = Code 93
    • 128 = Code 128


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 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
  • errorCode - [integer] representing the type of error. Possible values are:
    • -1002 = camera access is not authorized in iOS settings for Kiosk Pro
    • -1001 = scanning is not enabled in Kiosk Pro's settings
    • -1000 = scanning is currently in progress
    • 1 = internal error in scanning library


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
  • supported - [boolean integer] representing whether there is currently a camera selected for scanning in Kiosk Pro's settings:
    • 1 = if scanning is enabled in Kiosk Pro's settings
    • 0 = if scanning is not enabled in Kiosk Pro's settings


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

Still stuck? How can we help? How can we help?