Scan API: Native Camera

Kiosk Pro supports scanning barcodes and QR codes using the iPad's native cameras through an open-source library called ZBar. In recent testing, we've learned that using the front camera on an iPad is not always reliable for scanning. We highly recommend using the device's rear camera when possible.

This JavaScript API triggers a scan, at which point the camera goes full-screen to allow the visitor to position the code for scanning. When a barcode is detected, the scan completes and the data from the barcode is returned through a callback. Additional callbacks alert your page when a scan is manually cancelled, times out, or returns an error.

Functions

Callbacks

Related Settings

Requirements

  • Access JavaScript API
    • By Import - recommended, works both online & offline, requires inclusion of kiosk_functions.js prior to any of the following calls.
    • By Injection - only works offline, may not be available 'onload'.
  • Barcode & QR Code Scanning > Native Camera Scanning Settings > Camera = Front or Back

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 http://www.kioskproapp.com/scan-native-camera

Download Sample Code


kp_ZBarScanner_requestStateOfSupporting

This function determines whether scanning is enabled in Kiosk Pro's settings.

Format
kp_ZBarScanner_requestStateOfSupporting();
		

Status

Kiosk Pro will immediately call kp_ZBarScanner_stateOfSupportingDidChange with the current status.


kp_ZBarScanner_startScan

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();
		

Status

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


kp_ZBarScanner_cancelScan

This function cancels the current scanning process. If scanning is not in the progress, this function effectively does nothing.

Format
kp_ZBarScanner_cancelScan();
		

Status

Kiosk Pro will immediately call kp_ZBarScanner_scanDidCancel.


kp_ZBarScanner_scanDidFinishWithDataEx

This callback is triggered when the app finishes the scanning process successfully.

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_scanDidFinishWithDataEx(data, type);
		
Return values
  • data = decrypted code as string.
  • type = type of bar code as integer. 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

kp_ZBarScanner_scanDidFinishWithTimeout

This callback is triggered when the camera is unable to recognize any images as a valid barcode for a period of 15 seconds.

Format
kp_ZBarScanner_scanDidFinishWithTimeout();
		

kp_ZBarScanner_scanDidFailWithError

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 = code of error as integer. 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.

kp_ZBarScanner_scanDidCancel

This callback is triggered when scanning is manually cancelled by user.

Format
kp_ZBarScanner_scanDidCancel();
		

kp_ZBarScanner_stateOfSupportingDidChange

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 = supported state as boolean.
    • 1 = if scanning is enabled in Kiosk Pro's settings.
    • 0 = if scanning is not enabled in Kiosk Pro's settings.

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