BleSetupHelper

The BleSetupHelper class is a convenience class to effortlessly handle getting the necessary permissions for BLE scans to work on Android 6 and up. This can be quite an annoying experience, and we've chewed this piece of annoyance up for you. Of course, you can always ignore it, and roll your own implementation.

The helper will show dialogs to your user explaining what's needed and being requested. There's even pre formatted text for each dialog, which has multiple languages available.

How many languages does the helper come with?

18. English is the default, which is hardcoded (if you use the jar, this is all you will get without implementing your own), and 17 additional language codes.

The language codes are:

  1. English (en) [default]
  2. Czech (cs)
  3. Danish (da)
  4. German (de)
  5. Spanish (es)
  6. French (fr)
  7. French - Canada (fr-rCA)
  8. Italian (it)
  9. Japanese (ja)
  10. Korean (ko)
  11. Dutch (nl)
  12. Norwegian nn
  13. Polish (pl)
  14. Portuguese - Brazil (pt-rBR)
  15. Russian (ru)
  16. Swedish (sv)
  17. Chinese (China) zh-rCN
  18. Chinese (Taiwan) zh-rTW

What exactly is needed to successfully run a BLE scan on Android Marshmallow (6.0) and higher?

  1. Bluetooth must be on
  2. Location services permission
    a. You must declare android.permission.ACCESS_COARSE_LOCATION in your manifest file _(for Android Q and beyond, you will have to use android.permission.ACCESS_FINE_LOCATION)_
    b. You must request user permission at runtime
  3. Location services must be on

The helper will turn the bluetooth radio on, if it is not already. Next, it will request location permission, if they have not been granted. Then it will turn on location services, if they are not on. Finally, any custom permissions are handled.

Simple Example Usage

BleManagerConfig config = new BleManagerConfig();  
BleManager manager = BleManager.get(this, config);  
BleSetupHelper.runEnabler(manager, this, result ->  
{  
    if (result.getSuccessful())  
    {  
        // Do whatever you want to do with Bluetooth now.  
        scanThenConnectThenRead(manager);  
    }  
    else  
    {  
        // You may want to show something to the user here to explain  
        // that bluetooth scanning will not work without all the requested  
        // permissions and services are turned on  
    }  
});  

Can I use the helper class to handle my own custom permissions?

Yes! The helper was built with the idea that if you wanted to roll extra permissions into the flow, it would be easy to do.

Custom permission example


@Override
protected void onCreate(Bundle savedInstanceState)
{
    ...
    BleManagerConfig config = new BleManagerConfig();
    BleManager mgr = BleManager.get(this, config);
    BleSetupHelper helper = new BleSetupHelper(mgr, this, result ->
    {
        if (result.getSuccessful())
            // TODO BLE is fully enabled, and all permissions including custom are granted
    });
    helper.addRequiredPermissions();
    helper.addCustomPermission("My custom permission");
    helper.setImpl(new MyPermissionHelper());
    helper.start();
}


private static class MyPermissionHelper extends BleSetupHelper.BluetoothEnablerImpl  
{  
  boolean m_permissionGranted = false;  

  @Override  
  public void requestCustomPermission(Object metadata)  
  {   // TODO - Implement code to actually request the permission
      m_permissionGranted = true;  
  }  

  @Override  
  public boolean checkIsCustomPermissionEnabled(Object metadata)  
  {   // TODO - Actually check if the permission has been granted  
      return m_permissionGranted;  
  }  

  @Override  
  public boolean checkIsCustomPermissionRequired(Object metadata)  
  {   // We're just going to say that this permission is always required  
      return true;  
  }  
}