Overview

What is libbeacon?

libbeacon is a library to listen for an expected fleet of beacons, as a background service, and act upon entering/exiting their broadcast area.

What does it support?

Standard protocols

The frame processing supports the de facto industrial standards:.

  • iBeacon
  • Eddystone

Specific protocols

Other frame formats and/or data specific to manufacturers can be supported through the addition of plugins. For example, it's usual for manufacturers to provide an indicator for the battery level, but sometimes in a non standard way.

The library is provided with a basic set of plugins for the tags of these manufacturers:

  • Invirtus
  • ELA Innovation
  • Accent System (board of the Plus and Standard models of Blue Net Beacon)
  • Minew Technologies Co.

The integration of more plugins can be considered, on request.

How does it look like?

libbeacon is packaged as an aar file and needs an API Key (free for evaluation).

Integration Guidelines

Step 1: Get the library file

Go to the Download section and choose preferably the latest .aar file.

Place the file under the libs/ directory of the application of your project.

Step 2: Get an API Key

Go to the License section and request a Key.

Copy-paste this Key in your AndroidManifest.xml file as the YOUR_API_KEY below:

<manifest ... >
  <application ... >
    <activity ... > </activity>
    <meta-data android:name="fr.maxcom.libbeacon.apiKey" android:value="YOUR_API_KEY" />
  </application>
</manifest>

Step 3: Set the possible necessary permissions and features

Note: Required for its internal implementation, the library already declares these permissions in its AndroidManifest.xml, so they will be merged in the final app packaging:

"android.permission.BLUETOOTH_CONNECT"
"android.permission.BLUETOOTH_SCAN"

♦ If you want your application to run on older devices, lower or equal to Android 11 (R - API level 30) some legacy permissions are needed.

Set these permissions in the AndroidManifest.xml file:

<manifest ... >
  <!-- https://developer.android.com/develop/connectivity/bluetooth/bt-permissions -->
  <!-- "Request legacy Bluetooth permissions on older devices." -->
  <uses-permission android:name="android.permission.BLUETOOTH" android:maxSdkVersion="30" />
  <uses-permission android:name="android.permission.BLUETOOTH_ADMIN" android:maxSdkVersion="30" />
</manifest>

♦ On Android 11 or lower, ACCESS_FINE_LOCATION is necessary for a Bluetooth scan. On Android 12 or higher, the option of an assertion about "never derives physical location" can not be used because it is too much restrictive as it filters Eddystone and iBeacon payloads.

♦ On Android 12 (API level 31) or higher, if you need access to FINE location, you must request both ACCESS_FINE_LOCATION and ACCESS_COARSE_LOCATION.

Set these permissions in the AndroidManifest.xml file:

<manifest ... >
  <!-- https://developer.android.com/develop/connectivity/bluetooth/bt-permissions -->
  <!-- "Needed only if your app uses Bluetooth scan results to derive physical location." -->
  <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
  <!-- https://developer.android.com/develop/sensors-and-location/location/permissions#approximate-request -->
  <!-- "On Android 12 (API level 31) or higher, users can request that your app retrieve only approximate ..." -->
  <uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
</manifest>

♦ Optionally you may declare a required feature, intended to the Play Store filtering:

<manifest ... >
  <uses-feature android:name="android.hardware.bluetooth_le" android:required="true" />
</manifest>

Step 4: Allow the use of the library

Before any call to the library can be made, the application code must make an initial call to Licensing.allow(Context). Typically this takes place in the onCreate() method of the activity declared as the application entry point:

override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)

    Licensing.allow(applicationContext)
    //...
}

protected void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);

    Licensing.allow(getApplicationContext());
    //...
}