Android permissions
Permissions
This page contains details on permissions that need to be enabled on Android devices for the smooth performance of various Fairmatic SDK functionalities.
| Legend | Meaning |
|---|---|
 | The permission is vital for this product to function. |
 | Lack of this permission may interfere with the product's functioning. |
 | The permission is not needed for the product to function. |
| Product | Location | Activity | Overlay |
|---|---|---|---|
| Trip Detection | | | |
| Trip Mileage | | | |
| Collision Detection | | | |
| Driving Behavior - Hard Brake | | | |
| Driving Behavior - Hard Turns | | | |
| Driving Behavior - Rapid Acceleration | | | |
| Driving Behavior - Overspeeding | | | |
| Driving Behavior - Phone Use | | | |
Many SDK features are dependent on trip detection, therefore Location Permission is needed for every feature.
SDK Errors
The Fairmatic SDK provides the following permission errors to indicate high-priority permission needs:
| Error | Description |
|---|---|
LOCATION_PERMISSION_DENIED | This error is sent if background location permission is denied, even if foreground permission is granted. |
ACTIVITY_RECOGNITION_PERMISSION_DENIED | Activity permission is required for trip detection. |
PRECISE_LOCATION_DENIED | This will be returned on devices running on Android 12 and above when the user has set the location accuracy for the application as "Approximate". Fairmatic SDK needs the location access accuracy for the application to be set as "Precise" to operate. |
LOCATION_MODE_HIGH_ACCURACY_DENIED | This will be returned on devices running on Android versions 4.4 to 8.1 when user has not set location mode as LOCATION_MODE_HIGH_ACCURACY. |
BACKGROUND_RESTRICTION_ENABLED | This error indicates that background restrictions are on. Background restrictions may cause the trip to be missed while the app is in the background. If the app is running in the foreground, the trip may be detected. |
GOOGLE_PLAY_CONNECTION_ERROR | This error indicates that something went wrong in trying to connect to Google Play Services. See Google Play Services reference. |
AIRPLANE_MODE_ENABLED | This error indicates that airplane mode is active. Airplane mode affects location accuracy and can affect all features. |
The Fairmatic SDK provides the following permission errors to indicate low-priority permission needs:
| Error | Description |
|---|---|
BATTERY_OPTIMIZATION_ENABLED | This is the standard battery optimization setting on Android. However, Samsung's implementation restricts background execution significantly on many devices. So, this error is thrown only on Samsung devices. |
INTERNAL_ERROR | Some specific error occurred internally. It could be around battery or something OEM specific. Check if you are restricting the SDK ability due to some device setting |
Handling Errors
We recommend acquiring permissions during an onboarding process that clearly explains why those permissions are needed. The onboarding process for location permission in our in-house app is shown below for reference.
Example permission flow for Android
If an error is thrown after the onboarding process, a notification can indicate to the user that certain permission is needed. Use that notification to direct them to the correct screen or one describing why the permission is needed.
Missing permission notification