Permissions

Bluetooth

Bluetooth permission is needed for Proximity Transfer to work properly. If the permission is not granted, you need to ask for permission or explain to the user to grant it manually in the app setting.

Manifest declaration

To be able to use Bluetooth in your app, you need to declare several permissions in your AndroidManifest.xml app file.

<!-- Permissions required for Android 6 - 11 -->
<uses-permission android:name="android.permission.BLUETOOTH" android:maxSdkVersion="30" />
<uses-permission android:name="android.permission.BLUETOOTH_ADMIN" android:maxSdkVersion="30" />

<!-- Permissions required for Android 6 - 9 -->
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />

<!-- Permissions required for Android 10 - 11 -->
<uses-permission android:name="ACCESS_FINE_LOCATION" />

<!-- Permissions required for Android 12+ -->
<uses-permission android:name="android.permission.BLUETOOTH_SCAN" android:usesPermissionFlags="neverForLocation" tools:targetApi="s" />
<uses-permission android:name="android.permission.BLUETOOTH_CONNECT" />
<uses-permission android:name="android.permission.BLUETOOTH_ADVERTISE" />

<!-- HW declaration -->
<uses-feature android:name="android.hardware.bluetooth" android:required="false"/>
<uses-feature android:name="android.hardware.bluetooth_le" android:required="false"/>

Permission not granted

When a required permission is not granted, you should request a user for it. This can happen in start/stop functions in WPTSource and WPTTarget classes when WPTSourceError with the reason BLUETOOTH_PERMISSION_NOT_GRANTED is reported.

You can use WPTPermissions to get which permissions are required for the current device.

Bluetooth off

When the Bluetooth is off in the system settings, the user needs to turn it on.

Location off (Android 6-11)

On older Androids, location services are required to scan Bluetooth devices. If the user has location services turned off, you need to show the prompt asking to turn it on.

Example:

class MyFragment: Fragment {

    private val source: WPTSource // obtain source instance
    
    // permission launcher to request permission
    private val requestBTPermissionLauncher = registerForActivityResult(ActivityResultContracts.RequestPermission()) { isGranted ->
        if (isGranted) {
            // OK
        } else {
            // rejected
        }
    }
    
    private val requestBTLauncher = registerForActivityResult(ActivityResultContracts.StartActivityForResult()) { result ->
        if (result.resultCode != Activity.RESULT_OK) {
            // rejected
        } else {
            // OK
        }
    }
    
    fun start() {
        // start the source
        source.start { result ->
            result.onSuccess {
                // started
            }.onFailure { error -> 
                //Make sure the error is the expected type
                if (error is WPTSourceError) {
                     when (error.reason) {
                        // Bluetooth off - ask to turn on
                        WPTSourceError.Reason.BLUETOOTH_NOT_ENABLED -> {
                            // show system dialog to enable BT
                            val enableBtIntent = Intent(BluetoothAdapter.ACTION_REQUEST_ENABLE)
                            requestBTLauncher.launch(enableBtIntent)
                        }
                        // reason when permission was not granted
                        WPTSourceError.Reason.BLUETOOTH_PERMISSION_NOT_GRANTED -> {
                            // try to request all permissions
                            WPTPermissions.sourceBTPermissions().forEach { permission ->
                                // if rationale should be displayed (meaning that the user previously declined the permission)
                                if (shouldShowPermissionRationale(permission)) {
                                    // show rationale
                                } else {
                                    requestPermissionLauncher.launch(permission)
                                }
                            }
                        }
                        WPTSourceError.Reason.LOCATION_NOT_ENABLED -> {
                            AlertDialog.Builder(requireContext())
                                .setTitle("Error")
                                .setMessage("Location services are required.")
                                .setPositiveButton("Enable") { _, _ ->
                                    // navigates the user to the system settings
                                    startActivity(Intent(android.provider.Settings.ACTION_LOCATION_SOURCE_SETTINGS))
                                }
                                .setNegativeButton("Cancel") { _, _ ->
                                    // cancel the transfer
                                }
                                .show()
                        }
                        else -> {
                            // other reason
                        }
                     }
                } else {
                    // other error
                }
            }
        }
    }
    
    private fun shouldShowPermissionRationale(permission: String): Boolean {
        return ActivityCompat.shouldShowRequestPermissionRationale(requireActivity(), permission)
    }
}

Camera

To be able to scan the QR code, you need camera permissions. The SDK does not provide any functionality for this purpose, so please follow the official documentation when needed.