API: Receive Click Notification from Flic 2 Smart Button

Receive input from a physical button using a Flic 2. This functionality is great for kiosk deployments where you want visitors to be able to trigger content without using/touching a device, or for home automation.

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
    • Content > JavaScript API > Access JavaScript API = By Import
  • iOS/iPadOS Permissions
    • Bluetooth - more on enabling specific iOS/iPadOS permissions here.
  • Physical Hardware

Triggers via API Functions

Start Scanning for a Flic

This function scans for a Flic to pair with. When a Flic is found, an alert will appear asking for permission to pair your iPad with the Flic, which you will need to accept.

Format 
kp_Flic2ButtonAPI_startScan();
Triggers This call immediately triggers kp_Flic2ButtonAPI_didUpdateScanningState and kp_Flic2ButtonAPI_scannerDidUpdateStatus.

Stop Scanning for a Flic

This function stops scanning for a Flic to pair with.

Format 
kp_Flic2ButtonAPI_stopScan();
Triggers This call immediately triggers kp_Flic2ButtonAPI_didUpdateScanningState and kp_Flic2ButtonAPI_scannerDidUpdateStatus.

Restore Previously Connected Flics

This function restores Flics that were connected in a previous session. This call can only be triggered once per app session (reset when the app is terminated). Additional calls will show the list of Flics that were connected at the time of the first call.

Format 
kp_Flic2ButtonAPI_init();
Triggers This call immediately triggers kp_Flic2ButtonAPI_managerDidRestoreState and kp_Flic2ButtonAPI_managerDidUpdateState.

Forget a Flic

This function tells Kiosk Pro to forget a Flic that it has already paired with. This is helpful if you need to swap the buttons being used.

Format 
kp_Flic2ButtonAPI_forgetButton(buttonUUID);
Parameters buttonUUID - [string] the Flic button's UUID
Triggers This call triggers kp_Flic2ButtonAPI_didForgetButton.

Update Nickname of Flic

This function changes the nickname of a Flic.

Format 
kp_Flic2ButtonAPI_updateNickname(newNickname, buttonUUID);
Parameters
  • newNickname - [string] the nickname you want to give the Flic button
  • buttonUUID - [string] the Flic button's UUID
Triggers This call triggers kp_Flic2ButtonAPI_didForgetButton.

Notifications via API Callbacks

When Scanning Starts or Stops

This callback triggers when a Flic status changes while scanning.

Format 
kp_Flic2ButtonAPI_didUpdateScanningState(isScanning);
Return Values
  • isScanning - [string] the status of the scan. Possible values:
    • Scanning - scanning for a Flic
    • Not scanning - scanning has stopped

When Flic Status Changes During Scanning

This callback triggers when a Flic status changes while scanning.

Format 
kp_Flic2ButtonAPI_scannerDidUpdateStatus(status, discoveryResult);
Return Values
  • status - [string] the status of a found Flic
  • discoveryResult - [array] details about the Flic and the error. Possible values:
    • button - [array] details about the Flic. Possible values:
      • batteryVoltage - [integer] the Flic's battery voltage
      • serialNumber - [string] the Flic's serial number
      • triggerMode - [integer] type of click events used by the Flic.
        • 0 - click and hold events
        • 1 - click and double-click events
        • 2 - click, double-click and hold events
        • 3 - click events only
      • identifier - [string] a general Flic identifier that is the same for every Flic
      • name - [string] the bluetooth advertisement name of the Flic
      • uuid - [string] the unique identifier for the Flic
      • nickname - [string] the customizable nickname for the Flic
      • bluetoothAddress - [string] the bluetooth address of the Flic
      • state - [integer] the connection state of the Flic. Possible values:
        • 0 - disconnected
        • 1 - connecting
        • 2 - connected
        • 3 - disconnecting
      • pressCount - [integer] total number of clicks for the Flic
      • firmwareRevision - [integer] the revision of the firmware currently running on the Flic
      • isReady - [integer] whether the Flic is ready to receive click events. Possible values:
        • 0 - not ready
        • 1 - ready
      • isUnpaired - [integer] whether the Flic pairing with Kiosk Pro is valid. Possible values:
        • 0 - unpaired
        • 1 - paired
    • error - [array] details about the error, including:
      • code - [integer] error code
      • description - [string] description of the error
      • domain - [string] where the error occurred
      • debugDescription - [string] detailed description of the error

When Flic is Forgotten

This callback triggers when a Flic is forgotten.

Format 
kp_Flic2ButtonAPI_didForgetButton(flicButtonUUID, error);
Return Values
  • flicButtonUUID - [string] the unique identifier for the Flic
  • error - [array] details about the error, including:
    • code - [integer] error code
    • description - [string] description of the error
    • domain - [string] where the error occurred
    • debugDescription - [string] detailed description of the error

When Flic Failed to Update Nickname

This callback triggers when the Flic unpairs from the device.

Format 
kp_Flic2ButtonAPI_didFailUpdateNicknameOfButton(nickname, flicButtonUUID, error);
Return Values
  • nickname - [string] the customizable nickname for the Flic
  • flicButtonUUID - [string] the unique identifier for the Flic
  • error - [array] details about the error, including:
    • code - [integer] error code
    • description - [string] description of the error
    • domain - [string] where the error occurred
    • debugDescription - [string] detailed description of the error

When the Flic Manager Restores Flics from Previous Sessions

This callback triggers when the Flic Manager is restored, making Flics that were connected in the previous app session available.

Format 
kp_Flic2ButtonAPI_managerDidRestoreState(listOfRestoredButtons);
Return Values
  • listOfRestoredButtons - [array] contains information about restored Flics, including:
    • batteryVoltage - [integer] the Flic's battery voltage
    • serialNumber - [string] the Flic's serial number
    • triggerMode - [integer] type of click events used by the Flic.
      • 0 - click and hold events
      • 1 - click and double-click events
      • 2 - click, double-click and hold events
      • 3 - click events only
    • identifier - [string] a general Flic identifier that is the same for every Flic
    • name - [string] the bluetooth advertisement name of the Flic
    • uuid - [string] the unique identifier for the Flic
    • nickname - [string] the customizable nickname for the Flic
    • bluetoothAddress - [string] the bluetooth address of the Flic
    • state - [integer] the connection state of the Flic. Possible values:
      • 0 - disconnected
      • 1 - connecting
      • 2 - connected
      • 3 - disconnecting
    • pressCount - [integer] total number of clicks for the Flic
    • firmwareRevision - [integer] the revision of the firmware currently running on the Flic
    • isReady - [integer] whether the Flic is ready to receive click events. Possible values:
      • 0 - not ready
      • 1 - ready
    • isUnpaired - [integer] whether the Flic pairing with Kiosk Pro is valid. Possible values:
      • 0 - unpaired
      • 1 - paired

When the Flic Manager State is Updated

This callback triggers when the Flic Manager state updates, either when the Flic Manager is restored or when a Bluetooth connection changes.

Format 
kp_Flic2ButtonAPI_managerDidUpdateState(managerState);
Return Values managerState - [string] the manager instance that the event originates from

When Flic Connects

This callback triggers when the Flic connects to the device.

Format 
kp_Flic2ButtonAPI_buttonDidConnect(button, error);
Return Values
  • button - [array] contains details about the Flic. Possible values:
    • batteryVoltage - [integer] the Flic's battery voltage
    • serialNumber - [string] the Flic's serial number
    • triggerMode - [integer] type of click events used by the Flic.
      • 0 - click and hold events
      • 1 - click and double-click events
      • 2 - click, double-click and hold events
      • 3 - click events only
    • identifier - [string] a general Flic identifier that is the same for every Flic
    • name - [string] the bluetooth advertisement name of the Flic
    • uuid - [string] the unique identifier for the Flic
    • nickname - [string] the customizable nickname for the Flic
    • bluetoothAddress - [string] the bluetooth address of the Flic
    • state - [integer] the connection state of the Flic. Possible values:
      • 0 - disconnected
      • 1 - connecting
      • 2 - connected
      • 3 - disconnecting
    • pressCount - [integer] total number of clicks for the Flic
    • firmwareRevision - [integer] the revision of the firmware currently running on the Flic
    • isReady - [integer] whether the Flic is ready to receive click events. Possible values:
      • 0 - not ready
      • 1 - ready
    • isUnpaired - [integer] whether the Flic pairing with Kiosk Pro is valid. Possible values:
      • 0 - unpaired
      • 1 - paired

When Flic is Ready for Click Events

This callback triggers when the Flic is ready to receive click events.

Format 
kp_Flic2ButtonAPI_buttonIsReady(button);
Return Values
  • button - [array] contains details about the Flic. Possible values:
    • batteryVoltage - [integer] the Flic's battery voltage
    • serialNumber - [string] the Flic's serial number
    • triggerMode - [integer] type of click events used by the Flic.
      • 0 - click and hold events
      • 1 - click and double-click events
      • 2 - click, double-click and hold events
      • 3 - click events only
    • identifier - [string] a general Flic identifier that is the same for every Flic
    • name - [string] the bluetooth advertisement name of the Flic
    • uuid - [string] the unique identifier for the Flic
    • nickname - [string] the customizable nickname for the Flic
    • bluetoothAddress - [string] the bluetooth address of the Flic
    • state - [integer] the connection state of the Flic. Possible values:
      • 0 - disconnected
      • 1 - connecting
      • 2 - connected
      • 3 - disconnecting
    • pressCount - [integer] total number of clicks for the Flic
    • firmwareRevision - [integer] the revision of the firmware currently running on the Flic
    • isReady - [integer] whether the Flic is ready to receive click events. Possible values:
      • 0 - not ready
      • 1 - ready
    • isUnpaired - [integer] whether the Flic pairing with Kiosk Pro is valid. Possible values:
      • 0 - unpaired
      • 1 - paired

When Flic Disconnects

This callback triggers when the Flic disconnects from the device.

Format 
kp_Flic2ButtonAPI_buttonDidDisconnect(button, error);
Return Values
  • button - [array] contains details about the Flic. Possible values:
    • batteryVoltage - [integer] the Flic's battery voltage
    • serialNumber - [string] the Flic's serial number
    • triggerMode - [integer] type of click events used by the Flic.
      • 0 - click and hold events
      • 1 - click and double-click events
      • 2 - click, double-click and hold events
      • 3 - click events only
    • identifier - [string] a general Flic identifier that is the same for every Flic
    • name - [string] the bluetooth advertisement name of the Flic
    • uuid - [string] the unique identifier for the Flic
    • nickname - [string] the customizable nickname for the Flic
    • bluetoothAddress - [string] the bluetooth address of the Flic
    • state - [integer] the connection state of the Flic. Possible values:
      • 0 - disconnected
      • 1 - connecting
      • 2 - connected
      • 3 - disconnecting
    • pressCount - [integer] total number of clicks for the Flic
    • firmwareRevision - [integer] the revision of the firmware currently running on the Flic
    • isReady - [integer] whether the Flic is ready to receive click events. Possible values:
      • 0 - not ready
      • 1 - ready
    • isUnpaired - [integer] whether the Flic pairing with Kiosk Pro is valid. Possible values:
      • 0 - unpaired
      • 1 - paired
  • error - [array] details about the error, including:
    • code - [integer] error code
    • description - [string] description of the error
    • domain - [string] where the error occurred
    • debugDescription - [string] detailed description of the error

When Flic Fails to Connect

This callback triggers when the Flic fails to connect.

Format 
kp_Flic2ButtonAPI_buttonDidFailToConnect(button, error);
Return Values
  • button - [array] contains details about the Flic. Possible values:
    • batteryVoltage - [integer] the Flic's battery voltage
    • serialNumber - [string] the Flic's serial number
    • triggerMode - [integer] type of click events used by the Flic.
      • 0 - click and hold events
      • 1 - click and double-click events
      • 2 - click, double-click and hold events
      • 3 - click events only
    • identifier - [string] a general Flic identifier that is the same for every Flic
    • name - [string] the bluetooth advertisement name of the Flic
    • uuid - [string] the unique identifier for the Flic
    • nickname - [string] the customizable nickname for the Flic
    • bluetoothAddress - [string] the bluetooth address of the Flic
    • state - [integer] the connection state of the Flic. Possible values:
      • 0 - disconnected
      • 1 - connecting
      • 2 - connected
      • 3 - disconnecting
    • pressCount - [integer] total number of clicks for the Flic
    • firmwareRevision - [integer] the revision of the firmware currently running on the Flic
    • isReady - [integer] whether the Flic is ready to receive click events. Possible values:
      • 0 - not ready
      • 1 - ready
    • isUnpaired - [integer] whether the Flic pairing with Kiosk Pro is valid. Possible values:
      • 0 - unpaired
      • 1 - paired
  • error - [array] details about the error, including:
    • code - [integer] error code
    • description - [string] description of the error
    • domain - [string] where the error occurred
    • debugDescription - [string] detailed description of the error

When Flic Enters Down State

This callback triggers when the Flic goes into a down state.

Format 
kp_Flic2ButtonAPI_buttonDidReceiveButtonDown(button, queued, age);
Return Values
  • button - [array] contains details about the Flic. Possible values:
    • batteryVoltage - [integer] the Flic's battery voltage
    • serialNumber - [string] the Flic's serial number
    • triggerMode - [integer] type of click events used by the Flic.
      • 0 - click and hold events
      • 1 - click and double-click events
      • 2 - click, double-click and hold events
      • 3 - click events only
    • identifier - [string] a general Flic identifier that is the same for every Flic
    • name - [string] the bluetooth advertisement name of the Flic
    • uuid - [string] the unique identifier for the Flic
    • nickname - [string] the customizable nickname for the Flic
    • bluetoothAddress - [string] the bluetooth address of the Flic
    • state - [integer] the connection state of the Flic. Possible values:
      • 0 - disconnected
      • 1 - connecting
      • 2 - connected
      • 3 - disconnecting
    • pressCount - [integer] total number of clicks for the Flic
    • firmwareRevision - [integer] the revision of the firmware currently running on the Flic
    • isReady - [integer] whether the Flic is ready to receive click events. Possible values:
      • 0 - not ready
      • 1 - ready
    • isUnpaired - [integer] whether the Flic pairing with Kiosk Pro is valid. Possible values:
      • 0 - unpaired
      • 1 - paired
  • queued - [integer] whether the click event was queued or happened in real time. Possible values:
    • 0 - not queued
    • 1 - queued
  • age - [integer] the age of the click event in seconds if it was queued

When Flic Enters Up State

This callback triggers when the Flic goes into an up state.

Format 
kp_Flic2ButtonAPI_buttonDidReceiveButtonUp(button, queued, age);
Return Values
  • button - [array] contains details about the Flic. Possible values:
    • batteryVoltage - [integer] the Flic's battery voltage
    • serialNumber - [string] the Flic's serial number
    • triggerMode - [integer] type of click events used by the Flic.
      • 0 - click and hold events
      • 1 - click and double-click events
      • 2 - click, double-click and hold events
      • 3 - click events only
    • identifier - [string] a general Flic identifier that is the same for every Flic
    • name - [string] the bluetooth advertisement name of the Flic
    • uuid - [string] the unique identifier for the Flic
    • nickname - [string] the customizable nickname for the Flic
    • bluetoothAddress - [string] the bluetooth address of the Flic
    • state - [integer] the connection state of the Flic. Possible values:
      • 0 - disconnected
      • 1 - connecting
      • 2 - connected
      • 3 - disconnecting
    • pressCount - [integer] total number of clicks for the Flic
    • firmwareRevision - [integer] the revision of the firmware currently running on the Flic
    • isReady - [integer] whether the Flic is ready to receive click events. Possible values:
      • 0 - not ready
      • 1 - ready
    • isUnpaired - [integer] whether the Flic pairing with Kiosk Pro is valid. Possible values:
      • 0 - unpaired
      • 1 - paired
  • queued - [integer] whether the click event was queued or happened in real time. Possible values:
    • 0 - not queued
    • 1 - queued
  • age - [integer] the age of the click event in seconds if it was queued

When Flic is Clicked

This callback triggers when the Flic is clicked.

Format 
kp_Flic2ButtonAPI_buttonDidReceiveButtonClick(button, queued, age);
Return Values
  • button - [array] contains details about the Flic. Possible values:
    • batteryVoltage - [integer] the Flic's battery voltage
    • serialNumber - [string] the Flic's serial number
    • triggerMode - [integer] type of click events used by the Flic.
      • 0 - click and hold events
      • 1 - click and double-click events
      • 2 - click, double-click and hold events
      • 3 - click events only
    • identifier - [string] a general Flic identifier that is the same for every Flic
    • name - [string] the bluetooth advertisement name of the Flic
    • uuid - [string] the unique identifier for the Flic
    • nickname - [string] the customizable nickname for the Flic
    • bluetoothAddress - [string] the bluetooth address of the Flic
    • state - [integer] the connection state of the Flic. Possible values:
      • 0 - disconnected
      • 1 - connecting
      • 2 - connected
      • 3 - disconnecting
    • pressCount - [integer] total number of clicks for the Flic
    • firmwareRevision - [integer] the revision of the firmware currently running on the Flic
    • isReady - [integer] whether the Flic is ready to receive click events. Possible values:
      • 0 - not ready
      • 1 - ready
    • isUnpaired - [integer] whether the Flic pairing with Kiosk Pro is valid. Possible values:
      • 0 - unpaired
      • 1 - paired
  • queued - [integer] whether the click event was queued or happened in real time. Possible values:
    • 0 - not queued
    • 1 - queued
  • age - [integer] the age of the click event in seconds if it was queued

When Flic is Double-Clicked

This callback triggers when the Flic is double-clicked.

Format 
kp_Flic2ButtonAPI_buttonDidReceiveButtonHold(button, queued, age);
Return Values
  • button - [array] contains details about the Flic. Possible values:
    • batteryVoltage - [integer] the Flic's battery voltage
    • serialNumber - [string] the Flic's serial number
    • triggerMode - [integer] type of click events used by the Flic.
      • 0 - click and hold events
      • 1 - click and double-click events
      • 2 - click, double-click and hold events
      • 3 - click events only
    • identifier - [string] a general Flic identifier that is the same for every Flic
    • name - [string] the bluetooth advertisement name of the Flic
    • uuid - [string] the unique identifier for the Flic
    • nickname - [string] the customizable nickname for the Flic
    • bluetoothAddress - [string] the bluetooth address of the Flic
    • state - [integer] the connection state of the Flic. Possible values:
      • 0 - disconnected
      • 1 - connecting
      • 2 - connected
      • 3 - disconnecting
    • pressCount - [integer] total number of clicks for the Flic
    • firmwareRevision - [integer] the revision of the firmware currently running on the Flic
    • isReady - [integer] whether the Flic is ready to receive click events. Possible values:
      • 0 - not ready
      • 1 - ready
    • isUnpaired - [integer] whether the Flic pairing with Kiosk Pro is valid. Possible values:
      • 0 - unpaired
      • 1 - paired
  • queued - [integer] whether the double-click event was queued or happened in real time. Possible values:
    • 0 - not queued
    • 1 - queued
  • age - [integer] the age of the double-click event in seconds if it was queued

When Flic is Held Down

This callback triggers when the Flic is held down.

Format 
kp_Flic2ButtonAPI_buttonDidReceiveButtonHold(button, queued, age);
Return Values
  • button - [array] contains details about the Flic. Possible values:
    • batteryVoltage - [integer] the Flic's battery voltage
    • serialNumber - [string] the Flic's serial number
    • triggerMode - [integer] type of click events used by the Flic.
      • 0 - click and hold events
      • 1 - click and double-click events
      • 2 - click, double-click and hold events
      • 3 - click events only
    • identifier - [string] a general Flic identifier that is the same for every Flic
    • name - [string] the bluetooth advertisement name of the Flic
    • uuid - [string] the unique identifier for the Flic
    • nickname - [string] the customizable nickname for the Flic
    • bluetoothAddress - [string] the bluetooth address of the Flic
    • state - [integer] the connection state of the Flic. Possible values:
      • 0 - disconnected
      • 1 - connecting
      • 2 - connected
      • 3 - disconnecting
    • pressCount - [integer] total number of clicks for the Flic
    • firmwareRevision - [integer] the revision of the firmware currently running on the Flic
    • isReady - [integer] whether the Flic is ready to receive click events. Possible values:
      • 0 - not ready
      • 1 - ready
    • isUnpaired - [integer] whether the Flic pairing with Kiosk Pro is valid. Possible values:
      • 0 - unpaired
      • 1 - paired
  • queued - [integer] whether the hold event was queued or happened in real time. Possible values:
    • 0 - not queued
    • 1 - queued
  • age - [integer] the age of the hold event in seconds if it was queued

When Flic Unpairs from Device

This callback triggers when the Flic unpairs from the device.

Format 
kp_Flic2ButtonAPI_buttonDidUnpair(button, error);
Return Values
  • button - [array] contains details about the Flic. Possible values:
    • batteryVoltage - [integer] the Flic's battery voltage
    • serialNumber - [string] the Flic's serial number
    • triggerMode - [integer] type of click events used by the Flic.
      • 0 - click and hold events
      • 1 - click and double-click events
      • 2 - click, double-click and hold events
      • 3 - click events only
    • identifier - [string] a general Flic identifier that is the same for every Flic
    • name - [string] the bluetooth advertisement name of the Flic
    • uuid - [string] the unique identifier for the Flic
    • nickname - [string] the customizable nickname for the Flic
    • bluetoothAddress - [string] the bluetooth address of the Flic
    • state - [integer] the connection state of the Flic. Possible values:
      • 0 - disconnected
      • 1 - connecting
      • 2 - connected
      • 3 - disconnecting
    • pressCount - [integer] total number of clicks for the Flic
    • firmwareRevision - [integer] the revision of the firmware currently running on the Flic
    • isReady - [integer] whether the Flic is ready to receive click events. Possible values:
      • 0 - not ready
      • 1 - ready
    • isUnpaired - [integer] whether the Flic pairing with Kiosk Pro is valid. Possible values:
      • 0 - unpaired
      • 1 - paired
  • error - [array] details about the error, including:
    • code - [integer] error code
    • description - [string] description of the error
    • domain - [string] where the error occurred
    • debugDescription - [string] detailed description of the error

When Flic Battery Voltage Changes

This callback triggers when the Flic battery voltage changes.

Format 
kp_Flic2ButtonAPI_buttonDidUpdateBatteryVoltage(button, voltage);
Return Values
  • button - [array] contains details about the Flic. Possible values:
    • batteryVoltage - [integer] the Flic's battery voltage
    • serialNumber - [string] the Flic's serial number
    • triggerMode - [integer] type of click events used by the Flic.
      • 0 - click and hold events
      • 1 - click and double-click events
      • 2 - click, double-click and hold events
      • 3 - click events only
    • identifier - [string] a general Flic identifier that is the same for every Flic
    • name - [string] the bluetooth advertisement name of the Flic
    • uuid - [string] the unique identifier for the Flic
    • nickname - [string] the customizable nickname for the Flic
    • bluetoothAddress - [string] the bluetooth address of the Flic
    • state - [integer] the connection state of the Flic. Possible values:
      • 0 - disconnected
      • 1 - connecting
      • 2 - connected
      • 3 - disconnecting
    • pressCount - [integer] total number of clicks for the Flic
    • firmwareRevision - [integer] the revision of the firmware currently running on the Flic
    • isReady - [integer] whether the Flic is ready to receive click events. Possible values:
      • 0 - not ready
      • 1 - ready
    • isUnpaired - [integer] whether the Flic pairing with Kiosk Pro is valid. Possible values:
      • 0 - unpaired
      • 1 - paired
    • voltage - [integer] the Flic's battery voltage

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

Change Log

  • Added in version 10.0.

Related Articles

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