Frequently Asked Technical Questions

Mobile

A minimum, functional data set requires Zones, Fences (or Beacons) and Actions to be created. These are sent to the device as part of a data collection once the device is authenticated, hence an absence of these rules causes no data response.

Once an Action is triggered for a Zone, it is suppressed until the Minimum Re-trigger Time (MRT) that has been configured for the Zone has expired. The MRT is to prohibit continuous triggering while the device remains within a Fence.

In order to trigger an Action, it is necessary to be within a configured Fence, fulfilling any conditions associated with the action. If an action was triggered earlier, it won’t re-trigger until you check out of the Fence (if check-out has been enabled for the Zone that the Fence resides in) and the minimum re-trigger time (MRT) has expired.

There are no Zone triggering limitations on an app using the Bluedot SDK while it is running in the background on either Android or iOS.

In Android, actions triggered in the background have the same response as running in the foreground.

In iOS, the message and URL actions are posted as local notifications when they are triggered while your app is in the background.

On selecting the local notification for a URL, your app will be returned to the foreground and the user will be redirected to the configured URL in the device’s default browser.

On selecting the local notification for a message, your app will be returned to the foreground.

All of the provided actions that can be configured for a Zone are executed immediately upon the triggering of a Fence or Beacon. Should your app require additional functionality, like queuing message notifications while the app is in the background, the callback from a Custom Action can be utilized. These are methods that are called from the Bluedot SDK to your app with information such as the name of the Zone and the Fence, exact location the device triggered the action, a unique install reference for the app install. For a full list of fields, please consult our documentation here: iOS Features – Fence triggering and here: Android Features – Fence triggering.

It is not recommended to send complex JSON data within a Message Action; it is recommended to use a Custom Action to provide your app with the trigger information and perform any post processing thereafter.

The Bluedot SDK will not work if the user turns off Location Services on the device. Should the Location Services for a device not be available, your application will receive a callback requesting user intervention to resolve the issue.

The Bluedot SDK requires internet connectivity for authentication and to download the Zone configuration rules. Once the SDK has passed these steps, internet connection is not required except to trigger check-ins and check-outs. Internet connectivity is needed to report the check-ins and check-outs to the back-end and download the Zones after the Rule Download Interval set for your app has expired. In the absence of connectivity, all notifications will be persisted until connectivity is achieved.

Yes, if a Zone has been configured for check-out, then the time spent by the device within a Fence or within the range of a Beacon will be reported by the SDK. This action will also be returned as a callback to the app if a custom action has been added to the Zone.

A message or URL action generated by our SDK does not allow you to pass any additional metadata; these are utilized only for simple strings. A Custom Action will make a callback to your app upon triggering a Fence or Beacon, thereby allowing you to perform any additional processing required within your app, using the information from a trigger.

Please refer to the developer documentation on how to configure a Zone with a Custom Action to match your user scenario here: Point Access – Setting actions.

iOS

The Bluedot Point SDK can be configured to restart after being removed from the system tray. Once the app restart functionality has been implemented in your app, the user will be prompted with a local notification after the device has moved a significant distance (determined by iOS) to restart the app running the Bluedot Point SDK. Please refer to App Restart documentation for more information.

The Bluedot Point SDK has been designed and engineered to make use of all available sensors. A GPS sensor is the only hardware requirement for an iOS device; if the iPad model supports GPS then the Bluedot Point SDK will work on it. For authentication, a Wi-Fi or Cellular Internet connection is required.

As of version 1.6, the Bluedot Point SDK requires iOS 10.0 or above.

Yes, the Bluedot Point SDK can range for Beacons at a specific distance while your app is in the background.

Yes, The Bluedot Point SDK for iOS can be used in Swift projects as of v1.4.

In order to use our SDK, the minimum required XCode version is 7.1.

We have an example Swift Integration with Point SDK available from our GitHub page (PointSDK-MinimalIntegrationExample-iOS). As the Swift language is still an emerging standard, this should be considered Beta and subject to continual change.

Please get in touch with us if you require any assistance.

Android

A network error can be related to either one of the following cases:

Network outage on the device, where there is no Wi-Fi or data connection.

Security Providers are not up to date, which may happen on Android devices below 5.0. For this scenario, go through the Security Provider update process described at https://developer.android.com/training/articles/security-gms-provider.html.The solution is quite simple; an app invokes ProviderInstaller.installIfNeeded(getApplicationContext());right beforemServiceManager.sendAuthenticationRequest(…)

The Bluedot Point SDK will continue to receive notifications while running in the background. In order to resurrect the Bluedot Point SDK after the app is killed, you need to authenticate the SDK with the restartMode parameter set to true.

If the application is stopped by the user with the “Force Stop” option via Application Management then the Bluedot Point Service will not be restarted.

Any Android tablet devices which are GPS enabled are supported by the Bluedot Point SDK.

The minimum Android OS version supported by the Bluedot Point SDK is Android 4.0 Ice Cream Sandwich (API 14) and above.

The hardware required is the Bluetooth V4.0 Low Energy (BLE).

The OS version required is 4.3 Jellybean (API 18) and above.

Point Access Web Interface

The package name field is a unique identifier for an application; we suggest that you use the same name that you use for the application that you are going to publish to the app store. This field can only be set once on creation and cannot be edited later. The format requires at least 3 periods, for example com.bluedotinnovation.campusapp.

This is the minimum period of time the Bluedot Point SDK waits before downloading the new set of Zones, Fences, Beacons, Actions and Conditions; collectively known as the rule set. It is recommended to use the longest suitable time period depending on your data update frequency as a longer interval will save battery power. The default allocated time is 1 hour and the maximum time is 48 hours.

A zone contains one or more Fences (Geofences, Geolines™) and/or Beacons that all relate to a set of actions and conditions. Upon triggering any of the Fences or Beacons within a Zone:

a check-in notification is sent to the back-end

the Zone Actions are performed

the Fences and Beacons within the Zone are disabled for the minimum re-trigger time (MRT)

A Fence is a virtual perimeter for a real-world geographic area. It can be either an encapsulated two-dimensional geographical area (Geofence) or a series of connected lines (Geoline™).

Geofences can be defined as any of the following shapes:

Circle: One geographic coordinate representing the center of a circle, plus the radius in meters

Rectangle: Two distinct geographic coordinates representing the north-east and south-west corners of a rectangle

Polygon: Three or more geographic coordinates representing the vertices of an enclosed polygonal shape

A GEOLINE™️ is a thin, virtual tripwire spanning two or more geographical points.

An Action is executed when a given Zone responds to a device that triggers (checks into) a Fence or Beacon. Actions are not applicable to checking out of a Fence or Beacon.

The following pre-set actions can be utilized to trigger when a device triggers a check-in:

Message – send a local notification on the device.

URL – open a web page in the default browser on a device.

Custom – deliver a callback to the mobile app to allow any custom actions to be executed on the device.

Minimum re-trigger time (MRT) is the amount of time that needs to expire before the Zone allows a re-trigger of the Actions on a device. If checkout is not enabled for a Zone, the MRT starts immediately after a user checks into a Fence or Beacon. For example, if you enter 10:00 as the MRT for a Zone, actions will only re-trigger when the user checks into the same Zone after 10 hours.

If check-out is enabled, the MRT activates only after a device has checked out of the Fence or Beacon it checked into. During the time period that MRT is applied, no other action that has been created for the Zone will trigger; the Zone is effectively disabled. We recommend setting the MRT to as high a value as possible to avoid spamming the device with notifications and save on battery power.

There are no limitations on the number of Zones, Fences or Actions to be created for an App.

The Bluedot Point SDK supports the triggering of actions by entering a Geofence (a pre-defined geographical area), crossing a Geoline™ or coming into the configured proximity of a Beacon. When a Geofence, Geoline™ or Beacon is triggered:

a Check-In Notification is generated and sent to the Point Access back-end

the Actions pertaining to the Zone containing the Geofence, Geoline™ or Beacon are executed

the Zone is then disabled for the duration of its configurable MRT.

The Bluedot Point SDK can optionally track when a device leaves a Fence or Beacon proximity. This is known as ‘checking out’.

The check-out feature also allows your app to be notified, in real-time, when a device ‘checks out’ of a Fence or Beacon that it has previously been checked into.

For fences, check-out occurs as soon as the SDK confidently determines that the device is outside of a checked in fence area; the exact distance of travel is dependent on environmental conditions and the opportunity for battery conservation.

For beacons, checking out occurs when the device leaves the beacon’s full range and it is no longer detectable. The exact range for check out from a beacon is highly dependent on the beacon’s own hardware and configuration. This is irrespective of the proximity that may have been chosen for checking in.

GEOLINE™ components and check out

Having no area, GEOLINE™ components cannot be utilized for checking out.

This has more of an impact should a Percentage Crossed condition be applied to a Zone containing both Geofences and GEOLINE™, as the device will provide a check-out after the percentage is crossed by checking into a Fence but will not provide a check-out if the device finally checked into a GEOLINE™.

In summary, it is possible but not good practice to include GEOLINE™ components in a Zone that is to be utilized for checking out.

Bluetooth Beacons are devices that broadcast signals that can be detected by smart devices nearby. Paired with an app, Apple Wallet Pass or Physical Web browsers, businesses are able to deliver contextually relevant content and information to users at very specific locations.

The Bluedot Point SDK currently supports any Beacon using the iBeacon standard on iOS and uses a Beacon’s Proximity UUID, Major and Minor configuration settings to trigger on iOS devices. On Android, a Beacon is configured using its MAC address and TxPower. Support for other standards is in progress.

The following configuration details are required by the Bluedot Point SDK to trigger Beacons:

Android configuration for Beacons

Tx Power
Transmit power is a configuration setting common to all Bluetooth Beacons. This may be represented in the documentation or determined by the configuration tool supplied by the Beacon manufacturer. Specifying Tx Power allows Android devices to range for Beacons at a specifically configured proximity.

MAC Address
A unique identifier assigned to network interfaces for identification on a physical network. An example of a MAC address is “00-15-E9-2B-99-3C”. This identifier allows an Android device to identify a Beacon.

iOS configuration for Beacons

Proximity UUID
Every Beacon conforming to the iBeacon standard has an identifier known as the Proximity UUID. An example of a Proximity UUID is “de305d54-75b4-431b-adb2-eb6b9e546014”. Given that iOS currently has a restriction of approximately 20 Proximity UUIDs, multiple Beacons can be logically grouped by having the same Proximity UUID and differentiated using the Major and Minor values.

Major and Minor
Used to identify individual beacons within a Proximity UUID group. Minor and Major are integer values between 1 and 65535.

Most of the configuration details would be available from the Beacon manufacturer as part of the Beacon configuration on purchase. We recommend the following apps to detect and acquire Beacon configuration details:

To collect the MAC address and TxPower required for detecting and triggering Beacons on Android devices, you will have to use the apps on devices running the Android operating system. These details are not provided by any apps running on Apple devices.

The latitude and longitude geographical coordinates provided while creating a Beacon in the Bluedot Point Access web interface should be close to the real-world location of the Beacons. A variance of 10 – 20 meters in the actual physical location of the beacon and the location input in the web interface will not make a significant difference, but a greater variance in location could lead to the Beacon not being consistently detected by the SDK.

If the configuration of the Beacons are updated using their proprietary apps then these details have to be updated in the Bluedot Point Access through our web interface or Public APIs. If they are not updated then the Bluedot Point SDK will not be able to detect the Beacons.

Beacon proximity is the configured distance at which a Beacon will trigger an action. There are three standard proximities at which a Beacon can trigger:

Immediate – The Beacon has to be almost touching or within an inch of a device for the trigger to occur.

Near – The Beacon can be up to approximately 6 feet away from a device for the trigger to occur.

Far – The Beacon is farther than 6 feet away but still within receiving distance of the maximum range of the signal for the trigger to occur.

Bluetooth is a network protocol for communicating with nearby devices; the Global Positioning System (GPS) is the encompassing term for geosynchronous satellites in the Earth’s orbit that are triangulated to provide a location with an accuracy of ~5 meters.

It is mandatory to have at least one Action within a Zone. Any Zone without any Action declared, will not be added to data collection which is received after successful authentication.

Public API

Yes, we have detailed documentation of the Public API available here. We include code samples within our documentation for every command in Java, .Net C# and Node.js and also provide the source code on GitHub.

Yes, you can create a Geofences, Geolines™ and Beacons from within your app utilizing your Customer Api Key, Bluedot App Api Key and Zone Id. Sample code for the Public API is available here in different languages.

Miscellaneous

Yes, you can use a single set of Bluedot application credentials for multiple projects. For easier data analysis, we recommend that you create a new Bluedot application for each project.

The Bluedot Point SDK has been designed and developed to ensure that the battery power consumption is negligible through the use of various sensors within a mobile device as well as highly innovative and patented Intellectual Properties. The SDK manages the battery power use efficiently even in most intense customer scenarios where the app user is checking into a multiple locations throughout the day.

Currently, the Bluedot Point SDK is available for iOS and Android platforms.

There are no significant impacts on the battery life on the type of geofence (circle, bounding box or polygon) or GEOLINE™ created. The different configuration settings used together and our proprietary IP helps reduce battery drain.

There are a few things we suggest to improve battery life when it comes to Application and Zone setup.

When creating a Zone, a configuration for re-trigger of this Zone can be set. This field is called minimum re-trigger time (MRT). This is the time the SDK will disable the Zone for, once the Actions assigned to it are triggered. This also prevents the application from spamming the customer device with notifications.

You can also set the Zone to be active for a certain time during the day, for example business hours of 8 AM – 7 PM. The Zone will only be tracked for triggering during this time period.

When creating an app you can increase the Rule Download Interval time. Rule download Interval is the time period the SDK waits to ask for fresh updates on the Zones, Fences and Actions setup. This also plays a part in reducing battery drain.

Cross-Platform Support

Yes, the Bluedot Point SDK is available as a Cordova plugin through the npm repository. If your cross-platform mobile development framework is built on Cordova (or PhoneGap) you can use our Bluedot Point SDK directly out of the npm repository.

A Cordova-based example project is available to demonstrate how to use the functionality of the Bluedot Point SDK that can be downloaded from GitHub.