API: Access IDs & Device Information

Access the Unique iPad ID and/or Group IDs defined in Kiosk Pro's settings in your content. This can let you identify which kiosk is requesting a page or to tag form data with the ID of the sending kiosk.

In this article

Requirements

  • 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
    • Identification > Unique iPad ID and/or Group IDs > configured

Triggers via API Functions

Check Unique iPad ID

Supported in:

Kiosk Pro Basic, Plus and Enterprise

This function triggers a callback returning the Unique iPad ID set in Kiosk Pro settings.

Format 
kp_requestKioskId(callback);
Parameters callback - [string] the name of the callback to be triggered after the function has been executed
Callback format 
callback(kioskId);
Callback return values kioskId - [string] the Unique iPad ID configured in Kiosk Pro's settings

Set Unique iPad ID

This function triggers setting the unique iPad ID in the app's settings.

Format 
kp_Identification_setKioskId(uniqueiPadId);
Parameters
  • uniqueiPadId - [string] the unique iPad ID to be configured for the device
    		•

    Check Group IDs

    Supported in:

    Kiosk Pro Plus and Enterprise

    This function triggers a callback returning any Group IDs set for that device in Kiosk Pro settings.

    Format 
    kp_Identification_getGroupIDs();

    Status

    Triggers kp_Identification_groupsIDsDidChange, which returns any Group IDs assigned to that device as an associative array.

    Check App Version Name

    Supported in:

    Kiosk Pro Basic, Plus and Enterprise

    This function triggers a callback returning the name of the Kiosk Pro app currently running on the device. For example, "Kiosk Pro Plus".

    Format 
    kp_VersionAPI_requestProductName(callback);
    Parameters callback - [string] the name of the callback to be triggered after the function has been executed
    Callback format 
    callback(productName);
    Callback return values productName - [string] the version name of the Kiosk Pro app currently running on the device

    Check App Version Number

    Supported in:

    Kiosk Pro Basic, Plus and Enterprise

    This function triggers a callback returning the main version number of the Kiosk Pro app currently running on the device. For example, "1.2".

    Format 
    kp_VersionAPI_requestMainVersion(callback);
    Parameters callback - [string] the name of the callback to be triggered after the function has been executed
    Callback format 
    callback(mainVersion);
    Callback return values mainVersion - [string] the main version number of the Kiosk Pro app currently running on the device

    Check Device Info

    Supported in:

    Kiosk Pro Plus and Enterprise

    This function triggers a callback returning arrays with known information about the device.

    Format 
    kp_Identification_requestDeviceContextInfo(callback);
    Parameters callback - [string] the name of the callback to be triggered after the function has been executed
    Callback format 
    callback(deviceInfo);
    Callback return values deviceInfo - [array] containing the following:
    • deviceIdentification - [array] containing key-value pairs for the following:
      • deviceName - [string] the name configured for the device in iOS/iPadOS settings under General > About. For example, “Bob’s iPad”. In iOS/iPadOS 16 and later, this name is no longer directly available to third-party apps and this will return a generic identifier.
      • deviceModelName - [string] the specific model of the device. For example, “iPad Pro 10.5" - WiFi (model A1701)”
      • deviceModelID - [string] the general model of the device as assigned by Apple. For example, “iPad7,3”. A key for these codes can be found here
    • versionIdentification - [array] containing key-value pairs for the following:
      • systemVersion - [string] the current version of the operating system. For example, “iOS 13.7”
    • diskIdentification - [array] containing key-value pairs for the following:
      • diskTotalSpace - [string] the total disk space on the device. For example, “59.60 GB”
      • diskFreeSpace - [string] the amount of free disk space on the device. For example, “84.69%, 50.48 GB”
      • diskUsedSpace - [string] the amount of used disk space on the device. For example, “15.31%, 9.13 GB”

    Check Device Time Zone

    Supported in:

    Kiosk Pro Plus and Enterprise

    This function triggers a callback returning arrays with the time zone currently configured for the device.

    Format 
    kp_Identification_requestDeviceContextInfo(callback);
    Parameters callback - [string] the name of the callback to be triggered after the function has been executed
    Callback format 
    callback(deviceInfo);
    Callback return values deviceInfo - [array] containing the following:
    • timeIdentification - [array] containing key-value pairs for the following:
      • timeZoneName - [string] the ID assigned by Apple for the time zone currently configured in the device settings. For example, “America/New_York”
      • timeZoneBias - [string] the temporal offset, either plus or minus, from Greenwich Mean Time (GMT) in minutes. For example, “-240”

    Check Network Info

    Supported in:

    Kiosk Pro Plus and Enterprise

    This function triggers a callback returning arrays with network and cellular carrier (if applicable) information for the device.

    Format 
    kp_Identification_requestDeviceContextInfo(callback);
    Parameters callback - [string] the name of the callback to be triggered after the function has been executed
    Callback format 
    callback(deviceInfo);
    Callback return values deviceInfo - [array] containing the following:
    • networkIdentification - [array] containing key-value pairs for the following:
      • currentIPAddress - [string] the internal IP address of your network. For example, “192.168.0.100”
      • externalIPAddress - [string] the public IP address assigned to the router interface that is connected to the Internet. For example, “11.222.333.444”
      • connectedToWiFi - [boolean integer] representing whether the device is currently connected to a WiFi network. 0 - no, 1= yes
      • wifiIPAddress - [string] the internal IP address of the current WiFi network. For example, “192.168.0.100”
      • wifiBroadcastAddress - [string] the broadcast IP address of the current WiFi network. For example, “192.168.0.255”
      • connectedToCellNetwork - [boolean integer] representing whether the device is currently connected to a cellular network. 0 - no, 1 - yes
      • cellIPAddress - [string] the internal IP address of the current WiFi network
      • cellBroadcastAddress - [string] the broadcast IP address of the current WiFi network
    • carrierIdentificationArray - [array] containing key-value pairs for the following:
      • carrierName - [string] the name of the current cellular service provider. For example, “Verizon”. More detail here
      • carrierCountry - [string] the country for the current cellular service provider
      • carrierISOCountryCode - [string] the ISO country code for the current cellular service provider. More detail here
      • carrierMobileCountryCode - [string] the mobile country code (MCC) for the current cellular service provider. More detail here. 
      • carrierMobileNetworkCode - [string] the mobile network code for current cellular service provider. More detail here. 
      • carrierAllowsVOIP - [boolean integer] representing whether the carrier allows making VoIP calls on its network. 0 - no, 1= yes. More detail here

    Notifications via API Callbacks

    On Group ID Change or API Request

    Supported in:

    Kiosk Pro Plus and Enterprise

    This callback returns any Group IDs set for the device in Kiosk Pro settings as an associative array. Triggered by kp_Identification_getGroupIDs or a detected change in the Group IDs assigned in Kiosk Pro's settings.

    Format 
    kp_Identification_groupsIDsDidChange(groupIDs);
    Return Values groupIDs - an associative array containing Group IDs as key-value pairs. The following keys are supported (with spacing and capitalization as shown):
    • GroupID1
    • GroupID2
    • GroupID3
    • GroupID4
    • GroupID5
    • GroupID6
    • UniqueiPadID
    • KioskProductNameWithFullVersion
    • WebViewType

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

    Change Log

    • Ability to return the Unique iPad ID added in version 1.1. 
    • Ability to return the app version name and number added in version 5.4. 
    • Ability to set and return group IDs added in version 6.6. 
    • Ability to return device info, time zone, and network info in version 10.0.
    • Ability to set Unique iPad ID added in version 10.1.

    Related Articles

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