The Pulsate SDK requires an Android system permission, Location which is required for beacon scans, geofencing and location updates. Different Android versions require different permissions and must be asked for in the proper way or the App not operate in the most efficient way or problems could emerge.

Android 12

Google has introduced new permissions to be able to scan for beacons.

<uses-permission android:name="android.permission.BLUETOOTH_SCAN" />
<uses-permission android:name="android.permission.BLUETOOTH_CONNECT" />

There are many ways to ask for permissions and libraries / frameworks that do it for you. Below is one way you can use to ask for permissions.

private val requestMultiplePermissions = registerForActivityResult(RequestMultiplePermissions()) { }

private fun checkAndRequestPermissions(): Boolean {
    val listPermissionsNeeded: MutableList<String> = ArrayList()
    if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.S) {
        val blePermission = ContextCompat.checkSelfPermission(
                requireContext(),
            Manifest.permission.BLUETOOTH_SCAN
        )
        val bleConnectPermission = ContextCompat.checkSelfPermission(
            requireContext(),
            Manifest.permission.BLUETOOTH_CONNECT
        )
        if (blePermission != PackageManager.PERMISSION_GRANTED) {
            listPermissionsNeeded.add(Manifest.permission.BLUETOOTH_SCAN)
        }
        if (bleConnectPermission != PackageManager.PERMISSION_GRANTED) {
           listPermissionsNeeded.add(Manifest.permission.BLUETOOTH_CONNECT)
        }
    }

    if (listPermissionsNeeded.isNotEmpty()) {
        requestMultiplePermissions.launch(listPermissionsNeeded.toTypedArray())
        return false
    }
    return true
}

Android 11

Google has introduced new guidelines for “Sensitive app permissions”, inluding android.permission.BACKGROUND_LOCATION, which the Pulsate SDK automatically adds to your app’s AndroidManifest. While submitting your app, you may find your app being rejected by Google Play Console. In order to mitigate this, we recommend that you follow the below steps to mitigate this risk.

More information related to the new changes related to Location Permissions is located here:
https://developer.android.com/about/versions/11/privacy/location

When you install the Pulsate SDK, the location following permission settings will automatically be added to the AndroidManifest file.

<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
<uses-permission android:name="android.permission.ACCESS_BACKGROUND_LOCATION" />

You must first ask for ACCESS_FINE_LOCATION and ACCESS_COARSE_LOCATION permissions and only when these are granted you can ask for ACCESS_BACKGROUND_LOCATION.

We recommend explaining to users why your App needs location before showing the permission.

On your initial priming screen you should specify why the app needs foreground permissions.

Use cases may include:

  • Customer Service
  • Marketing Communications
  • Improved Engagement experience
1080

Once the user clicks on the action button to Accept the Permissions, they must be prompted to allow foreground permission "While using the app"

1080

To request foreground location permissions (as pictured above) you can use the code below.

// On Foreground Location Priming Screen
if (android.os.Build.VERSION.SDK_INT >= android.os.Build.VERSION_CODES.R) {
  int foregroundCheck = ActivityCompat.checkSelfPermission(this, Manifest.permission.ACCESS_FINE_LOCATION);
  if (foregroundCheck != PackageManager.PERMISSION_GRANTED) {
    requestPermissions(new String[]{Manifest.permission.ACCESS_FINE_LOCATION}, 1);
  }
}

After the user accepts foreground location we can ask for background location. Background location does not show a permission prompt, instead it takes the user the App Settings.

Just like for foreground location we recommend explaining to users why your App needs background location before taking him to them to App Settings.

When explaining background location make sure to:

1) To clearly specify why you need the sensitive "Background" location permission.

Use cases may include:

  • To Receive location based support
  • Save you time at the Drive-thru
  • Get notified of exclusive in-Branch/in-store Services.

2) To explain to the end user that they must click "Allow all the time" on the following screen

1080

Once the user accepts allowing background permissions, you will present them with the system background permission screen. Here, they must select "Allow all the time"

1080

To request background location permissions (as pictured above) you can use the code below.

// Background Location Priming Screen
if (android.os.Build.VERSION.SDK_INT >= android.os.Build.VERSION_CODES.R) {
  int backgroundCheck = ActivityCompat.checkSelfPermission(this, Manifest.permission.ACCESS_BACKGROUND_LOCATION);
  if (backgroundCheck != PackageManager.PERMISSION_GRANTED) {
    requestPermissions(new String[]{Manifest.permission.ACCESS_BACKGROUND_LOCATION}, 1);
  }
}

Android 10

In Android Manifest add -

<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
<uses-permission android:name="android.permission.ACCESS_BACKGROUND_LOCATION" />

When asking for location permission ask for it like this -

if (android.os.Build.VERSION.SDK_INT == android.os.Build.VERSION_CODES.Q) {
    ActivityCompat.requestPermissions(activity,
        new String[]{Manifest.permission.ACCESS_FINE_LOCATION, Manifest.permission.ACCESS_BACKGROUND_LOCATION}, 1);
}

Android 9 and under

In Android Manifest add -

<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />

When asking for location permission ask for it like this -

ActivityCompat.requestPermissions(activity,
        new String[]{Manifest.permission.ACCESS_FINE_LOCATION}, 1);