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

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

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

Le système vérifie que les types de services de premier plan sont utilisés correctement et confirme que l'application a demandé les autorisations d'exécution appropriées ou qu'elle utilise les API requises. Par exemple, le système s'attend à ce que les applications qui utilisent le type de service FOREGROUND_SERVICE_TYPE_LOCATION de premier plan demandent ACCESS_COARSE_LOCATION ou ACCESS_FINE_LOCATION.

Par conséquent, les applications doivent suivre un ordre d'opérations très spécifique lorsqu'elles demandent des autorisations à l'utilisateur et démarrent des services de premier plan. Les autorisations doivent être demandées et accordées avant que l'application ne tente d'appeler startForeground(). Les applications qui demandent les autorisations appropriées après le démarrage du service de premier plan doivent modifier cet ordre des opérations et demander l'autorisation avant de démarrer le service de premier plan.

Les spécificités des mesures d'application de la plate-forme apparaissent dans les sections intitulées "Conditions d'exécution" de la section Cas d'utilisation prévus et mesures d'application pour chaque type de service de premier plan sur cette page.

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

In order to use a given foreground service type, you must declare a particular permission in your manifest file, you must fulfill specific runtime requirements, and your app must fulfill one of the intended sets of use cases for that type. The following sections explain the permission that you must declare, the runtime prerequisites, and the intended use cases for each type.

Caméra

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é

要在清单中的以下位置声明的前台服务类型
android:foregroundServiceType
connectedDevice
在清单中声明的权限
FOREGROUND_SERVICE_CONNECTED_DEVICE
要传递给 startForeground() 的常量
FOREGROUND_SERVICE_TYPE_CONNECTED_DEVICE
运行时前提条件

必须至少满足以下其中一个条件：

说明

与需要蓝牙、NFC、IR、USB 或网络连接的外部设备进行互动。

替代方案

如果您的应用需要向外部设备持续传输数据，请考虑改用配套设备管理器。使用配套设备感知 API，可帮助您的应用在配套设备在范围内时保持运行。

如果您的应用需要扫描蓝牙设备，请考虑改用 Bluetooth Scan API。

Synchroniser les données

Type de service de premier plan à déclarer dans le fichier manifeste sous
android:foregroundServiceType
dataSync
Autorisation à déclarer dans votre fichier manifeste
FOREGROUND_SERVICE_DATA_SYNC
Constante à transmettre à startForeground()
FOREGROUND_SERVICE_TYPE_DATA_SYNC
Conditions préalables 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 la section Alternatives aux services de premier plan de synchronisation des données.

Santé

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

Vous devez remplir l'une des conditions suivantes :

Remarque:Les autorisations d'exécution READ basées sur les capteurs et BODY_SENSORS sont soumises à des restrictions d'utilisation. Pour cette raison, vous ne pouvez pas créer de service de premier plan health qui utilise des capteurs corporels lorsque votre application est en arrière-plan, sauf si vous avez reçu les autorisations BODY_SENSORS_BACKGROUND (niveau d'API 33 à 35) ou READ_HEALTH_DATA_IN_BACKGROUND (niveau d'API 36 et versions ultérieures). 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

Tous les cas d'utilisation de longue durée pour prendre en charge les applications de la catégorie "Remise en forme", tels que les coachs électroniques d'entraînement.

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 d'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éder à 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 en arrière-plan, sauf si vous avez reçu l'autorisation d'exécution ACCESS_BACKGROUND_LOCATION. 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

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 atteint des emplacements spécifiques, envisagez plutôt d'utiliser l'API Geofence.

Contenus multimédias

Type de service de premier plan à déclarer dans le fichier manifeste sous
android:foregroundServiceType
mediaPlayback
Autorisation à déclarer dans votre fichier manifeste
FOREGROUND_SERVICE_MEDIA_PLAYBACK
Constante à transmettre à startForeground()
FOREGROUND_SERVICE_TYPE_MEDIA_PLAYBACK
Conditions préalables d'exécution
Aucune
Description
Continuez la lecture audio ou vidéo en arrière-plan. Prend en charge la fonctionnalité d'enregistrement vidéo numérique (DVR) sur Android TV.
Autres solutions
Si vous diffusez une vidéo en mode Picture-in-picture, utilisez le mode Picture-in-picture.

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

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

Demandez l'autorisation d'exécution RECORD_AUDIO et obtenez-la.

Remarque:L'autorisation d'exécution RECORD_AUDIO est soumise à des restrictions d'utilisation. Pour cette raison, vous ne pouvez pas créer de service de premier plan microphone 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 à utiliser le micro en arrière-plan, par exemple pour un enregistreur vocal ou une application de communication.

Appel téléphonique

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

Vous devez remplir l'une des conditions suivantes:

  • L'application a déclaré l'autorisation MANAGE_OWN_CALLS dans son fichier manifeste.
  • L'application est l'application de téléphone par défaut via le rôle ROLE_DIALER.
Description

Poursuivez 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.

Envisagez d'utiliser CallScreeningService pour filtrer les appels.

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

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

Recouvre les cas d'utilisation de services de premier plan valides qui ne sont pas couverts par les autres types de services de premier plan.

En plus de déclarer le type de service de premier plan FOREGROUND_SERVICE_TYPE_SPECIAL_USE, les développeurs doivent déclarer les cas d'utilisation dans le fichier manifeste. Pour ce faire, ils doivent spécifier l'élément <property> dans l'élément <service>. Ces valeurs et les cas d'utilisation correspondants sont examinés lorsque vous envoyez votre application dans la Google Play Console. Les cas d'utilisation que vous fournissez sont libres et vous devez vous assurer de fournir suffisamment d'informations pour permettre à l'examinateur de voir pourquoi vous devez utiliser le type specialUse.

<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é

要在清单中的以下位置声明的前台服务类型
android:foregroundServiceType
systemExempted
在清单中声明的权限
FOREGROUND_SERVICE_SYSTEM_EXEMPTED
要传递给 startForeground() 的常量
FOREGROUND_SERVICE_TYPE_SYSTEM_EXEMPTED
运行时前提条件
无
说明

为系统应用和特定系统集成预留，使其能继续使用前台服务。

如需使用此类型，应用必须至少满足以下条件之一：

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

如果您的应用以 Android 14 或更高版本为目标平台，您需要在 Play 管理中心的“应用内容”页面（政策 > 应用内容）中声明应用的前台服务类型。如需详细了解如何在 Play 管理中心内声明前台服务类型，请参阅了解前台服务和全屏 intent 要求。