What you will learn

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

Prerequisites - What you need to get started

About location permission

Android 6 introduces a new set of permissions for specific features, which must be explicitly granted by the user upon first launch. This is the case when an application wants to access the location of a user.
The Bluetooth scanning process has been associated with the location feature, including GPS and Wi-Fi network triangulation.

If your application targets Android 6 devices or above, and does not ask for location authorization, the bluetooth scanning process cannot start.

If your application does not target Android 6 devices or above, you do not need to implement this feature, but the bluetooth scanning process won't return result when the application is in background on Android 6 devices or above.

Requesting location permission

Find out more about location permission in the official Android permission tutorial.

Reminder:

It is necessary to have an Android device with Android 6 or above to complete this tutorial.

Step 1: clone the sdk-tutorial repository

git clone https://github.com/Connecthings/sdk-tutorial.git

Step 2: Configure the SDK

      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: Request permission

Note:

private void requestLocationPermission() {
}
private void requestLocationPermission() {
  if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.M) {
  }
}
private void requestLocationPermission() {
  if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.M) {
    //this method shows the permission dialog.
    //Note that the permission dialog will not be displayed if the user denies permission definitively
    requestPermissions(new String[]{Manifest.permission.ACCESS_COARSE_LOCATION}, PERMISSION_REQUEST_COARSE_LOCATION);
  }
}

Step 4: Retrieve the user's choice

Starting with Android 6, the Android Activity class provides the onRequestPermissionsResult method in order for an application to be notified about the user's choice from the permission dialog.

@Override
public void onRequestPermissionsResult(int requestCode, String permissions[], int[] grantResults) {
}
@Override
public void onRequestPermissionsResult(int requestCode, String permissions[], int[] grantResults) {
  if(requestCode == PERMISSION_REQUEST_COARSE_LOCATION){
  
  }
}
@Override
public void onRequestPermissionsResult(int requestCode, String permissions[], int[] grantResults) {
  if(requestCode == PERMISSION_REQUEST_COARSE_LOCATION){
    if (grantResults.length > 0){
      boolean isGranted = grantResults[0] == PackageManager.PERMISSION_GRANTED;
      if (isGranted) {
        
      }else{
        // permission was denied -> ask for it again
        
      }
    }else{
      // no result ? ask again for permission
    
    }
  }
}
@Override
public void onRequestPermissionsResult(int requestCode, String permissions[], int[] grantResults) {
  if(requestCode == PERMISSION_REQUEST_COARSE_LOCATION){
    if (grantResults.length > 0){
      boolean isGranted = grantResults[0] == PackageManager.PERMISSION_GRANTED;
      if (isGranted) {
        switchToBeaconTv();
        testToGrantBluetoothAccess();
      }else{
        // permission was denied -> ask for it again
        requestLocationPermission();
      }
    }else{
      // no result ? ask again for permission
      requestLocationPermission();
    }
  }
}

Step 5: Test if location permission has been granted

private void testLocationPermission(){

}
private void testLocationPermission(){
        if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.M ) {
            boolean isGranted = checkSelfPermission(Manifest.permission.ACCESS_COARSE_LOCATION) == PackageManager.PERMISSION_GRANTED;
            if (isGranted) {
                //launch the scan
                switchToBeaconTv();
                testToGrantBluetoothAccess();
            }else{
                //request permission
                requestLocationPermission();
            }
        }
    }
protected void onResume(){
  super.onResume();
  [...]
  testLocationPermission();
}

Step 6: Request permission depending on the user's previous action

private void onRequestLocationPermission(){

}
private void onRequestLocationPermission(){
  if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.M ) {
    if(shouldShowRequestPermissionRationale(Manifest.permission.ACCESS_COARSE_LOCATION)){
      //permission has been asked before and the user refused it
      showLocationTv(R.string.tv_error_location_permission);
    }else{
      //permission has never been asked or has been asked and the user refused it definitively...
      requestLocationPermission();
      //show a message if never the user has denied it definitively
      locationPermissionIsDefinitivelyDenied = true;
      showLocationTv(R.string.tv_error_location_permission_definitive);
    }
  }
}

Note:

In the tutorial app you are currently working on, if the native shouldShowRequestPermissionRationale method returns 'false' - i.e. the user has permanently denied permission -, a informative message is displayed to encourage the user to grant the location permission. This informative message is automatically hidden once the user grants permission.

Step 7: Generate a log about permission status

Generating logs about permission status is important because it allows the Adtag platform to calculate on how many devices the SDK is working.

This can be done in a single code line with the sendLogLocationPermissionAccepted method from the AdtagBeaconManager class

adtagBeaconManager.sendLogLocationPermissionAccepted(isPermissionGranted);

In the application tutorial, this code line must be added in:

Step 8: test location permission

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

Note 1:

If you granted location permission in the application and do not get this message, check that the location feature is enabled on your smartphone.

The location feature must be enabled to detect beacons on some Android 6 devices, such as Nexus 5 ou Samsung S6.

Note 2:

Some libraries exist to help you with permission management. E.g. EasyPermissions.