Scan API: Bluetooth Barcode Scanning

Kiosk Pro Enterprise includes support for barcode scanners that can connect to the iPad via Bluetooth, returning the results of a scan directly to your page through a JavaScript callback.

This type of barcode scanner uses the iPad's native connection for Bluetooth keyboards to emulate keyboard input. This means that while the scanner is directly connected to the iPad, no on-screen keyboard will be shown when focus enters text fields so the use of this type of scanner is not recommended for projects where visitors would need access to the on-screen keyboard. Use of Bluetooth barcode scanners can also interfere with other types of inputs (for example, dropdown menus).

While certain scanners have physical buttons that allow you to connect and disconnect the scanner to gain access to the keyboard, we've had varying levels of success with these in testing and cannot provide support if problems arise.

There are two primary API calls - one that triggers an alert popup requesting a scan (with customizable text) and one that listens in the background for scanner data. Data encoded in the barcode or QR code is returned as a string to your page through a JavaScript callback.

Functions

Callbacks

Related Settings

Requirements

  • Kiosk Pro Enterprise, version 6.4 or later.
  • 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' event.
  • Barcode & QR Code Scanning > Bluetooth Scanning = ON
  • Connection to an iOS-compatible Bluetooth Barcode Scanner
    • iOS device must be paired with an iOS-compatible Bluetooth barcode scanner through the device's Settings > Bluetooth menu.

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/bluetooth-scanner

Download Sample Code


kp_BluetoothBarcodeScanner_requestStateOfSupporting

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

Format
kp_BluetoothBarcodeScanner_requestStateOfSupporting();
		

Status

Following this call, the app will immediately trigger kp_BluetoothBarcodeScanner_stateOfSupportingDidChange with the current state.


kp_BluetoothBarcodeScanner_requestAcceptingData

This function triggers a scan, showing a standard iOS alert box displayed over your content to notify the visitor that the barcode scanner is expecting them to scan; you can customize this alert with the text of your choice.

Format
kp_BluetoothBarcodeScanner_requestAcceptingData(alertTitle, alertText, timeout);
		
Parameters
  • alertTitle = the title of the alert box shown, can be left blank if preferred by including "" in parameters.
  • alertText = the text of the alert box shown.
  • timeout = the number of seconds the alert box will be shown and data accepted from the scanner.

Status

Kiosk Pro will trigger one of the following callbacks depending on API availability, visitor action, and the results of the scan:


kp_BluetoothBarcodeScanner_requestSilentAcceptingData

This function allows your code to listen for data from the Bluetooth scanner silently without an explicit prompt or alert; this means that either your page or signage around the kiosk must direct the visitor to scan.

This function does not timeout, but needs to be called individually on any page that you want to accept scanning. If you call this function and then the user navigates to another page and attempts to scan without this function being called for that page as well, the results of the scan will not be returned.

Format
kp_BluetoothBarcodeScanner_requestSilentAcceptingData();
		

Status

Kiosk Pro will trigger one of the following callbacks depending on API availability, visitor action, and the results of the scan:


kp_BluetoothBarcodeScanner_stateOfSupportingDidChange

This callback is triggered:

Format
kp_BluetoothBarcodeScanner_stateOfSupportingDidChange(supported);
		
Return values
  • supported = supported state as a boolean.
    • 1 = 'Bluetooth Scanning' is enabled in Kiosk Pro's settings.
    • 0 = 'Bluetooth Scanning' is disabled in Kiosk Pro's settings.


kp_BluetoothBarcodeScanner_dataAcceptingDidFinishWithData

This callback is triggered when requesting data is returned successfully by:

Format
kp_BluetoothBarcodeScanner_dataAcceptingDidFinishWithData(data);
		
Return values data = interpreted data from the scan as a string.

kp_BluetoothBarcodeScanner_dataAcceptingDidFinishWithTimeout

This callback is triggered after the timeout period defined as a parameter in kp_BluetoothBarcodeScanner_requestAcceptingData if no data has been successfully returned by the scanner.

Format
kp_BluetoothBarcodeScanner_dataAcceptingDidFinishWithTimeout();
		

BluetoothBarcodeScanner_dataAcceptingDidFailWithError

This callback is triggered if the data request kp_BluetoothBarcodeScanner_requestAcceptingData or kp_BluetoothBarcodeScanner_requestSilentAcceptingData fail due to an error.

Format
kp_BluetoothBarcodeScanner_dataAcceptingDidFailWithError(errorCode);
		
Return values
  • errorCode = code of error as an integer. The following are possible:
    • -1001 = 'Bluetooth Scanning' is disabled in Kiosk Pro's settings.
    • -1000 = Data has already been requested & the scanner is currently busy.

kp_BluetoothBarcodeScanner_dataAcceptingDidCancel

This callback is triggered when requesting data by kp_BluetoothBarcodeScanner_requestAcceptingData is cancelled by visitor.

Format
kp_BluetoothBarcodeScanner_dataAcceptingDidCancel();
		

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