AndroidForegroundServiceType

Kind of work performed by an Android foreground service.

Used by Notifications.start_foreground_service. Each member below includes its pyproject.toml entries and any additional runtime or eligibility requirements. The type-specific foreground-service permissions are required when targeting Android 14+.

Start with this shared configuration, then merge the entries for the selected member into the same service and permission tables:

[tool.flet.android.service."com.dexterous.flutterlocalnotifications.ForegroundService"]
exported = false

[tool.flet.android.permission]
"android.permission.FOREGROUND_SERVICE" = true

Do not repeat a TOML table header when combining examples. When using more than one service type, combine the manifest names with |, for example foregroundServiceType = "location|mediaPlayback", and include the permissions and prerequisites for every selected type. Pass the matching enum members to the method's service_types argument.

Note

Manifest declarations do not grant runtime permissions. Obtain any required runtime grants or consent before starting. Selecting a type does not start camera, recording, location, or other application work, and does not remove Android's background-start or execution-time restrictions.

See the Android service configuration guide for how these entries map to the Android manifest.

Inherits: enum.Enum

Properties

• CAMERA - Camera access while performing foreground-service work.
• CONNECTED_DEVICE - Interaction with an external device, such as a Bluetooth accessory.
• DATA_SYNC - Data transfer or processing, such as upload, download, backup, or import.
• HEALTH - Health or fitness work, such as tracking an exercise session.
• LOCATION - Ongoing location work, such as navigation or location sharing.
• MEDIA_PLAYBACK - Ongoing audio or video playback.
• MEDIA_PROJECTION - Screen capture or projection of device content.
• MICROPHONE - Ongoing microphone capture or audio recording.
• PHONE_CALL - Continuation of a voice or video call.
• REMOTE_MESSAGING - Transfer of text messages between devices for messaging continuity.
• SHORT_SERVICE - Short, critical work subject to Android's short-service time limit.
• SPECIAL_USE - Qualifying foreground work not covered by another service type.
• SYSTEM_EXEMPTED - System integration work that meets Android's exemption criteria.

Properties

buildCAMERAclass-attributeinstance-attribute

Camera access while performing foreground-service work.

Merge these entries with the shared configuration in AndroidForegroundServiceType.

[tool.flet.android.service."com.dexterous.flutterlocalnotifications.ForegroundService"]
foregroundServiceType = "camera"

[tool.flet.android.permission]
"android.permission.FOREGROUND_SERVICE_CAMERA" = true
"android.permission.CAMERA" = true

Note

Obtain the CAMERA runtime grant before starting. While-in-use restrictions usually require starting while the app is visible; background and boot starts are restricted. Declaring CAMERA in this file does not grant access.

See Android's requirements for this type.

buildCONNECTED_DEVICEclass-attributeinstance-attribute

Interaction with an external device, such as a Bluetooth accessory.

Merge these entries with the shared configuration in AndroidForegroundServiceType. This example uses Bluetooth; adapt its transport permission to your use case.

[tool.flet.android.service."com.dexterous.flutterlocalnotifications.ForegroundService"]
foregroundServiceType = "connectedDevice"

[tool.flet.android.permission]
"android.permission.FOREGROUND_SERVICE_CONNECTED_DEVICE" = true
"android.permission.BLUETOOTH_CONNECT" = true

Note

This example is for a Bluetooth connection on Android 12+. Obtain the BLUETOOTH_CONNECT runtime grant before starting. Other operations may need BLUETOOTH_SCAN or BLUETOOTH_ADVERTISE instead.

Note

For other transports, satisfy the applicable prerequisite: a declared network, Wi-Fi, NFC, or infrared permission; a granted UWB permission; or USB device permission obtained through Android's USB permission dialog. Use the permissions for the transport your app actually uses.

See Android's requirements for this type.

buildDATA_SYNCclass-attributeinstance-attribute

Data transfer or processing, such as upload, download, backup, or import.

Merge these entries with the shared configuration in AndroidForegroundServiceType.

[tool.flet.android.service."com.dexterous.flutterlocalnotifications.ForegroundService"]
foregroundServiceType = "dataSync"

[tool.flet.android.permission]
"android.permission.FOREGROUND_SERVICE_DATA_SYNC" = true

Note

This type has no additional type-specific runtime permission prerequisite. Access to the actual data or network may require other permissions. Apps targeting Android 15+ cannot start this type from a boot-completed receiver; Android also applies execution time limits.

See Android's requirements for this type.

buildHEALTHclass-attributeinstance-attribute

Health or fitness work, such as tracking an exercise session.

Merge these entries with the shared configuration in AndroidForegroundServiceType. This example uses activity recognition; adapt its sensor permission to your use case.

[tool.flet.android.service."com.dexterous.flutterlocalnotifications.ForegroundService"]
foregroundServiceType = "health"

[tool.flet.android.permission]
"android.permission.FOREGROUND_SERVICE_HEALTH" = true
"android.permission.ACTIVITY_RECOGNITION" = true

This example is for activity recognition. Obtain the ACTIVITY_RECOGNITION runtime grant before starting.

Other health workloads can qualify through HIGH_SAMPLING_RATE_SENSORS or an appropriate sensor permission. Body-sensor access uses BODY_SENSORS on API 35 and earlier; newer health access can use READ_HEART_RATE, READ_SKIN_TEMPERATURE, or READ_OXYGEN_SATURATION. Declare and request the permissions matching your sensor and Android version, rather than adding all of them.

Note

For body-sensor use subject to while-in-use restrictions, background access also needs BODY_SENSORS_BACKGROUND on API 33–35 or READ_HEALTH_DATA_IN_BACKGROUND on API 36+, as applicable.

See Android's requirements for this type.

buildLOCATIONclass-attributeinstance-attribute

Ongoing location work, such as navigation or location sharing.

Merge these entries with the shared configuration in AndroidForegroundServiceType.

[tool.flet.android.service."com.dexterous.flutterlocalnotifications.ForegroundService"]
foregroundServiceType = "location"

[tool.flet.android.permission]
"android.permission.FOREGROUND_SERVICE_LOCATION" = true
"android.permission.ACCESS_COARSE_LOCATION" = true
"android.permission.ACCESS_FINE_LOCATION" = true

The user must enable device location services and grant coarse or fine location access before the service starts. Request coarse and fine together when precise location is needed; approximate access may be sufficient for your use case.

Note

While-in-use restrictions usually require starting while the app is visible. Starting from the background requires ACCESS_BACKGROUND_LOCATION where applicable, as well as satisfying Android's foreground-service start rules. The block above does not request background location.

See Android's requirements for this type.

buildMEDIA_PLAYBACKclass-attributeinstance-attribute

Ongoing audio or video playback.

Merge these entries with the shared configuration in AndroidForegroundServiceType.

[tool.flet.android.service."com.dexterous.flutterlocalnotifications.ForegroundService"]
foregroundServiceType = "mediaPlayback"

[tool.flet.android.permission]
"android.permission.FOREGROUND_SERVICE_MEDIA_PLAYBACK" = true

Note

This type has no additional type-specific runtime permission prerequisite. It does not start media playback itself. Apps targeting Android 15+ cannot start this type from a boot-completed receiver.

See Android's requirements for this type.

buildMEDIA_PROJECTIONclass-attributeinstance-attribute

Screen capture or projection of device content.

Merge these entries with the shared configuration in AndroidForegroundServiceType.

[tool.flet.android.service."com.dexterous.flutterlocalnotifications.ForegroundService"]
foregroundServiceType = "mediaProjection"

[tool.flet.android.permission]
"android.permission.FOREGROUND_SERVICE_MEDIA_PROJECTION" = true

Note

Obtain the user's screen-capture consent through Android's MediaProjectionManager.createScreenCaptureIntent() flow before starting the service. A manifest permission cannot replace this consent. This extension does not expose that flow; the component performing screen capture must obtain it. Apps targeting Android 15+ cannot start this type from a boot-completed receiver.

See Android's requirements for this type.

buildMICROPHONEclass-attributeinstance-attribute

Ongoing microphone capture or audio recording.

Merge these entries with the shared configuration in AndroidForegroundServiceType.

[tool.flet.android.service."com.dexterous.flutterlocalnotifications.ForegroundService"]
foregroundServiceType = "microphone"

[tool.flet.android.permission]
"android.permission.FOREGROUND_SERVICE_MICROPHONE" = true
"android.permission.RECORD_AUDIO" = true

Note

Obtain the RECORD_AUDIO runtime grant before starting. While-in-use restrictions usually require starting while the app is visible; background and boot starts are restricted. Declaring the permission does not start recording or grant microphone access.

See Android's requirements for this type.

buildPHONE_CALLclass-attributeinstance-attribute

Continuation of a voice or video call.

Merge these entries with the shared configuration in AndroidForegroundServiceType. This example is for a self-managed calling app.

[tool.flet.android.service."com.dexterous.flutterlocalnotifications.ForegroundService"]
foregroundServiceType = "phoneCall"

[tool.flet.android.permission]
"android.permission.FOREGROUND_SERVICE_PHONE_CALL" = true
"android.permission.MANAGE_OWN_CALLS" = true

This example is for a self-managed calling app using Android's ConnectionService APIs and declaring MANAGE_OWN_CALLS. Alternatively, the app can qualify by holding the default-dialer role. Adding this block does not implement calling or obtain that role.

Note

Apps targeting Android 15+ cannot start this type from a boot-completed receiver.

See Android's requirements for this type.

buildREMOTE_MESSAGINGclass-attributeinstance-attribute

Transfer of text messages between devices for messaging continuity.

Merge these entries with the shared configuration in AndroidForegroundServiceType.

[tool.flet.android.service."com.dexterous.flutterlocalnotifications.ForegroundService"]
foregroundServiceType = "remoteMessaging"

[tool.flet.android.permission]
"android.permission.FOREGROUND_SERVICE_REMOTE_MESSAGING" = true

Note

This type has no additional type-specific runtime permission prerequisite. Use it for continuity of messaging between devices, rather than ordinary local notifications or an incoming push message.

See Android's requirements for this type.

buildSHORT_SERVICEclass-attributeinstance-attribute

Short, critical work subject to Android's short-service time limit.

Merge these entries with the shared configuration in AndroidForegroundServiceType.

[tool.flet.android.service."com.dexterous.flutterlocalnotifications.ForegroundService"]
foregroundServiceType = "shortService"

No type-specific foreground-service permission is required; the shared FOREGROUND_SERVICE permission is still needed.

Note

Android limits this type to about three minutes and does not support sticky restart behavior. Use AndroidServiceStartType.NOT_STICKY and call Notifications.stop_foreground_service before the deadline. This type cannot start another foreground service. If combined with another service type, Android ignores shortService and applies the other type's requirements.

See Android's requirements for this type.

buildSPECIAL_USEclass-attributeinstance-attribute

Qualifying foreground work not covered by another service type.

Merge these entries with the shared configuration in AndroidForegroundServiceType.

[tool.flet.android.service."com.dexterous.flutterlocalnotifications.ForegroundService"]
foregroundServiceType = "specialUse"

[tool.flet.android.service."com.dexterous.flutterlocalnotifications.ForegroundService".property]
"android.app.PROPERTY_SPECIAL_USE_FGS_SUBTYPE" = "Describe the service's actual work"

[tool.flet.android.permission]
"android.permission.FOREGROUND_SERVICE_SPECIAL_USE" = true

Note

Replace the subtype description with the specific work your service performs and why it needs this type. Android requires this service property; Google Play reviews the declared use case. This type has no additional type-specific runtime permission prerequisite and is not a substitute for another type that already describes the work.

See Android's requirements for this type.

buildSYSTEM_EXEMPTEDclass-attributeinstance-attribute

System integration work that meets Android's exemption criteria.

Merge these entries with the shared configuration in AndroidForegroundServiceType.

[tool.flet.android.service."com.dexterous.flutterlocalnotifications.ForegroundService"]
foregroundServiceType = "systemExempted"

[tool.flet.android.permission]
"android.permission.FOREGROUND_SERVICE_SYSTEM_EXEMPTED" = true

Note

The app must independently meet Android's eligibility criteria, such as being a qualifying device-management app, a configured VPN, or holding an applicable exact-alarm permission for the permitted use case. Declaring the permission alone does not make the app eligible; Android rejects this type for ineligible apps. Ordinary applications cannot select it to bypass limits.

See Android's requirements for this type.