Types de services de premier plan

À partir d'Android 14 (niveau d'API 34), vous devez déclarer un type de service approprié pour chaque service de premier plan. Cela signifie que vous devez déclarer le type de service dans le fichier manifeste de votre application, et demander également l'autorisation de service de premier plan appropriée pour ce type (en plus de demander l'autorisation FOREGROUND_SERVICE). En outre, selon le type de service de premier plan, vous devrez peut-être demander des autorisations d'exécution avant de lancer le service.

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 pour l'environnement d'exécution

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

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 de déclarer dans votre fichier manifeste
FOREGROUND_SERVICE_CONNECTED_DEVICE
Constante à transmettre à startForeground()
FOREGROUND_SERVICE_TYPE_CONNECTED_DEVICE
Conditions requises pour l'environnement 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 plutôt d'utiliser le gestionnaire d'appareils associés. Utilisez l'API de présence d'appareil associé pour permettre à votre application de rester exécutée lorsque l'appareil associé est à portée.

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

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 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 la section Alternatives aux services de premier plan de synchronisation des données.

Santé

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

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

说明

为健身类别的应用（例如锻炼追踪器）提供支持的所有长时间运行的用例。

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:

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 pour l'environnement d'exécution
Aucune
Description

Permet de poursuivre 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.

Traitement multimédia

要在其清单中声明的前台服务类型
android:foregroundServiceType
mediaProcessing
在清单中声明的权限
FOREGROUND_SERVICE_MEDIA_PROCESSING
要传递给 startForeground() 的常量
FOREGROUND_SERVICE_TYPE_MEDIA_PROCESSING
运行时前提条件
无
说明

用于对媒体资源执行耗时操作的服务，例如将媒体转换为不同格式。系统允许此服务有有限的运行时间；在正常情况下，此时间限制为每 24 小时 6 小时。（此限制由应用的所有 mediaProcessing 前台服务共享。）

您的应用应在以下情况下手动停止媒体处理服务：

如果达到超时期限，系统会调用服务的 Service.onTimeout(int, int) 方法。此时，服务有几秒钟时间来调用 Service.stopSelf()。如果服务未调用 Service.stopSelf()，将发生 ANR，并显示以下错误消息：“<fgs_type> 的前台服务未在其超时内停止：<component_name>”。

注意：Service.onTimeout(int, int) 不适用于 Android 14 或更低版本。在运行这些版本的设备上，如果媒体处理服务达到超时期限，系统会立即缓存应用。因此，您的应用不应等待收到超时通知。而是应尽快终止前台服务或将其更改为后台服务。

Projection multimédia

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

在启动前台服务之前调用 createScreenCaptureIntent() 方法。这样做会向用户显示权限通知；用户必须先授予权限，您才能创建服务。

创建前台服务后，您可以调用 MediaProjectionManager.getMediaProjection()。

说明

使用 MediaProjection API 将内容投影到非主要显示屏或外部设备。这些内容不必全都为媒体内容。

替代方案

如需将媒体流式传输到其他设备，请使用 Google Cast SDK。

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 pour l'environnement d'exécution

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

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 pour l'environnement 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 de déclarer dans votre fichier manifeste
FOREGROUND_SERVICE_REMOTE_MESSAGING
Constante à transmettre à startForeground()
FOREGROUND_SERVICE_TYPE_REMOTE_MESSAGING
Conditions requises pour l'environnement 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 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 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 à l'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. L'utilisation des demandes que vous fournissez sont libres. Assurez-vous d'en fournir suffisamment des informations pour permettre à l'examinateur de savoir pourquoi vous devez utiliser l'specialUse de mots clés.

<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 ou USE_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 "Contenu de l'application" de la Play Console (Règles > Contenu de l'application). Pour en savoir plus sur la déclaration de vos types de services de premier plan dans la Play Console, consultez Comprendre les exigences liées aux services de premier plan et à l'intent plein écran.