What you will learn

This tutorial will teach you how to create your beacon ranging process to detect nearby beacons around a user.

Prerequisites - What you need to get started

  • Your SDK credentials, including an SDK Login, Password, and Company Key to initialize the SDK.
  • A BLE beacon, which has been configured on your account, in order to test interactions with your app.
  • An Android Device, with Bluetooth 4.0 and Android 4.0 and above, to be able to interact with BLE beacons.
  • The Android Studio application, which you can download from the Android Developers website.

Step 1: Clone the sdk-tutorial repository

  • Clone the sdk-tutorial repository
git clone https://github.com/opsct/sdk-tutorial.git
  • Open the android>beacon>8-beacon-Range>Starter project with Android Studio

Step 2: Configure the SDK

  • Open the ApplicationNotification class
  • Configure the SDK with:
    • the UUID of your beacon
    • the appropriate Adtag Environment (DEMO / PREPROD / PROD / PROD_US)
    • your SDK credentials (your login, password, and company details from Connecthings )
      AdtagInitializer.initInstance(this)
                      .initUrlType(UrlType.DEMO / ... / UrlType.PROD)
                      .initUser("YOUR_USER",  "YOUR_PWD")
                      .initCompany("YOUR_COMPANY_KEY").synchronize();

If you need more informations, have a look to the 5 minutes quickstart tutorial

Step 3: Display nearby beacons

  • Open the MainActiviy class
  • Implement the BeaconRange listener
public class MainActivity extends AppCompatActivity implements BeaconRange {
	[...]
	@Override
    public void didRangeBeacons(List<AppleBeacon> beacons, List<BeaconContent> beaconContents, BeaconContent.INFORMATION_STATUS informationStatus, FEED_STATUS feedStatus) {
	
	}
}
  • Code
   @Override
    public void didRangeBeacons(List<AppleBeacon> beacons, List<BeaconContent> beaconContents, BeaconContent.INFORMATION_STATUS informationStatus, FEED_STATUS feedStatus) {
        tvBeaconNumber.setText(getString(R.string.tv_beacon_number, feedStatus, beacons.size(), beaconContents.size()));
        if(beaconContents.size() > 0 && beaconContents.size() == beacons.size()){
            findViewById(R.id.tv_beacon_next_step).setVisibility(View.VISIBLE);
        }
        //update the beaconList when beaconContents update
        if(previousBeaconContents == null || previousBeaconContents.size() != beaconContents.size() || !beaconContents.containsAll(previousBeaconContents)){
            beaconArrayAdapter.setList(beaconContents);
        }
        previousBeaconContents = beaconContents;
    }

Note 1:

  • List < AppleBeacon > beacons: list of nearby beacons

  • List < BeaconContent > beaconContents: list of contents associated to these nearby beacons in Adtag. The content is cached for 10 minutes

  • BeaconContent.INFORMATION_STATUS informationStatus: allows to verify if all the content has been downloaded from Adtag. Values are:

    • NO_INFORMATION: no content has been downloaded yet from the Adtag Platform / the SDK is starting the download
    • PARTIAL_INFORMATION: content download from Adtag is in progress, and already complete for some of the nearby beacons
    • FULL_INFORMATION: download is complete for the content of all nearby beacons
  • FEED_STATUS feedStatus: allows to know the status of the connection with the Adtag Platform. Values are :

    • IN_PROGRESS: content download from the Adtag Platform is in progress
    • BACKEND_ERROR: download error due to Adtag
    • NO_NETWORK_ERROR: content download cannot be completed because the device does not have access to an internet network (wifi or cellular)
    • BACKEND_SUCCESS: successful content download

Note 2:

If the size of the beacons list and of the beaconContents list is different, and if the informationStatus shows ATRangeInformationStatusComplete, then this means that some beacons do not have associated content in Adtag.

Note 3:

The BeaconRange listener is automatically registered to the AdtagBeaconManager when it is implemented on an Activity object. If you implement the BeaconRange listener on a Fragment object or any other object, you have to:

  • register the BeaconRange listener to the AdtagBeaconManager when the activity resumes, using the following code:
adtagBeaconManager.registerBeaconRangeLister(beaconRange);
  • unregister the BeaconRange listener to the AdtagBeaconManager when the activity goes to pause, using the following code:
adtagBeaconManager.unRegisterBeaconRangeLister(beaconRange);

Step 4: test on your device

  • Check that your Android Device is in Developer Mode
  • Connect your Android Device to your computer
  • Activate your beacon
  • In Android Studio, click on "Play" to launch the installation process on your phone.
  • Once it is running, wait until you see the following text
    "BACKEND_SUCCESS, 1 beacon(s) detected, 1 content(s) attached to the beacon(s) on Adtag downloaded"