API: Navigate or Trigger Action Based on iBeacon Proximity

Create a location-aware interactive presentation by displaying specific content based on the device's proximity to an iBeacon. iBeacon is a Bluetooth advertising protocol designed by Apple with native support in iOS and iPadOS.

This functionality is useful for deployments where devices are distributed to visitors, like a multimedia tour of a museum.

Note that Kiosk Pro can also advertise as an iBeacon itself - more information on this functionality here.

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 & Location - more on enabling specific iOS/iPadOS permissions here.

Physical Hardware

iBeacon-enabled hardware.

Start Monitoring for iBeacons

This function starts monitoring for iBeacons. This function must also define a filepath to the schema file that instructs Kiosk Pro on how to respond to specific beacons.

Format	kp_iBeaconAPI_startMonitoringWithPath2SchemeFile(filepath);
Parameters	filepath - [string] path to the schema file. If remote, this should be the full URL. If local, this path should be relative to the Kiosk Pro documents folder (rather than relative to the file calling the function).
Triggers	If Kiosk Pro is unable tp find or parse the .xml file, the app will immediately call kp_iBeaconAPI_didFailMonitoringWithError, passing more detail about the error as a parameter.

Stop Monitoring for iBeacons

This function ends monitoring for iBeacons.

Format	kp_iBeaconAPI_startMonitoringWithPath2SchemeFile(filepath);
Parameters	filepath - [string] path to the schema file. If remote, this should be the full URL. If local, this path should be relative to the Kiosk Pro documents folder (rather than relative to the file calling the function).
Triggers	If Kiosk Pro is unable tp find or parse the .xml file, the app will immediately call kp_iBeaconAPI_didFailMonitoringWithError, passing more detail about the error as a parameter.

Notifications via API Callbacks

When Device Enters a Beacon Region
When Device Leaves a Beacon Region
When Monitoring for Beacons Returns an Error

When Device Enters a Beacon Region

This callback is run each time the device enters a new iBeacon region defined in the current schema file.

Format	function(callback);
Return values	UUID - [string] the UUID majorValue - [string] the major value minorValue - [string] the minor value name - [string] the region name

When Device Leaves a Beacon Region

This callback triggers each time the device exits an iBeacon region defined in the current schema file.

Format	kp_iBeaconAPI_didExitBeaconRegion(UUID, majorValue, minorValue, name);
Return values	UUID - [string] the UUID majorValue - [string] the major value minorValue - [string] the minor value name - [string] the region name

When Monitoring for Beacons Returns an Error

This callback triggers when the function to initiate monitoring using kp_iBeaconAPI_startMonitoringWithPath2SchemeFile is unsuccessful.

Format

kp_iBeaconAPI_didFailMonitoringWithError(error);

Return values

error - [array] JavaScript object with the following properties:

error.code - [string] the error code
error.description - [string] a description of the error
error.failureReason - [string] the reason for the error
error.recoverySuggestion - [string] a potential solution for resolving the error
error.debugDescription - [string] a fully detailed description of the error
error.domain - [string] where the error occurred

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

Change Log

Added in version 8.5.