What you will learn

This tutorial will teach you how to manage bluetooth permission with the mobile SDK.

Pre-requisites - What you need to get started

  • A Nexus Account: the SDK is available through a private Nexus. You must have received an email with your user account, including a link to create a password
  • Your SDK user information: in order to initialize the Mobile SDK, you must have received a User Name, a Password and a Company
  • A BLE beacon: a BLE beacon configured on your account is mandatory to test the application
  • An Android Device: you need a compatible Bluetooth Low Energy Android device that is able to detect beacons
  • The Android Studio application: you must have downloaded Android Studio from the Android Developpers’ website
  • You must have completed the location permission tutorial

About bluetooth permission

Our mobile SDK uses bluetooth scanning to detect nearby beacons, and has the ability to automatically enable bluetooth on smartphones. However, bluetooth is a critical function of smart devices, and has direct impact on battery consumption. As such, at Connecthings, we strongly recommend that you explicitly ask users for permission to use bluetooth when they first launch the app, especially if you plan on leveraging Android's capability to automatically activate bluetooth at later times, or when the beacon services restart. For instance, you can implement an alert to ask the user for permission to use bluetooth.

The saveBleAccessAuthorize method, in the AdtagBeaconManager class, indicates whether or not the user has authorized bluetooth. If it returns 'true', then the SDK is able to launch the scanning process to detect nearby beacons.

adtagBeaconManager.saveBleAccessAuthorize(true); 

If it returns 'false', the scanning process cannot start.

Once the SDK has launched the scanning process, your application needs to be able to activate the phone's bluetooth.

When your application is open / in the foreground, this has to be done explicitly using the AdtagBeaconManager.enableBluetooth() function, which directly activates the bluetooth function.

When your application is running in the background, the SDK periodically tests the phone's bluetooth status, and can re-enable it if necessary, depending on the value chosen for the following AdtagBeaconManager.setEnableBluetoothWhenAppInBackground(BLUETOOTH_BACKGROUND_ACTIVATION_STATUS) function.

There are various BLUETOOTH_BACKGROUND_ACTIVATION_STATUS values:

  • ENABLE: the SDK automatically enables bluetooth when the application is running in the background if it has permission to access the bluetooth function. This is the default configuration.
  • DISABLE: when the SDK detects that bluetooth has been disabled, it leaves it deactivated.
  • ASK_PERMISSION: the first time the SDK detects that bluetooth is disabled while the application is running in the background, it generates a notification asking for permission to re-enable it.

To sum up, you are free to choose which configuration to implement with regards to Bluetooth permission:

  • Either implicit bluetooth permission, by setting bluetooth permission to "true" in the Application class, and adding the adtagBeaconManager.saveBleAccessAuthorize(true); line to the Application class (as seen in the 'Location Permission Tutorial')
  • Or explicit bluetooth permission, as described in this tutorial

There are no specific Android OS requirements, but Connecthings' recommendation is to opt for the latter.

Requesting bluetooth permission

Step 1: clone the sdk-tutorial repository

  • Clone the beacon-tutorial repository
git clone https://github.com/Connecthings/sdk-tutorial.git
  • Open the android>beacon>12-permissions-bluetooth>Starter project with Android Studio

Note:

This tutorial is a direct continuation of the location permission tutorial. This tutorial continues to enrich the location permission tutorial application, to achieve full permission management.

Step 2: Configure the SDK

  1. Open the 'ApplicationPermission' class
  2. Configure the SDK with:
  • the UUID of your beacon
  • the appropriate Adtag Environment
  • your login, password, and company details you received from Connecthings

Step 3: Test if bluetooth permission has been granted

  • The AdtagBeaconManager class enables you to use two methods to test bluetooth permission:

    • AdtagBeaconManager.isBleAccessAuthorize(): returns "true" if bluetooth permission has been granted
    • AdtagBeaconManager.isBleAccessAsk(): allows to enquire whether bluetooth permission has been asked before
  • Create a testBluetoothPermission method in the MainActivity class:

private void testBluetoothPermission(){

}
  • Test if bluetooth permission has been granted
private void testBluetoothPermission(){
  if(adtagBeaconManager.isBleAccessAuthorize()) {

  }else{

  }
}
  • Test if bluetooth permission has been asked before
private void testBluetoothPermission(){
  if(adtagBeaconManager.isBleAccessAuthorize()) {

  }else{
    if(adtagBeaconManager.isBleAccessAsk()){

    }else{
    
    }
  }
}
  • Let's implement the following behavior in this tutorial:
  • open a dialog if it is the first time that permission is asked using the BleDialog class
  • display a message in the MainActivity if the user has previously denied bluetooth permission.
private void testBluetoothPermission(){
  if(adtagBeaconManager.isBleAccessAuthorize()) {
    switchToBeaconTv();
  }else{
    //BLE access has been asked before -> display a simple text in the Activity
    if(adtagBeaconManager.isBleAccessAsk()){
      showBluetoothTv();
      hideLocationTv();
    }else{
      //BLE access has never been asked -> show a dialog
      BleDialog.newInstance().show(getFragmentManager(), BleDialog.TAG);
    }
  }
}

Step 4: Replace the call of the testToGrantBluetoothAccess method

Until now, the application gave implicit bluetooth permission when calling the testToGrantBluetoothAccess method, in the MainActivity class. Let's now change the application's behavior to explicitly ask the user for bluetooth access permission.

  • In the testLocationPermission method:
    • Replace the call of the testToGrantBluetoothAccess method with the call of the testBluetoothPermission method
    • Remove the call of the switchToBeaconTv(); method, which launches the display of the bluetooth scan result (irrelevant for now).

Now the application explicitly asks the user for bluetooth permission.

Step 5: Manage dialog interactions

  • Open the BleDialog class
  • In the onClick method:
    • When the user accepts bluetooth permission, notify the mobile SDK and launch the ranging process
      • Call the testToGrantBluetoothAccess method from the MainActivity class to realize it.
    • When a user rejects bluetooth permission, show a less intrusive text in the MainActivity to remind him/her that bluetooth permission is necessary for the application to function correctly
      • Call the showBluetoothTv method from the MainActivity class to realize it.
@Override
public void onClick(DialogInterface dialog, int which) {
  AdtagBeaconManager manager = AdtagBeaconManager.getInstance();
  if(which == Dialog.BUTTON_NEGATIVE){
    manager.saveBleAccessAuthorize(false);
    ((MainActivity) getActivity()).showBluetoothTv();
    dismiss();
  }else if(which == Dialog.BUTTON_POSITIVE){
    ((MainActivity) getActivity()).testToGrantBluetoothAccess();
    dismiss();
  }
}

Step 6: Learn from the testToGrantBluetoothAccess method code

  • Open the MainActivity class
  • Find the testToGrantBluetoothAccess method
  • This method uses:
    • adtagBeaconManager.saveBleAccessAuthorize(true) to allow the SDK to access the bluetooth function
    • adtagBeaconManager.startRanging(RangeConsumer) to launch the ranging process

Note:

The beacon ranging process automatically starts once the SDK has been granted bluetooth permission, and if an activity implements the BeaconRange interface.

Step 7: Configure the BLUETOOTH_BACKGROUND_ACTIVATION_STATUS

Let's configure the application to ask permission to enable bluetooth when the application is running in the background.

  • In the ApplicationPermission class, at the end of the onCreate method, add:
beaconManager.setEnableBluetoothWhenAppInBackground(BluetoothManager.BLUETOOTH_BACKGROUND_ACTIVATION_STATUS.ASK_PERMISSION);

Note :

In this case, the SDK will generate a notification the first time that it detects that the application is in the background, and that bluetooth has been disabled. You can customize the strings and the drawables of the notification.

In a strings.xml file, use the following key to customize the strings associated with the notification:

  • notification_ble_bg_title: title of the notification
  • notification_ble_bg_desc: description field for the notification
  • notification_ble_btn_grant: label of the button to grant permission
  • notification_ble_btn_refuse: label of the button to refuse permission

In your drawable folders, you can add the following file to customize the drawables associated with the notification:

  • icon_notification_ble_ask_permission: icon associated with the notification
  • btn_notification_ble_grant: icon of the button to grant permission
  • btn_notification_ble_refuse: icon of the button to refuse permission

Step 8: Test the foreground permission process

  • Uninstall the previous version of the location tutorial application from your Android Device, in order to see the permissions dialog again

  • Connect an Android Device to your computer

  • Note: if your device has an older version than Android 6.0, you will only see the bluetooth permission dialog.

  • Activate your beacon

  • In Android Studio, click on "Play" to launch the installation process on your phone.

  • When the application starts, a location permission dialog appears.

  • If you agree to grant access to your location, a new dialog will appear for bluetooth permission. Do not hesitate to test all of the possible options regarding bluetooth permission, even rejection.

  • When both permissions are granted, the following message appears:

"BACKEND_SUCCESS, 1 beacon(s) detected, 1 content(s) attached to the beacon(s) on Adtag downloaded"

Step 9: Test the background permission process

  • Put the application in the background
  • Disable bluetooth
  • Kill and reopen the application
  • The notification asking for bluetooth permission appears after few seconds
    • Note: you need to clear your application's data in the android application settings if you want to display the notification another time
  • Click on Grant to enable bluetooth, otherwise it will remain disabled.