Beacons in Android

improve this page | report issue


This tutorial discusses the client-side API for working with beacons in Android.
This is a continuation of Working with Beacons (introduction, setup, and server side API).

The following topics are covered:

Configuring your application

  1. Download the Android Beacon Library v2.1.3 and above from this page:
  2. Import the Android Beacon Library into Eclipse.
  3. Right-click the Android application project and select Properties -> Android -> Library -> Add.
  4. Select android-beacon-library and click Apply -> OK.
  5. Add the following entry to the file.
  6. Copy the source files under /src/com/worklight/wlclient/api into the src folder of the Android application (by preserving the package directories).

    These source files use JSONStore to store beacons, triggers, and associations locally.

  7. Add the libraries to enable JSONStore for your native Android application.

For more information, see the topic about copying files of native API applications for Android, in the user documentation.

Android Manifest configuration

  • Specify minSdkVersion as 18 (Android 4.3).

  • Specify permissions for BLUETOOTH and BLUETOOTH_ADMIN.
    <uses-permission android:name="android.permission.BLUETOOTH" />
    <uses-permission android:name="android.permission.BLUETOOTH_ADMIN" />

  • This is in addition to the following standard Worklight permissions:

    <uses-permission android:name="android.permission.INTERNET" />
    <uses-permission android:name="android.permission.ACCESS_WIFI_STATE" />
    <uses-permission android:name="android.permission.GET_TASKS" />

  • Specify com.worklight.wlclient.api.WLBeaconsMonitoringApplication as the application name.

Enable the library to show alerts

protected void onCreate(Bundle savedInstanceState) {
    ((WLBeaconsMonitoringApplication) this.getApplication()).setAlertHandler(new WLAlertHandler(this));

Simplified APIs for monitoring/ranging beacons

Loading beacons and triggers from the server

To load information pertaining to beacons, triggers, and their associations from the server and storing it in the application JSONStore, write the following code:

String adapterName = "BeaconsAdapter";
String procedureName = "getBeaconsAndTriggers";

WLBeaconsAndTriggersJSONStoreManager.getInstance(context).loadBeaconsAndTriggers(adapterName, procedureName, new WLResponseListener() {
    public void onSuccess(WLResponse arg0) {
        // Successfully fetched beacons, triggers and associations from server and saved in JSONStore.
    public void onFailure(WLFailResponse response) {
        // Failed to fetch beacons, triggers and associations from server
        String responseText = "WLBeaconsAndTriggersJSONStoreManager.loadBeaconsAndTriggers() failed:\n" + response.getResponseText();
        Log.d(TAG, responseText);

Triggering action

To start the monitoring/ranging of Beacons and to fire trigger actions, write the following code:

((WLBeaconsMonitoringApplication) this.getApplication()).startMonitoring();

To let the user opt out of Beacon monitoring, write the following code:

((WLBeaconsMonitoringApplication) this.getApplication()).stopMonitoring();

Running the sample application

Download the MobileFirst project and the native project.

The sample contains two projects:

  • The file contains a MobileFirst native API that you can deploy to your MobileFirst Server instance.
  • The file contains a native library that provides a simplified set of APIs for ranging/monitoring beacons and a native Android application that demonstrates the usage of those APIs.

Make sure to update the file in AndroidNativeBeacons with the relevant server settings.

The sample showcases a simple banking scenario where actions are triggered based on proximity:

  • When the user enters a Bank branch, a notification action is triggered with a Welcome message.
  • When the user stays in the Bank branch, an alert is triggered with a message stating that a bank personnel will assist the user soon.
  • When the user exits the Bank branch, a notification action is triggered with a message.

What kinds of beacons can be detected?

By default, the Android Beacon Library will only find beacons, meeting the open AltBeacon standard.

The library can be configured to work with different types of beacons. The byte layout of the beacon's advertisement must be specified in WLBeaconsMonitoringApplication class in
com/worklight/wlclient/api package.

For details refer -

Detecting Beacons After application is killed

Application can be configured to detect Beacons even after being killed.

For details refer -



Inclusive terminology note: The Mobile First Platform team is making changes to support the IBM® initiative to replace racially biased and other discriminatory language in our code and content with more inclusive language. While IBM values the use of inclusive language, terms that are outside of IBM's direct influence are sometimes required for the sake of maintaining user understanding. As other industry leaders join IBM in embracing the use of inclusive language, IBM will continue to update the documentation to reflect those changes.
Last modified on November 09, 2016