API: Control & Trigger Fingerbot Button Press

Remotely trigger buttons and switches by connecting to a Fingerbot by Adaprox. This functionality is great for kiosk deployments that need to physically trigger something using the iPad, or for home automation.

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
  • iOS/iPadOS Permissions
    • Bluetooth - more on enabling specific iOS/iPadOS permissions here
  • Physical Hardware


Triggers via API Functions

Scan for Fingerbot

This function scans for Fingerbots.

Format
kp_FingerbotAPI_startScan();
		
Triggers This call immediately triggers kp_FingerbotAPI_didUpdateScanningState. If the scan fails to find a new Fingerbot it will trigger kp_FingerbotAPI_didFailToDiscoverNewDevices. If the scan fails due to a Bluetooth connection problem it will trigger kp_FingerbotAPI_didFailToDiscoverDevicesDueToBluetoothProblems.


Stop Scanning for Fingerbot

This function stops scanning for Fingerbots.

Format
kp_FingerbotAPI_stopScan();
		
Triggers This call immediately triggers kp_FingerbotAPI_didUpdateScanningState.


Get List of Connected Fingerbots

This function gets a list of Fingerbots that are currently connected.

Format
kp_FingerbotAPI_getAllConnectedDevices();
		
Triggers This call immediately triggers kp_FingerbotAPI_didUpdateDeviceList.


Check if Fingerbot is Connected

This function checks if a specific Fingerbot is connected.

Format
kp_FingerbotAPI_isDeviceConnected(deviceId);
		
Parameters
  • deviceId - [string] the Fingerbot identifier
  • Triggers If the Fingerbot is connected, this call triggers kp_FingerbotAPI_didConnectToDevice. Otherwise, this call triggers kp_FingerbotAPI_didDisconnectFromDevice. If the device cannot be found then kp_FingerbotAPI_didFailFindDeviceWithId will be triggered.


    Update Fingerbot Firmware

    This function updates the firmware on a specific Fingerbot. Note: calling this function disconnects the device, so you'll need to re-connect using kp_FingerbotAPI_connectToDevice after the update is finished.

    Format
    kp_FingerbotAPI_updateFirmwareVersionOnDevice(deviceId);
    		
    Parameters
  • deviceId - [string] the Fingerbot identifier
  • Triggers This call immediately triggers kp_FingerbotAPI_disconnectFromDevice, unless Kiosk Pro fails to find the device, in which case kp_FingerbotAPI_didFailFindDeviceWithId will be triggered. After you re-connect the Fingerbot, the kp_FingerbotAPI_didUpdateFirmwareVersionOnDevice callback will trigger.


    Connect to Fingerbot

    This function connects to a specific Fingerbot.

    Format
    kp_FingerbotAPI_connectToDevice(deviceId);
    		
    Parameters
  • deviceId - [string] the Fingerbot identifier
  • Triggers When connected, this call triggers kp_FingerbotAPI_didConnectToDevice. If the Fingerbot could not be found, kp_FingerbotAPI_didFailFindDeviceWithId is triggered. If the firmware was updated, this call will trigger When Firmware is Updated.


    Disconnect from Fingerbot

    This function disconnects from a specific Fingerbot.

    Format
    kp_FingerbotAPI_disconnectFromDevice(deviceId);
    		
    Parameters
  • deviceId - [string] the Fingerbot identifier
  • Triggers When disconnected, this call triggers kp_FingerbotAPI_didDisconnectFromDevice. Otherwise, this call triggers kp_FingerbotAPI_didFailFindDeviceWithId.


    Send Click Request to Fingerbot

    This function sends a click request to a specific Fingerbot.

    Format
    kp_FingerbotAPI_clickOnDevice(deviceId);
    		
    Parameters
  • deviceId - [string] the Fingerbot identifier
  • Triggers This call trigger when the click request is successful. If the Fingerbot cannot be found, kp_FingerbotAPI_didFailFindDeviceWithId is triggered.


    Get Battery Level from Fingerbot

    This function gets the battery percentage of a specific Fingerbot.

    Format
    kp_FingerbotAPI_refreshBatteryOnDevice(deviceId);
    		
    Parameters
  • deviceId - [string] the Fingerbot identifier
  • Triggers This call triggers kp_FingerbotAPI_didRefreshBatteryOnDevice. If the Fingerbot cannot be found, kp_FingerbotAPI_didFailFindDeviceWithId is triggered.


    Set Sustain Time on Fingerbot

    This function

    Format
    kp_FingerbotAPI_setSustainTimeOnDevice(deviceId, time);
    		
    Parameters
  • deviceId - [string] the Fingerbot identifier
  • time - [integer] the amount of time for the click to hold. Allowed values range from 0.2 to 10 seconds.
  • Triggers This call triggers kp_FingerbotAPI_didUpdateSustainTimeOnDevice. If the Fingerbot cannot be found, kp_FingerbotAPI_didFailFindDeviceWithId is triggered.


    Set Down Movement on Fingerbot

    This function

    Format
    kp_FingerbotAPI_setDownMovementOnDevice(deviceId, percent);
    		
    Parameters
  • deviceId - [string] the Fingerbot identifier
  • percent - [integer] how deep the Fingerbot should click. Allowed values range from 51 to 100 percent.
  • Triggers This call triggers kp_FingerbotAPI_didUpdateSustainTimeOnDevice. If the Fingerbot cannot be found, kp_FingerbotAPI_didFailFindDeviceWithId is triggered.


    Notifications via API Callbacks

    When Scanning Status Changes

    This callback is triggered when the scan for Fingerbots starts or ends.

    Format
    kp_FingerbotAPI_didUpdateScanningState(isScanning);
    		
    Return values isScanning - [integer] the status of the scan. Possible values include:
    • 0 - scanning ended
    • 1 - scanning started


    When Scanning Fails Due to Bluetooth

    This callback triggers if scanning fails because Bluetooth is turned off.

    Format
    kp_FingerbotAPI_didFailToDiscoverDevicesDueToBluetoothProblems();
    		


    When a Fingerbot Cannot be Found

    This callback triggers when a scan fails to find new devices.

    Format
    kp_FingerbotAPI_didFailToDiscoverNewDevices(callback);
    		


    When the Fingerbot List is Updated

    This callback triggers when a Fingerbot is found after scanning.

    Format
    kp_FingerbotAPI_didUpdateDeviceList(deviceList);
    		
    Return values
    • deviceList - [array] contains information about the device(s), including:
      • isConnected - [integer] whether the device is connected. Possible values:
        • 0 - disconnected
        • 1 - connected
      • deviceId - [string] the Fingerbot identifier


    When a Fingerbot with the Specified ID Cannot be Found

    This callback triggers when trying to communicate with a specific Fingerbot fails.

    Format
    kp_FingerbotAPI_didFailFindDeviceWithId(callback);
    		
    Return values deviceId - [string] the Fingerbot identifier


    When Firmware is Updated

    This callback triggers after connecting to a Fingerbot that had its firmware updated.

    Format
    kp_FingerbotAPI_didUpdateFirmwareVersionOnDevice(device, version);
    		
    Return values
    • device - [array] information about the Fingerbot including:
      • isConnected - [integer] whether the device is connected. Possible values:
        • 0 - disconnected
        • 1 - connected
      • deviceId - [string] the Fingerbot identifier
    • version - [string] the firmware version number


    When Getting Battery Status is Successful

    This callback triggers when getting the battery status of a Fingerbot is successful.

    Format
    kp_FingerbotAPI_didRefreshBatteryOnDevice(device, level);
    		
    Return values
    • device - [array] information about the Fingerbot including:
      • isConnected - [integer] whether the device is connected. Possible values:
        • 0 - disconnected
        • 1 - connected
      • deviceId - [string] the Fingerbot identifier
    • level - [integer] the percentage of the Fingerbot's battery level


    When Fingerbot Charging Status Changes

    This callback triggers when the charging status of a connected Fingerbot changes.

    Format
    kp_FingerbotAPI_didUpdateChargingOnDevice(device, chargingStatus);
    		
    Return values
    • device - [array] information about the Fingerbot including:
      • isConnected - [integer] whether the device is connected. Possible values:
        • 0 - disconnected
        • 1 - connected
      • deviceId - [string] the Fingerbot identifier
    • chargingStatus - [string] whether the Fingerbot is charging. Possible values:
      • None - not charging
      • Charging - charging


    When Fingerbot is Connected

    This callback triggers when a Fingerbot is connected.

    Format
    kp_FingerbotAPI_didConnectToDevice(device);
    		
    Return values
    • device - [array] information about the Fingerbot including:
      • isConnected - [integer] whether the device is connected. Possible values:
        • 0 - disconnected
        • 1 - connected
      • deviceId - [string] the Fingerbot identifier


    When Fingerbot is Disconnected

    This callback is triggered when a Fingerbot is disconnected.

    Format
    kp_FingerbotAPI_didDisconnectFromDevice(device);
    		
    Return values
    • device - [array] information about the Fingerbot including:
      • isConnected - [integer] whether the device is connected. Possible values:
        • 0 - disconnected
        • 1 - connected
      • deviceId - [string] the Fingerbot identifier


    When Fingerbot is Clicked

    This callback is triggered when a Fingerbot successfully receives a click request.

    Format
    kp_FingerbotAPI_didClickOnDevice(device);
    		
    Return values
    • device - [array] information about the Fingerbot including:
      • isConnected - [integer] whether the device is connected. Possible values:
        • 0 - disconnected
        • 1 - connected
      • deviceId - [string] the Fingerbot identifier


    When Down Movement is Updated

    This callback triggers after the down movement of the Fingerbot is updated.

    Format
    kp_FingerbotAPI_didUpdateDownMovementOnDevice(device, percent);
    		
    Return values
    • device - [array] information about the Fingerbot including:
      • isConnected - [integer] whether the device is connected. Possible values:
        • 0 - disconnected
        • 1 - connected
      • deviceId - [string] the Fingerbot identifier
    • percent - [integer] the percentage of depth the Fingerbot should move when clicking


    When Sustain Time is Updated

    This callback triggers after a Fingerbot's sustain time is updated.

    Format
    kp_FingerbotAPI_didUpdateSustainTimeOnDevice(device, time);
    		
    Return values
    • device - [array] information about the Fingerbot including:
      • isConnected - [integer] whether the device is connected. Possible values:
        • 0 - disconnected
        • 1 - connected
      • deviceId - [string] the Fingerbot identifier
    • time - [integer] the number of seconds that the Fingerbot should stay down when clicking


    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/fingerbot-api
    • To download a .zip of sample code, click here.

    Change Log

    • Added in version 10.0.

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