.. _Android Permissions: ===================================== 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 `_ .. contents:: :local: :depth: 1 ---------------------------- 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: .. code-block:: java :linenos: @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. .. code-block:: xml :linenos: 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. .. code-block:: xml :linenos: ---------------------------- 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.