Overview

Add indoor location awareness and mapping capabilities to your app through the use of iBeacons and proximity scanning.

This module allows the scanning of nearby Bluetooth Low-Energy beacons that conform to the iBeacon spec. It provides Median JavaScript Bridge commands to retrieve the list of nearby beacons and their identifying information.

An iBeacon continuously broadcasts three identifiers: a UUID, major, and minor. UUID is a long random identifier that should be customized for each implementation. Major and minor are integers between 0 and 65535 that can be used to differentiate each individual beacon. For example, a retailer may have one UUID across all of their iBeacon deployments used for their retail customers, and another UUID used for employees. Each store may have a major identifier, and each individual beacon would have a different minor identifier.

The beacon broadcast data also encodes the emitting signal power. By comparing this to the actual received signal power, devices can estimate their distance from each beacon.

As Bluetooth beacons can be used to identify the user's physical location, this is considered a privacy sensitive function. iOS requires the user to grant location permissions. Android also requires the user to grant permissions starting with Android 10.

Implementation Guide

Once the premium module has been added to your app, you may use the following Median JavaScript Bridge commands to access its functionality.

You must provide a specific UUID to scan for iBeacons on iOS as Apple does not permit iOS devices to scan for all UUIDs.

Define a callback function that will receive the beacon data. For example:

// define this function, but do not call it yourself!
function callback(data) {
  if (data.success) {
    alert('I found ' + data.beacons.length + ' beacons');
  }
}

↔️Median JavaScript Bridge

To initiate a scan, run the following JavaScript function. uuid can be omitted for Android but is required for iOS.

JavaScript

median.beacon.scan({'callback': callback, 'uuid': 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx'});

Within a few seconds of a successful scan, the app will run your callback function with a data object with the fields:

• success: set to true. This does not indicate that any beacons were found, only that the scan did not encounter errors.
• beacons: an array of beacon objects, each containing the fields:
  • format: a string, set to "iBeacon"
  • uuid: a string
  • major: an integer
  • minor: an integer
  • rssi: signal strength in decibels
  • proximity (iOS only): "immediate", "near", "far", or "unknown"
  • accuracy (iOS only): the accuracy of the proximity calculation in meters
  • distance (Android only): the estimated distance of the beacon in meters

For example:

{
  "success": true,
  "beacons": [
{
  "format": "iBeacon",
  "uuid": "9C615AD4-8E6A-53BC-BC27-82171491A2WA",
  "major": 1000,
  "minor": 123,
  "rssi": -52,
  "proximity": "immediate",
  "accuracy": 0.1413
},
{
  "format": "iBeacon",
  "uuid": "9C615AD4-8E6A-53BC-BC27-82171491A2WB",
  "major": 1001,
  "minor": 1321,
  "rssi": -78,
  "proximity": "near",
  "accuracy": 4.5321
}
  ]
}

If the scan fails, the data object will have the fields:

• success: set to false
• error: a string that describes why the scan failed

For example:

{
  "success": false,
  "error": "This device does not support Bluetooth LE"
}

Typical reasons for a scan to fail include the device not having the necessary hardware, Bluetooth being disabled, or the user denying location permissions.