sodcalculator

10 Tech How-To

How to Request Foreground Service Permissions in Android

Guide 10-47420 · Updated · Step by step

This guide walks you through requesting the correct foreground service permissions in Android, covering the required manifest declarations, runtime permission requests, and the Android 14+ foreground service type requirements. By the end, you’ll know exactly which permissions your app needs and how to request them properly.

What You’ll Need

  • Android Studio (latest stable version recommended)
  • An Android device or emulator running Android 6.0 (API 23) or higher for runtime permissions, and Android 14 (API 34) or higher to test the new foreground service type requirements
  • Basic familiarity with Android manifest files and Kotlin/Java code

Step-by-Step

  1. Identify your foreground service type. Android 14 (API 34) requires you to declare a specific type for each foreground service. Common types include location, camera, microphone, mediaPlayback, dataSync, connectedDevice, and phoneCall. Choose the one that matches the primary function of your service.
  2. Add the FOREGROUND_SERVICE permission. In your AndroidManifest.xml, add <uses-permission android:name="android.permission.FOREGROUND_SERVICE" /> before the <application> tag. This is required for any foreground service.
  3. Add the permission for your specific service type. For each type, Android requires an additional permission. For example, for location: <uses-permission android:name="android.permission.FOREGROUND_SERVICE_LOCATION" />; for camera: FOREGROUND_SERVICE_CAMERA; for microphone: FOREGROUND_SERVICE_MICROPHONE; for connected device: FOREGROUND_SERVICE_CONNECTED_DEVICE; for media playback: FOREGROUND_SERVICE_MEDIA_PLAYBACK; for data sync: FOREGROUND_SERVICE_DATA_SYNC. These are normal permissions, so they are granted automatically at install time.
  4. Add the runtime permissions your service needs. If your service accesses sensitive data (e.g., location, camera, microphone), you must also request those runtime permissions. For location, add ACCESS_FINE_LOCATION and/or ACCESS_COARSE_LOCATION; for camera, add CAMERA; for microphone, add RECORD_AUDIO. These are dangerous permissions and must be requested at runtime.
  5. Declare the service in your manifest. Inside <application>, add a <service> element with the android:foregroundServiceType attribute. For example, for a location service: <service android:name=".LocationService" android:foregroundServiceType="location" />. For multiple types, use a pipe: android:foregroundServiceType="location|connectedDevice".
  6. Request runtime permissions in your code. Before starting the foreground service, check if the required runtime permissions are granted. If not, request them using ActivityCompat.requestPermissions() or the newer registerForActivityResult() API. Only start the service after permissions are granted.
  7. Start the foreground service. Use ContextCompat.startForegroundService() (or startForegroundService() on API 26+) to start the service. Inside the service’s onStartCommand(), call startForeground() with a notification within 5 seconds of being started.
  8. For Android 14+, handle the while-in-use permission. If your service type is location, camera, or microphone, you must also request the corresponding while-in-use permission (e.g., ACCESS_COARSE_LOCATION or ACCESS_FINE_LOCATION for location) and ensure the user grants it. The system will show a runtime prompt for these.
  9. Test on both old and new Android versions. Run your app on Android 13 and below to ensure the old permission flow works, and on Android 14+ to verify the new type requirements are met. Use the adb shell dumpsys activity services command to check if your service is running as a foreground service.

Common Mistakes

  • Forgetting the type-specific permission. On Android 14+, if you declare a foreground service type without the corresponding permission, the app will crash with a SecurityException when starting the service.
  • Not requesting runtime permissions before starting the service. If you start a foreground service that needs location without having the runtime permission, the system will throw a SecurityException.
  • Using the wrong foreground service type. For example, using dataSync for a media player will cause the service to be killed quickly on Android 14+ because dataSync has a 6-hour timeout.
  • Not calling startForeground() promptly. If you don’t call startForeground() within 5 seconds of startForegroundService(), the system throws ForegroundServiceDidNotStartInTimeException and the app crashes.
  • Declaring the service type but not the permission. The manifest must include both the foregroundServiceType attribute and the corresponding FOREGROUND_SERVICE_* permission.

Tips

  • Use the foregroundServiceType attribute with multiple types when needed. For example, a navigation app might use location and connectedDevice for a Bluetooth headset.
  • Check the user’s response to runtime permission requests. If the user denies a permission, don’t start the service; instead, explain why the permission is needed and offer to re-request.
  • For Android 14+, consider using the while-in-use restrictions. The system may restrict the launch of certain foreground service types from the background. Ensure your service is started from a user-visible action (like a button tap) to avoid issues.
  • Use the android:stopWithTask attribute on the service if you want the service to stop when the user swipes away the app from recents, or set it to false if you want it to continue.
  • Keep the notification channel ID consistent. Create a notification channel for your foreground service notification and reuse it every time.

Troubleshooting

  • SecurityException: “Starting FGS with type ‘location’ permission not granted” — This means you haven’t requested the runtime location permission or it was denied. Request ACCESS_FINE_LOCATION (or coarse) before starting the service.
  • ForegroundServiceDidNotStartInTimeException — Your service didn’t call startForeground() within 5 seconds. Move the startForeground() call to the very beginning of onStartCommand().
  • App crashes on Android 14 but works on older versions — Verify that you’ve added the type-specific permission (e.g., FOREGROUND_SERVICE_LOCATION) and that the foregroundServiceType attribute matches the permission.
  • Service stops unexpectedly — On Android 14+, certain types like dataSync have time limits. If your service runs longer, consider using a different type or splitting the work into chunks.
  • Permission dialog doesn’t appear — Make sure you’re requesting the permission from an Activity context, not from the service itself. Also check that the permission is declared in the manifest.

Frequently Asked Questions

Do I need the FOREGROUND_SERVICE permission on all Android versions?

Yes, since Android 9 (API 28), the FOREGROUND_SERVICE permission is required for any app that starts a foreground service.

What is the difference between FOREGROUND_SERVICE and FOREGROUND_SERVICE_LOCATION?

FOREGROUND_SERVICE is the base permission to run any foreground service. FOREGROUND_SERVICE_LOCATION is an additional permission required specifically for foreground services that access location, and it’s enforced on Android 14+.

Can I use the same permission for multiple service types?

No, each foreground service type has its own specific permission (e.g., FOREGROUND_SERVICE_CAMERA, FOREGROUND_SERVICE_MICROPHONE). You need to declare all that apply to your service.

What happens if I don’t declare a foregroundServiceType on Android 14?

Your app will crash with a SecurityException when it tries to start the foreground service, because the system requires a type declaration.

Do I need to request runtime permissions for every foreground service type?

No, only for types that access sensitive data like location, camera, or microphone. For example, a media playback service doesn’t need a runtime permission, but a location service does.

Can I start a foreground service from the background?

Starting from the background is restricted on Android 12+ and further restricted on Android 14+. You should start the service from a foreground context, like when the user interacts with your app.

Related

General steps for current mainstream versions; menus can differ by device and version. See the disclaimer or report an error.

More in this bed

The whole Tech How-To bed →