API: Return Data from Socket Mobile Scanners & RFID/NFC Readers

Scan barcodes and QR codes using a Socket Mobile S800 scanner or RFID and NFC cards, key fobs, tags, and labels using a SocketScan S550 contactless reader. This JavaScript API can return data, as well as check the connection status and battery level of the Socket Mobile devices.

In this article

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
    • JavaScript > Access JavaScript API > By Import
    • One of the following turned On:
      • Peripherals & Integrations > Card Readers > Enable Socket Mobile NFC Reader = On
      • Peripherals & Integrations > Other Peripherals & Integrations > External Barcode & QR Code Scanners > Enable Socket Mobile Scanner = On
  • iOS/iPadOS Permissions
    • Bluetooth - more on enabling specific iOS/iPadOS permissions here
  • Physical Hardware
    • Socket Mobile S800 scanner. Scanner must be set to "Application Mode". For more information about the Socket Mobile S800 scanner, click here.
    • Socket Mobile SocketScan S550 RFID reader. For more information about the SocketScan S550 RFID reader, click here.

Triggers via API Functions

Check if Device is Enabled

This function checks whether a Socket Mobile device is enabled in Kiosk Pro's settings.

Format 
kp_SocketScannerAPI_requestStateOfSupporting(callback);
Parameters callback - [string] the name of the callback to be triggered after the function has been executed
Callback format 
callback(supported);
Callback return values
  • supported - [integer] returns whether the Socket Mobile NFC Reader OR Socket Mobile Scanner settings are enabled. If both are enabled, this will return "0". Possible values are:
    • 0 - Not enabled
    • 1 - Enabled

Check Battery Level

This function checks the battery level of the Socket Mobile device.

Format 
kp_SocketScannerAPI_requestBatteryLevel();
Parameters callback - [string] the name of the callback to be triggered after the function has been executed
Callback format 
callback(levelInPercent)
Callback return values
  • levelInPercent - [integer] returns the battery level of the Socket Mobile device as a percentage. Possible values are:
    • -1 - Undefined, Socket Mobile device is likely not connected
    • 0-100 - Battery level

Notifications via API Callbacks

When Device is Connected

This callback triggers when the Socket Mobile device connects to Kiosk Pro.

Format 
kp_SocketScannerAPI_didConnectToDevice(device);
Return values
  • device - [associative array] key/value pairs containing information about the Socket Mobile device. Possible values are:
    • friendlyName - [string] name for identifying the device.
    • deviceType - [integer] device model as a SKT Capture device type numeric value, representing a combination of product type and interface. Returned as a large Objective-C enumeration.
    • deviceTypeFriendlyName - [string] model name of device.
    • guid - [string] unique identifier of device. Due to iPadOS privacy restrictions, this value changes every time the device is connected.

When Device is Disconnected

This callback triggers when the Socket Mobile device disconnects from Kiosk Pro.

Format 
kp_SocketScannerAPI_didDisconnectFromDevice(device);
Return values
  • device - [associative array] key/value pairs containing information about the Socket Mobile device. Possible values are:
    • friendlyName - [string] name for identifying the device.
    • deviceType - [integer] device model as a SKT Capture device type numeric value, representing a combination of product type and interface. Returned as a large Objective-C enumeration.
    • deviceTypeFriendlyName - [string] model name of device.
    • guid - [string] unique identifier of device. Due to iPadOS privacy restrictions, this value changes every time the device is connected.

When Data is Returned

This callback is triggered when the app returns data successfully.

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_SocketScannerAPI_didReceiveDecodedDataFromDevice(decodedData, device);
Return values
  • decodedData - [associative array] key/value pairs containing information about the data. Possible values are:
    • DataSourceID - [integer] decoded data source ID.
    • DataSourceIDFriendlyName - [string] readable decoded data source ID.
    • DataSourceName - [string] data source name.
    • DecodedData - [string] data returned from the barcode. Each byte transforms to string: @"%02X", (unsigned char)bytes[i].
    • StringFromDecodedData - [string] data returned from the barcode. This may not be returned if the data in the barcode is not UTF8 encoded.
  • device - [associative array] key/value pairs containing information about the Socket Mobile device. Possible values are:
    • friendlyName - [string] name for identifying the device.
    • deviceType - [integer] device model as a SKT Capture device type numeric value, representing a combination of product type and interface. Returned as a large Objective-C enumeration.
    • deviceTypeFriendlyName - [string] model name of device.
    • guid - [string] unique identifier of device. Due to iPadOS privacy restrictions, this value changes every time the device is connected.

When an Error is Returned

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_SocketScannerAPI_didReceiveError(error);
Return values
  • error - [associative array] key/value pairs containing information about the data. Possible values are:
    • domain - [string] where the error occurred
    • code - [integer] an identifier for the error
    • description - [string] a brief description of error
    • failureReason - [string] a reason for the error (optional, may return as empty)
    • recoverySuggestion - [string] a suggested solution (optional, may return as empty)
    • debugDescription - [string] a detailed description of the error (optional, may return as empty)

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 https://kioskgroup.com/socket-mobile-api
  • To download a .zip of sample code, click here.

Change Log

  • Added support for Socket Mobile S800 scanner in version 9.5.4. Added support for Socket Mobile SocketScan S550 NFC reader in version 10.1. 

Related Articles

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