Important: This guide describes the “monolithic” Estimote SDK, from  Estimote/Android-SDK

The proximity detection features in that SDK are now obsoleted in favor of the new Estimote Proximity SDK, available at  Estimote/Android-Proximity-SDK

To learn more about the new API, see the Add Proximity to Android app guide instead.

Part 1: Setting up

Android Beacon Regions API, which is part of the Estimote SDK for Android, is an effort to replicate the concepts of Beacon Regions, Monitoring, and Ranging, on Android.

This tutorial is thus the counter-part to the iBeacon tutorial. We’ll walk you through how to build an almost identical beacon-enabled Android app.

See also: What is iBeacon?

The main theme is that of an airport app.

What’s ahead (aka Table of Contents)

Prerequisites

  • 1 x computer with Android Studio.
  • 1 x device with Android 4.3 or above.
  • 1 x Estimote Account (sign up here).
  • 1 or more Estimote Beacons with iBeacon broadcasting enabled.

Create a beacon project

Start by creating a new Android Studio project. Name it however you want; “Airport” might be a good one. Set “Minimum SDK” to “API 18: Android 4.3 (Jelly Bean)” and choose “Blank Activity” to begin with.

Add Estimote SDK

Open the “build.gradle (Module: app)” Gradle Script and declare Estimote SDK dependency:

dependencies {
    compile fileTree(dir: 'libs', include: ['*.jar'])
    compile 'com.android.support:appcompat-v7:23.0.1'

    // add the following line, and replace "1.0.12" with the latest version
    // of Estimote Android SDK; you'll find the latest version number on:
    //   https://github.com/Estimote/Android-SDK/releases
    compile 'com.estimote:sdk:1.0.12'
}

Android Studio will now show a “Gradle files have changed since last project sync …” warning. Just click “Sync Now” and the Estimote SDK will be automatically added to the project.

Runtime permissions (Android 6.0)

There’s one extra step you need to perform if your app’s targetSdkVersion is 23 (i.e., Android 6.0) or greater—and that’s to request the ACCESS_COARSE_LOCATION permission at runtime. You can read more in Google’s Requesting Permissions at Run Time article, or in the Android 6.0 and runtime permissions section of our own Estimote Android SDK readme.

We can’t automatically request these permissions for you, like we do with the manifest file, but we do provide helper methods to make it really easy. One of these methods is SystemRequirementsChecker’s checkWithDefaultDialogs. It goes through a predefined checklist and makes sure everything is accounted for, including the runtime permissions (and also things like, is Bluetooth on, is Location on, etc.)

Let’s call it in the MainActivity:

@Override
protected void onResume() {
    super.onResume();

    SystemRequirementsChecker.checkWithDefaultDialogs(this);
}

Info: The checkWithDefaultDialogs will use default system dialogs if it needs to ask the user for anything—e.g., to turn Bluetooth or Location on, or … yes, ask for ACCESS_COARSE_LOCATION permission.

This is great for this tutorial, as we want to get up and running quickly—but in a production app, you might want to design your own UI, or even an entire onboarding process, to explain why your app requires location and Bluetooth, and what’s in it for the user.

The check method might be a better option then. It won’t trigger any dialogs, but will simply report anything that’s missing to a callback—leaving how to handle it up to you.

Key takeaways

  • To add Android Estimote SDK to your project, declare it as a dependency in the “build.gradle” file.

  • While Estimote SDK requires the app to request Bluetooth and Internet permissions to function, it’s automatically taken care of. You do not need to declare these by hand.

  • Starting with Android 6.0, you also need to request Location permissions for your app to be able to discover beacons, and these permissions must be requested at runtime. Use one of the SystemRequirementsChecker helper methods to do that easily.

Part 2: Background monitoring