Android Permissions

Permissions in Android are a crucial aspect of app development, allowing applications to access sensitive resources or perform specific actions on the device.

In libSoftphone, we’ve carefully considered the permissions necessary for its functionality. Some permissions are bundled within the library itself, while others need to be manually added by developers integrating the library into their projects. In this article, we’ll delve into the required and optional permissions in libSoftphone, along with explanations for their necessity.

The Android SDK categorizes permissions into two main categories. You can read more about them and their impact to the users here:

• Android documentation on Runtime Permissions

• Android documentation on Normal Permissions

Required Runtime Permissions

These permissions are essential for libSoftphone to function correctly. They are bundled within the library’s AndroidManifest.xml file, ensuring that the necessary access is granted at runtime without additional configuration by developers.

The libSoftphone SDK automatically requests there permissions when they are required, and developers need to handle only a minimal amount of code to ensure that the permissions are granted.

To report permission results, please include the following code in your activity:

@MainThread
@Override
public void onRequestPermissionsResult(int requestCode, @NonNull String[] permissions, @NonNull int[] results)
{
    Permission.onRequestPermissionResult(requestCode, permissions, results);
    super.onRequestPermissionsResult(requestCode, permissions, results);
}

For more guidance on handling runtime permissions in Android, refer to the official Android documentation on Requesting Permissions at Runtime.

Here is a list of the required runtime permissions for libSoftphone:

• RECORD_AUDIO

  This permission is required because libSoftphone needs to access the device’s microphone to capture audio during VoIP calls.

• READ_PHONE_STATE

  Used to retrieve the state of ongoing calls. Used to manage PhoneAccounts to be used with ConnectionService.

Required Foreground Service Permissions

Same as runtime permissions, these permissions are essential for libSoftphone to function correctly. They allow libSoftphone to work in background and correctly register to the SIPIS servers.

As per the recent changes in the Google Play Console, these permissions need to be declared and a justification for their use needs to be provided. The explanations here should give you a good starting point for completing the foreground service declaration form.

Here is a list of the required foreground service permissions for libSoftphone:

• FOREGROUND_SERVICE_TYPE_PHONE_CALL

  Required to handle SIP registration and VoIP calls, must be added together with MANAGE_OWN_CALLS.

• FOREGROUND_SERVICE_TYPE_MICROPHONE

  Required to guarantee access to microphone during calls.

Required Normal Permissions

There permission are granted by Android automatically and do not require any additional code to be written by the developer. They are bundled within the library’s AndroidManifest.xml file, ensuring that the necessary access is granted at runtime without additional configuration by developers.

As of writing they also do not require any justification in the Google Play Console.

Here is a list of the required normal permissions for libSoftphone:

• FOREGROUND_SERVICE

  This is a baseline permission that is required if any Foreground Service is to be used.

• INTERNET

  We need to access the internet to make and receive calls.

• ACCESS_NETWORK_STATE

  This permission is required to check the network state and to determine if the device is connected to the internet.

• ACCESS_WIFI_STATE

  This permission is required to check the WiFi state and to determine if the device is connected to a WiFi network.

• CHANGE_NETWORK_STATE

  We use this to enforce calls to be made over WiFi, or Mobile Data.

• VIBRATE

  This permission is required to vibrate the device when a call is received.

• MANAGE_OWN_CALLS

  This is an essential permission to properly support ConnectionService.

Recommended Runtime Permissions

There permissions are not included in the libSoftphone library’s AndroidManifest.xml file. They are not essential for the library to function, but they can enhance the user experience and provide additional functionality.

It is up to you to request these permissions in your application’s code. The SDK will not request them automatically.

If the SDK detects that these permissions are provided in the host application’s AndroidManifest.xml file, it will enable aditional features.

If you want to enable these features, you need to add the permissions to your application’s AndroidManifest.xml file.

<?xml version="1.0" encoding="utf-8"?>
<manifest xmlns:android="http://schemas.android.com/apk/res/android" xmlns:tools="http://schemas.android.com/tools">

    <uses-permission android:name="The permission string as per Android documentation" />

</manifest>

Here is a list of the recommended runtime permissions for libSoftphone:

• BLUETOOTH_CONNECT

  The SDK will be able to detect the exact bluetooth device type. For example to determine if a headset or smart watch is connected.

  To fully enable the Bluetooth feature, you need to add the following to your application’s AndroidManifest.xml file.

  <?xml version="1.0" encoding="utf-8"?>
  <manifest xmlns:android="http://schemas.android.com/apk/res/android" xmlns:tools="http://schemas.android.com/tools">
  
          <uses-feature android:name="android.hardware.bluetooth" android:required="false" />
  
  </manifest>
  

Optional Runtime Permissions

The permissions from this section enable additional features in the SDK that you might want to include depending on your final app’s usecase. These permissions are not included in the libSoftphone library’s AndroidManifest.xml file.

It is up to the application developer to add the permissions to application’s manifest and to request these permissions in the application’s code.

Here is a list of the optional runtime permissions for libSoftphone:

• ACCESS_COARSE_LOCATION and ACCESS_FINE_LOCATION

  To be used when your app is using the registration or call location policy features.

• READ_CONTACTS

  This permission is used to access the device’s contacts and enables contact matching for CallEvents.

• CALL_PHONE

  This is used to place GSM calls from the SDK, e.g. as a fallback when VoIP is not available or not suitable.

• SCHEDULE_EXACT_ALARM

  Used to periodically wake up the SDK in standard (non-push) incoming calls mode. If your app is using push, you don’t need this permission.

Optional Foreground Service Permissions

Same as the optional runtime permissions, these permissions are not included in the libSoftphone library’s AndroidManifest.xml file.

As per the recent changes in the Google Play Console, these permissions need to be declared and a justification for their use needs to be provided. The explanations here should give you a good starting point for completing the foreground service declaration form.

• FOREGROUND_SERVICE_LOCATION

  The SDK uses this when your app is using the registration or call location policy features.