Le type de service au premier plan doit être indiqué

Pour aider les développeurs à définir des services de premier plan destinés aux utilisateurs, Android 10 a introduit l'attribut android:foregroundServiceType dans l'élément <service>.

Si votre application cible Android 14, elle doit spécifier les types de services de premier plan appropriés. Comme dans les versions précédentes d'Android, vous pouvez combiner plusieurs types. Cette liste présente les types de services de premier plan disponibles :

Si un cas d'utilisation dans votre application n'est associé à aucun de ces types, nous vous recommandons fortement de migrer votre logique pour utiliser WorkManager ou les tâches de transfert de données lancé par l'utilisateur.

Les types health, remoteMessaging, shortService, specialUse et systemExempted sont nouveaux sur Android 14.

L'extrait de code suivant fournit un exemple de déclaration de type de service de premier plan dans le fichier manifeste :

<manifest ...>
  <uses-permission android:name="android.permission.FOREGROUND_SERVICE" />
  <uses-permission android:name="android.permission.FOREGROUND_SERVICE_MEDIA_PLAYBACK" />
    <application ...>
      <service
          android:name=".MyMediaPlaybackService"
          android:foregroundServiceType="mediaPlayback"
          android:exported="false">
      </service>
    </application>
</manifest>

Si une application qui cible Android 14 ne définit pas de types pour un service donné dans le fichier manifeste, le système génère MissingForegroundServiceTypeException lors de l'appel de startForeground() pour ce service.

Déclarer une nouvelle autorisation pour utiliser les types de services de premier plan

If apps that target Android 14 use a foreground service, they must declare a specific permission, based on the foreground service type, that Android 14 introduces. These permissions appear in the sections labeled "permission that you must declare in your manifest file" in the intended use cases and enforcement for each foreground service type section on this page.

All of the permissions are defined as normal permissions and are granted by default. Users cannot revoke these permissions.

Inclure le type de service de premier plan lors de l'exécution

Une bonne pratique pour les applications qui lancent des services de premier plan consiste à utiliser la version ServiceCompat de startForeground() (disponible dans androidx-core 1.12 et versions ultérieures), dans laquelle vous transmettez un entier bit à bit de types de service de premier plan. Vous pouvez choisir de transmettre une ou plusieurs valeurs de type.

En règle générale, vous ne devez déclarer que les types requis pour un cas d'utilisation particulier. Cela permet de répondre plus facilement aux attentes du système pour chaque type de service de premier plan. Si un service de premier plan est démarré avec plusieurs types, il doit respecter les exigences d'application des plates-formes de tous les types.

ServiceCompat.startForeground(0, notification, FOREGROUND_SERVICE_TYPE_LOCATION)

Si le type de service de premier plan n'est pas spécifié dans l'appel, il utilise par défaut les valeurs définies dans le fichier manifeste. Si vous n'avez pas spécifié le type de service dans le fichier manifeste, le système génère MissingForegroundServiceTypeException.

Si le service de premier plan a besoin de nouvelles autorisations après son lancement, vous devez appeler à nouveau startForeground() et ajouter les nouveaux types de services. Par exemple, supposons qu'une application de fitness exécute un service de suivi de la course à pied qui a toujours besoin des informations location, mais qui peut ou non avoir besoin d'autorisations media. Vous devez déclarer à la fois location et mediaPlayback dans le fichier manifeste. Si un utilisateur démarre une exécution et souhaite simplement suivre sa position, votre application doit appeler startForeground() et ne transmettre que le type de service location. Ensuite, si l'utilisateur souhaite commencer à lire un contenu audio, appelez à nouveau startForeground() et transmettez location|mediaPlayback.

Vérifications de l'exécution du système

The system checks for proper use of foreground service types and confirms that the app has requested the proper runtime permissions or uses the required APIs. For instance, the system expects apps that use the foreground service type FOREGROUND_SERVICE_TYPE_LOCATION type to request either ACCESS_COARSE_LOCATION or ACCESS_FINE_LOCATION.

This implies that apps must follow a very specific order of operations when requesting permissions from the user and starting foreground services. Permissions must be requested and granted before the app attempts to call startForeground(). Apps that request the appropriate permissions after the foreground service has been started must change this order of operations and request the permission before starting the foreground service.

The specifics of platform enforcement appear in the sections labeled "runtime requirements" in the intended use cases and enforcement for each foreground service type section on this page.

Cas d'utilisation prévus et application forcée pour chaque type de service de premier plan

Pour utiliser un type de service de premier plan donné, vous devez déclarer une autorisation particulière dans votre fichier manifeste, respecter des exigences d'exécution spécifiques et votre application doit respecter l'un des ensembles de cas d'utilisation prévus pour ce type. Les sections suivantes décrivent les autorisations que vous devez déclarer, les conditions préalables d'exécution et les cas d'utilisation prévus pour chaque type.

Appareil photo

Type de service de premier plan à déclarer dans le fichier manifeste sous android:foregroundServiceType
camera
Autorisation à déclarer dans votre fichier manifeste
FOREGROUND_SERVICE_CAMERA
Constante à transmettre à startForeground()
FOREGROUND_SERVICE_TYPE_CAMERA
Conditions préalables d'exécution

Demander l'autorisation d'exécution CAMERA et l'obtenir

Remarque:L'autorisation d'exécution CAMERA est soumise à des restrictions d'utilisation. Pour cette raison, vous ne pouvez pas créer de service de premier plan camera lorsque votre application est en arrière-plan, à quelques exceptions près. Pour en savoir plus, consultez la section Restrictions concernant le démarrage de services de premier plan nécessitant des autorisations en cours d'utilisation.

Description

Continuez à avoir accès à la caméra en arrière-plan, pour les applications de chat vidéo permettant d'effectuer plusieurs tâches en même temps, par exemple.

Appareil connecté

Type de service de premier plan à déclarer dans le fichier manifeste sous
android:foregroundServiceType
connectedDevice
Autorisation à déclarer dans votre fichier manifeste
FOREGROUND_SERVICE_CONNECTED_DEVICE
Constante à transmettre à startForeground()
FOREGROUND_SERVICE_TYPE_CONNECTED_DEVICE
Conditions préalables d'exécution

Vous devez remplir l'une des conditions suivantes :

Description

Interactions avec des appareils externes nécessitant une connexion Bluetooth, NFC, IR, USB ou réseau.

Autres solutions

Si votre application doit effectuer un transfert de données continu vers un appareil externe, envisagez d'utiliser le gestionnaire d'appareils associés à la place. Utilisez l'API de présence de l'appareil associé pour que votre application reste en cours d'exécution lorsque l'appareil associé est à portée.

Si votre application doit rechercher des appareils Bluetooth, envisagez plutôt d'utiliser l'API de recherche Bluetooth.

Synchroniser les données

Foreground service type to declare in manifest under
android:foregroundServiceType
dataSync
Permission to declare in your manifest
FOREGROUND_SERVICE_DATA_SYNC
Constant to pass to startForeground()
FOREGROUND_SERVICE_TYPE_DATA_SYNC
Runtime prerequisites
None
Description

Data transfer operations, such as the following:

  • Data upload or download
  • Backup-and-restore operations
  • Import or export operations
  • Fetch data
  • Local file processing
  • Transfer data between a device and the cloud over a network
Alternatives

See Alternatives to data sync foreground services for detailed information.

Santé

Foreground service type to declare in manifest under
android:foregroundServiceType
health
Permission to declare in your manifest
FOREGROUND_SERVICE_HEALTH
Constant to pass to startForeground()
FOREGROUND_SERVICE_TYPE_HEALTH
Runtime prerequisites

At least one of the following conditions must be true:

Note: The BODY_SENSORS runtime permission is subject to while-in-use restrictions. For this reason, you cannot create a health foreground service that uses body sensors while your app is in the background, with a few exceptions. For more information, see Restrictions on starting foreground services that need while-in-use permissions.

Description

Any long-running use cases to support apps in the fitness category such as exercise trackers.

Localisation

Foreground service type to declare in manifest under
android:foregroundServiceType
location
Permission to declare in your manifest
FOREGROUND_SERVICE_LOCATION
Constant to pass to startForeground()
FOREGROUND_SERVICE_TYPE_LOCATION
Runtime prerequisites

The user must have enabled location services and the app must be granted at least one of the following runtime permissions:

Note: In order to check that the user has enabled location services as well as granted access to the runtime permissions, use PermissionChecker#checkSelfPermission()

Note: The location runtime permissions are subject to while-in-use restrictions. For this reason, you cannot create a location foreground service while your app is in the background, unless you've been granted the ACCESS_BACKGROUND_LOCATION runtime permission. For more information, see Restrictions on starting foreground services that need while-in-use permissions.

Description

Long-running use cases that require location access, such as navigation and location sharing.

Alternatives

If your app needs to be triggered when the user reaches specific locations, consider using the geofence API instead.

Contenus multimédias

Foreground service type to declare in manifest under
android:foregroundServiceType
mediaPlayback
Permission to declare in your manifest
FOREGROUND_SERVICE_MEDIA_PLAYBACK
Constant to pass to startForeground()
FOREGROUND_SERVICE_TYPE_MEDIA_PLAYBACK
Runtime prerequisites
None
Description
Continue audio or video playback from the background. Support Digital Video Recording (DVR) functionality on Android TV.
Alternatives
If you're showing picture-in-picture video, use Picture-in-Picture mode.

Projection multimédia

Type de service de premier plan à déclarer dans le fichier manifeste sous
android:foregroundServiceType
mediaProjection
Autorisation à déclarer dans votre fichier manifeste
FOREGROUND_SERVICE_MEDIA_PROJECTION
Constante à transmettre à startForeground()
FOREGROUND_SERVICE_TYPE_MEDIA_PROJECTION
Conditions préalables d'exécution

Appelez la méthode createScreenCaptureIntent() avant de démarrer le service de premier plan. Une notification d'autorisation s'affiche alors auprès de l'utilisateur. Celui-ci doit accorder l'autorisation avant que vous puissiez créer le service.

Une fois le service de premier plan créé, vous pouvez appeler MediaProjectionManager.getMediaProjection().

Description

Projetez du contenu sur un écran externe ou un appareil externe à l'aide des API MediaProjection. Il ne doit pas nécessairement s'agir de contenu exclusivement multimédia.

Autres solutions

Pour diffuser des contenus multimédias en streaming sur un autre appareil, utilisez le SDK Google Cast.

Micro

Foreground service type to declare in manifest under
android:foregroundServiceType
microphone
Permission to declare in your manifest
FOREGROUND_SERVICE_MICROPHONE
Constant to pass to startForeground()
FOREGROUND_SERVICE_TYPE_MICROPHONE
Runtime prerequisites

Request and be granted the RECORD_AUDIO runtime permission.

Note: The RECORD_AUDIO runtime permission is subject to while-in-use restrictions. For this reason, you cannot create a microphone foreground service while your app is in the background, with a few exceptions. For more information, see Restrictions on starting foreground services that need while-in-use permissions.

Description

Continue microphone capture from the background, such as voice recorders or communication apps.

Appel téléphonique

Foreground service type to declare in manifest under
android:foregroundServiceType
phoneCall
Permission to declare in your manifest
FOREGROUND_SERVICE_PHONE_CALL
Constant to pass to startForeground()
FOREGROUND_SERVICE_TYPE_PHONE_CALL
Runtime prerequisites

At least one of these conditions must be true:

  • App is the default dialer app through the ROLE_DIALER role.
Description

Continue an ongoing call using the ConnectionService APIs.

Alternatives

If you need to make phone, video, or VoIP calls, consider using the android.telecom library.

Consider using CallScreeningService to screen calls.

Messagerie à distance

Type de service de premier plan à déclarer dans le fichier manifeste sous
android:foregroundServiceType
remoteMessaging
Autorisation à déclarer dans votre fichier manifeste
FOREGROUND_SERVICE_REMOTE_MESSAGING
Constante à transmettre à startForeground()
FOREGROUND_SERVICE_TYPE_REMOTE_MESSAGING
Conditions préalables d'exécution
Aucune
Description
Transférez des messages d'un appareil à un autre. Contribue à la continuité des tâches de messagerie d'un utilisateur lorsqu'il change d'appareil.

Service court

Type de service de premier plan à déclarer dans le fichier manifeste sous
android:foregroundServiceType
shortService
Autorisation à déclarer dans votre fichier manifeste
Aucune
Constante à transmettre à startForeground()
FOREGROUND_SERVICE_TYPE_SHORT_SERVICE
Conditions préalables d'exécution
Aucune
Description

Finalisez rapidement les tâches essentielles qui ne peuvent pas être interrompues ni reportées.

Ce type présente des caractéristiques uniques :

  • Il ne peut être exécuté que sur une courte période (environ trois minutes).
  • Il est incompatible avec les services de premier plan persistants.
  • Il ne peut démarrer d'autres services de premier plan.
  • Il ne nécessite pas d'autorisation spécifique à un type, bien que l'autorisation FOREGROUND_SERVICE reste nécessaire.
  • Un shortService ne peut passer à un autre type de service que si l'application est actuellement éligible au démarrage d'un nouveau service de premier plan.
  • Un service de premier plan peut modifier son type en shortService à tout moment, à partir de quoi le délai avant expiration commence.

Le délai d'inactivité pour shortService commence à partir du moment où Service.startForeground() est appelé. L'application doit appeler Service.stopSelf() ou Service.stopForeground() avant l'expiration du délai. Sinon, le nouveau Service.onTimeout() est appelé, ce qui permet aux applications d'appeler brièvement stopSelf() ou stopForeground() pour arrêter leur service.

Peu après l'appel de Service.onTimeout(), l'application passe dans un état mis en cache et n'est plus considérée comme étant de premier plan, sauf si l'utilisateur interagit activement avec elle. Peu de temps après la mise en cache de l'application et l'arrêt du service, celle-ci reçoit une erreur ANR. Le message ANR mentionne FOREGROUND_SERVICE_TYPE_SHORT_SERVICE. Pour ces raisons, il est recommandé d'implémenter le rappel Service.onTimeout().

Le rappel Service.onTimeout() n'existe pas sur Android 13 ou version antérieure. Si le même service s'exécute sur ces appareils, il ne reçoit pas de délai d'inactivité ni d'erreur ANR. Assurez-vous que votre service s'arrête dès la fin de la tâche de traitement, même s'il n'a pas encore reçu le rappel Service.onTimeout().

Notez que si le délai d'expiration de shortService n'est pas respecté, l'application sera ANR, même si d'autres services de premier plan valides ou d'autres processus de cycle de vie de l'application sont en cours d'exécution.

Si une application est visible par l'utilisateur ou qu'elle satisfait l'une des exceptions permettant de démarrer les services de premier plan en arrière-plan, appeler à nouveau Service.StartForeground() avec le paramètre FOREGROUND_SERVICE_TYPE_SHORT_SERVICE prolonge le délai avant expiration de trois minutes. Si l'application n'est pas visible par l'utilisateur et qu'elle ne satisfait pas l'une des exceptions, toute tentative de démarrage d'un autre service de premier plan, quel que soit son type, entraîne une ForegroundServiceStartNotAllowedException

Si un utilisateur désactive l'optimisation de la batterie pour votre application, cette dernière sera toujours affectée par le délai d'inactivité du shortService du service de premier plan.

Si vous démarrez un service de premier plan qui inclut le type shortService et un autre type de service de premier plan, le système ignore la déclaration du type shortService. Toutefois, le service doit toujours respecter les conditions préalables des autres types déclarés. Pour en savoir plus, consultez la documentation sur les services de premier plan.

Utilisation spéciale

Foreground service type to declare in manifest under
android:foregroundServiceType
specialUse
Permission to declare in your manifest
FOREGROUND_SERVICE_SPECIAL_USE
Constant to pass to startForeground()
FOREGROUND_SERVICE_TYPE_SPECIAL_USE
Runtime prerequisites
None
Description

Covers any valid foreground service use cases that aren't covered by the other foreground service types.

In addition to declaring the FOREGROUND_SERVICE_TYPE_SPECIAL_USE foreground service type, developers should declare use cases in the manifest. To do so, they specify the <property> element within the <service> element. These values and corresponding use cases are reviewed when you submit your app in the Google Play Console. The use cases you provide are free-form, and you should make sure to provide enough information to let the reviewer see why you need to use the specialUse type.

<service android:name="fooService" android:foregroundServiceType="specialUse">
  <property android:name="android.app.PROPERTY_SPECIAL_USE_FGS_SUBTYPE"
      android:value="explanation_for_special_use"/>
</service>

Système exempté

Type de service de premier plan à déclarer dans le fichier manifeste sous
android:foregroundServiceType
systemExempted
Autorisation à déclarer dans votre fichier manifeste
FOREGROUND_SERVICE_SYSTEM_EXEMPTED
Constante à transmettre à startForeground()
FOREGROUND_SERVICE_TYPE_SYSTEM_EXEMPTED
Conditions préalables d'exécution
Aucune
Description

Réservé pour les applications système et les intégrations système spécifiques, afin de continuer à utiliser les services de premier plan.

Pour utiliser ce type, une application doit correspondre à au moins un des critères suivants :

  • L'appareil est en mode démo
  • L'application est un Device Owner
  • L'application est un Profiler Owner
  • Les applications de sécurité ayant le rôle ROLE_EMERGENCY
  • Les applications Device Admin
  • Applications disposant de l'autorisation SCHEDULE_EXACT_ALARM ou USE_EXACT_ALARM et qui utilisent le service de premier plan pour continuer les alarmes en arrière-plan, y compris les alarmes haptiques uniquement.

  • Applications VPN (configurées via Paramètres > Réseau et Internet > VPN)

    Autrement, le fait de déclarer ce type renvoie une exception ForegroundServiceTypeNotAllowedException.

Application des règles Google Play pour l'utilisation des types de services de premier plan

If your app targets Android 14 or higher, you'll need to declare your app's foreground service types in the Play Console's app content page (Policy > App content). For more information on how to declare your foreground service types in Play Console, see Understanding foreground service and full-screen intent requirements.