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 :
camera
connectedDevice
dataSync
health
location
mediaPlayback
mediaProjection
microphone
phoneCall
remoteMessaging
shortService
specialUse
systemExempted
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
Si les applications qui ciblent Android 14 utilisent un service de premier plan, elles doivent déclarer une autorisation spécifique, basée sur le type de service de premier plan, introduite par Android 14. Ces autorisations apparaissent dans les sections intitulées "Autorisation que vous devez déclarer dans votre fichier manifeste" de la section Cas d'utilisation prévus et mesures d'application pour chaque type de service de premier plan sur cette page.
Toutes les autorisations sont définies comme des autorisations normales et sont accordées par défaut. Les utilisateurs ne peuvent pas les révoquer.
Inclure le type de service de premier plan lors de l'exécution
Pour les applications qui lancent des services de premier plan, il est recommandé d'utiliser la version ServiceCompat
de startForeground()
(disponible dans androidx-core 1.12 ou version ultérieure) dans laquelle vous transmettez un entier bit à bit de types de services 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 de la plate-forme 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 une erreur MissingForegroundServiceTypeException
.
Si le service de premier plan nécessite 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 d'informations location
, mais qui peut nécessiter ou non les autorisations media
. Vous devez déclarer location
et mediaPlayback
dans le fichier manifeste. Si un utilisateur lance une course à pied 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 du contenu audio, appelez de 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 l'autorisation que vous devez déclarer, les conditions préalables à l'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 de déclarer dans votre fichier manifeste
FOREGROUND_SERVICE_CAMERA
- Constante à transmettre à
startForeground()
FOREGROUND_SERVICE_TYPE_CAMERA
- Conditions requises pour l'environnement d'exécution
Demander et obtenir l'autorisation d'exécution
CAMERA
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 plancamera
lorsque votre application est en arrière-plan, à quelques exceptions près. Pour en savoir plus, consultez la section Restrictions au démarrage de services de premier plan nécessitant des autorisations en cours d'utilisation.- Description
continuer à accéder à la caméra en arrière-plan (applications de chat vidéo permettant le multitâche, par exemple).
Appareil connecté
- Foreground service type to declare in manifest under
android:foregroundServiceType
connectedDevice
- Permission to declare in your manifest
FOREGROUND_SERVICE_CONNECTED_DEVICE
- Constant to pass to
startForeground()
FOREGROUND_SERVICE_TYPE_CONNECTED_DEVICE
- Runtime prerequisites
At least one of the following conditions must be true:
Declare at least one of the following permissions in your manifest:
Request and be granted at least one of the following runtime permissions:
- Description
Interactions with external devices that require a Bluetooth, NFC, IR, USB, or network connection.
- Alternatives
If your app needs to do continuous data transfer to an external device, consider using the companion device manager instead. Use the companion device presence API to help your app stay running while the companion device is in range.
If your app needs to scan for bluetooth devices, consider using the Bluetooth scan API instead.
Synchroniser les données
- Type de service de premier plan à déclarer dans le fichier manifeste sous
android:foregroundServiceType
dataSync
- Autorisation de déclarer dans votre fichier manifeste
FOREGROUND_SERVICE_DATA_SYNC
- Constante à transmettre à
startForeground()
FOREGROUND_SERVICE_TYPE_DATA_SYNC
- Conditions requises pour l'environnement d'exécution
- Aucune
- Description
Opérations de transfert de données, telles que :
- Importation ou téléchargement de données
- Opérations de sauvegarde et restauration
- Opérations d'importation ou d'exportation
- Extraction de données
- Traitement des fichiers en local
- Transfert de données d'un appareil vers le cloud via un réseau
- Autres solutions
Pour en savoir plus, consultez Alternatives aux services de premier plan de synchronisation de données.
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:
Declare the
HIGH_SAMPLING_RATE_SENSORS
permission in your manifest.Request and be granted at least one of the following runtime permissions:
Note: The
BODY_SENSORS
runtime permission is subject to while-in-use restrictions. For this reason, you cannot create ahealth
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
- Type de service de premier plan à déclarer dans le fichier manifeste sous
android:foregroundServiceType
location
- Autorisation à déclarer dans votre fichier manifeste
FOREGROUND_SERVICE_LOCATION
- Constante à transmettre à
startForeground()
FOREGROUND_SERVICE_TYPE_LOCATION
- Conditions préalables à l'exécution
L'utilisateur doit avoir activé les services de localisation, et l'application doit disposer d'au moins l'une des autorisations d'exécution suivantes:
Remarque:Pour vérifier que l'utilisateur a activé les services de localisation et accordé l'accès aux autorisations d'exécution, utilisez
PermissionChecker#checkSelfPermission()
.Remarque:Les autorisations d'exécution d'accès à la position sont soumises à des restrictions d'utilisation. Pour cette raison, vous ne pouvez pas créer de service de premier plan
location
lorsque votre application est exécutée en arrière-plan, sauf si vous disposez de l'autorisation d'exécutionACCESS_BACKGROUND_LOCATION
. Pour en savoir plus, consultez la section Restrictions concernant le démarrage de services de premier plan qui nécessitent des autorisations en cours d'utilisation.- Description
Cas d'utilisation de longue durée nécessitant un accès à la position, tels que la navigation et le partage de position.
- Autres solutions
Si votre application doit être déclenchée lorsque l'utilisateur accède à des emplacements spécifiques, envisagez plutôt d'utiliser l'API Géoreence.
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 de déclarer dans votre fichier manifeste
FOREGROUND_SERVICE_MEDIA_PROJECTION
- Constante à transmettre à
startForeground()
FOREGROUND_SERVICE_TYPE_MEDIA_PROJECTION
- Conditions requises pour l'environnement d'exécution
Appelez la méthode
createScreenCaptureIntent()
avant de démarrer le service de premier plan. Une notification d'autorisation s'affiche. Celui-ci doit accorder l'autorisation pour que vous puissiez créer le service.Après avoir créé le service de premier plan, 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 du contenu multimédia 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 amicrophone
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
- Type de service de premier plan à déclarer dans le fichier manifeste sous
android:foregroundServiceType
phoneCall
- Autorisation de déclarer dans votre fichier manifeste
FOREGROUND_SERVICE_PHONE_CALL
- Constante à transmettre à
startForeground()
FOREGROUND_SERVICE_TYPE_PHONE_CALL
- Conditions requises pour l'environnement d'exécution
Vous devez remplir au moins l'une des conditions suivantes:
- L'application a déclaré l'autorisation
MANAGE_OWN_CALLS
dans son fichier manifeste.
- L'application a déclaré l'autorisation
- Il s'agit de l'application de téléphonie par défaut via le rôle
ROLE_DIALER
.
- Il s'agit de l'application de téléphonie par défaut via le rôle
- Description
Continuez un appel en cours à l'aide des API
ConnectionService
.- Autres solutions
Si vous devez passer des appels téléphoniques, vidéo ou VoIP, envisagez d'utiliser la bibliothèque
android.telecom
.Pensez à utiliser
CallScreeningService
pour filtrer les appels.
Messagerie à distance
- Foreground service type to declare in manifest under
android:foregroundServiceType
remoteMessaging
- Permission to declare in your manifest
FOREGROUND_SERVICE_REMOTE_MESSAGING
- Constant to pass to
startForeground()
FOREGROUND_SERVICE_TYPE_REMOTE_MESSAGING
- Runtime prerequisites
- None
- Description
- Transfer text messages from one device to another. Assists with continuity of a user's messaging tasks when they switch devices.
Service court
- Type de service de premier plan à déclarer dans le fichier manifeste sous
android:foregroundServiceType
shortService
- Autorisation de déclarer dans votre fichier manifeste
- Aucune
- Constante à transmettre à
startForeground()
FOREGROUND_SERVICE_TYPE_SHORT_SERVICE
- Conditions requises pour l'environnement 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 à démarrer un nouveau service de premier plan. - Un service de premier plan peut changer son type en
shortService
à tout moment. Le délai avant expiration commence alors.
Le délai d'inactivité pour shortService commence à partir du moment où
Service.startForeground()
est appelé. L'application doit appelerService.stopSelf()
ouService.stopForeground()
avant l'expiration du délai. Sinon, le nouveauService.onTimeout()
est appelé, ce qui permet aux applications d'appeler brièvementstopSelf()
oustopForeground()
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 mentionneFOREGROUND_SERVICE_TYPE_SHORT_SERVICE
. Pour ces raisons, il est recommandé d'implémenter le rappelService.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 rappelService.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ètreFOREGROUND_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 uneForegroundServiceStartNotAllowedException
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 typeshortService
. 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 thespecialUse
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 de déclarer dans votre fichier manifeste
FOREGROUND_SERVICE_SYSTEM_EXEMPTED
- Constante à transmettre à
startForeground()
FOREGROUND_SERVICE_TYPE_SYSTEM_EXEMPTED
- Conditions requises pour l'environnement 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
ouUSE_EXACT_ALARM
Applications VPN (configurées sous 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
Si votre application cible Android 14 ou une version ultérieure, vous devez déclarer les types de services de premier plan de votre application sur la page du contenu de l'application dans la Play Console (Règles > Contenu de l'application). Pour savoir comment déclarer vos types de services de premier plan dans la Play Console, consultez la page Comprendre les exigences concernant les services de premier plan et l'intent plein écran.