Résoudre les problèmes liés aux services de premier plan

Cette page présente quelques raisons courantes pour lesquelles les services de premier plan peuvent échouer et vous aide à identifier la cause du problème.

Ce document traite des problèmes suivants :

Avant de procéder au dépannage

Vérifier les modifications récentes apportées aux services de premier plan

S'ils ne sont pas utilisés correctement, les services de premier plan peuvent avoir des effets négatifs sur les performances de l'appareil et l'autonomie de la batterie. C'est pourquoi les versions de la plate-forme Android modifient souvent le comportement des services de premier plan afin de limiter ces effets négatifs.

Si vous rencontrez des problèmes avec les services de premier plan, consultez la documentation sur les modifications apportées aux services de premier plan pour voir si des modifications récentes pourraient expliquer vos problèmes. Il est particulièrement important de vérifier les modifications dans les cas suivants :

  • Le code du service de premier plan qui fonctionnait auparavant échoue désormais
  • Vous venez de commencer à tester une nouvelle version de la plate-forme ou vous avez modifié le niveau d'API ciblé par votre application.

De plus, si vous testez votre appareil sur une preview développeur de la plate-forme, veillez à consulter la version la plus récente de la documentation de la preview développeur.

Erreurs ANR (L'application ne répond pas)

Dans certains cas, une application doit arrêter son service de premier plan. Si l'application n'arrête pas le service, le système l'arrête et déclenche une erreur L'application ne répond pas (ANR).

Un service court s'exécute trop longtemps, ce qui entraîne une erreur ANR

Les services de premier plan qui utilisent le type service court doivent se terminer rapidement, en trois minutes environ. Une fois le délai écoulé, le système appelle la méthode Service.onTimeout(int,int) du service. Le service dispose de quelques secondes pour appeler stopSelf(). Si le service ne s'arrête pas de lui-même, le système déclenche une erreur "L'application ne répond pas".

Diagnostiquer :

Si l'ANR a été causé par un service de premier plan qui n'a pas pu s'arrêter, le système génère une exception interne. Vous pouvez vérifier si c'est le cas en consultant les rapports ANR. Si tel est le cas, le rapport inclut le message suivant :

Fatal Exception: android.app.RemoteServiceException: "A foreground service of
type FOREGROUND_SERVICE_TYPE_SHORT_SERVICE did not stop within its timeout:
[component name]"

Solution :

Assurez-vous que tous les services de premier plan limités dans le temps terminent leur travail et appellent stopForeground(int) dans le délai imparti par le système.

Faites en sorte que vos services de premier plan implémentent Service.onTimeout(int,int). Assurez-vous que votre implémentation de cette méthode appelle immédiatement stopSelf().

Exceptions pour les services de premier plan

Cette section décrit plusieurs problèmes liés aux services de premier plan qui peuvent amener le système à générer une exception. Si l'application ne détecte pas l'exception, l'utilisateur voit une boîte de dialogue l'informant que l'application s'est arrêtée.

Dans certains cas, le système génère une exception interne. Dans ce cas, vous pouvez identifier l'exception en examinant la trace de la pile et consulter Logcat pour obtenir des informations plus détaillées sur l'erreur.

Exception interne : délai avant expiration dépassé

Le système impose une limite à la durée d'exécution des services de premier plan de synchronisation des données et de traitement des contenus multimédias lorsque l'application est en arrière-plan. Si le service dépasse cette limite, le système appelle la méthode Service.onTimeout(int,int) du service. Le service dispose de quelques secondes pour appeler stopSelf(). Si le service ne s'arrête pas de lui-même, le système génère une exception RemoteServiceException interne, ce qui entraîne le plantage de l'application.

Diagnostiquer :

Vous pouvez identifier l'exception en examinant la trace de la pile et consulter Logcat pour obtenir des informations plus détaillées sur l'erreur. Dans ce cas, Logcat affiche le message d'erreur suivant :

Fatal Exception: android.app.RemoteServiceException: "A foreground service of
type [service type] did not stop within its timeout: [component name]"

Solution :

Assurez-vous que tous les services de premier plan limités dans le temps terminent leur travail et appellent stopForeground(int) dans le délai imparti par le système.

Faites en sorte que vos services de premier plan implémentent Service.onTimeout(int,int). Assurez-vous que votre implémentation de cette méthode appelle immédiatement stopSelf().

Exception interne : ForegroundServiceDidNotStartInTimeException

Lorsque vous lancez un service en appelant context.startForegroundService(), ce service dispose de quelques secondes pour se promouvoir en tant que service de premier plan en appelant ServiceCompat.startForeground(). Si le service ne le fait pas, il génère une erreur ForegroundServiceDidNotStartInTimeException interne.

Diagnostiquer :

Vous pouvez identifier l'exception en examinant la trace de la pile et consulter Logcat pour obtenir des informations plus détaillées sur l'erreur. Dans ce cas, Logcat affiche le message d'erreur suivant :

android.app.RemoteServiceException$ForegroundServiceDidNotStartInTimeException:
Context.startForegroundService() did not then call Service.startForeground()

Solution :

Assurez-vous que tous les services de premier plan nouvellement créés appellent ServiceCompat.startForeground() en quelques secondes.

WorkManager :

Vous pouvez également voir cette exception avec les nœuds de calcul WorkManager qui exécutent un service de premier plan (appelez setForegound ou setForegroundAsync). Lorsque le cycle de vie de deux nœuds de calcul de premier plan se chevauche, car un nœuil de calcul tente de démarrer un service de premier plan alors qu'un service de premier plan précédemment en cours d'exécution tente de s'arrêter, ce plantage est accompagné du journal suivant :

Re-initializing SystemForegroundService after a request to shut-down

Ce plantage a été corrigé dans la version 2.10.5 de WorkManager.

Si votre application rencontre cette exception, passez à la version la plus récente de WorkManager et signalez tout problème persistant dans l'outil de suivi des problèmes de WorkManager.

ForegroundServiceStartNotAllowedException

Erreur :

Le système génère une erreur ForegroundServiceStartNotAllowedException.

Cause :

Cela est généralement dû au fait que l'application lance un service de premier plan depuis l'arrière-plan alors qu'aucune exception valide n'est applicable.

À partir d'Android 12 (niveau d'API 31), les applications ne sont pas autorisées à démarrer des services de premier plan lorsqu'elles s'exécutent en arrière-plan, à quelques exceptions près. Si vous tentez de démarrer un service de premier plan à partir de l'arrière-plan et que vous ne remplissez pas les conditions de l'une des exceptions, le système génère ForegroundServiceStartNotAllowedException. Le système effectue également cette opération si vous ne remplissez pas les conditions de l'exemption.

Par exemple, une application peut comporter un bouton sur lequel l'utilisateur peut cliquer, ce qui entraîne un traitement, puis le lancement d'un service de premier plan. Dans ce cas, l'utilisateur risque de cliquer sur le bouton, puis de mettre immédiatement l'application en arrière-plan. L'application essaierait alors de lancer le service en arrière-plan. Si l'application ne remplit pas l'une des conditions d'exemption spécifiées, le système génère une exception ForegroundServiceStartNotAllowedException.

De plus, certaines exemptions ont une durée limitée. Par exemple, une brève exemption est accordée si votre application lance un service de premier plan en réponse à un message FCM de priorité élevée. Si vous ne lancez pas le service assez rapidement, vous obtiendrez une erreur ForegroundServiceStartNotAllowedException.

Les exemptions spécifiques deviennent parfois plus restrictives avec les nouvelles versions d'Android. Si vous avez modifié la version d'Android ciblée par votre application, consultez la documentation sur les modifications apportées aux services de premier plan et vérifiez que votre application remplit toujours l'une des conditions d'exemption autorisées.

Solution :

Modifiez le workflow de votre application afin qu'elle n'ait pas besoin de lancer des services de premier plan lorsqu'elle est en arrière-plan, ou vérifiez qu'elle remplit l'une des conditions d'exemption.

Vous pouvez utiliser des composants qui tiennent compte du cycle de vie pour gérer le cycle de vie de votre application afin de ne pas essayer de lancer par inadvertance un service de premier plan depuis l'arrière-plan.

SecurityException

Erreur :

Le système génère SecurityException.

Cause :

Votre application a tenté de lancer un service de premier plan sans disposer des autorisations nécessaires.

  • Si une application cible Android 9 (niveau d'API 28) ou une version ultérieure, elle doit disposer de l'autorisation FOREGROUND_SERVICE pour lancer un service de premier plan.
  • Si une application cible Android 14 (niveau d'API 34) ou version ultérieure, elle doit remplir toutes les conditions préalables pour son type de service de premier plan. Ces conditions préalables sont détaillées dans la documentation sur les types de services de premier plan. En particulier, tenez compte des exigences suivantes :
    • Plusieurs types de services de premier plan nécessitent des autorisations d'exécution spécifiques. Par exemple, un service de premier plan de messagerie à distance doit disposer de l'autorisation FOREGROUND_SERVICE_REMOTE_MESSAGING.
  • Dans plusieurs cas, des restrictions supplémentaires s'appliquent aux autorisations requises par certains types de services de premier plan lorsqu'ils sont utilisés. Ces autorisations ne sont accordées à l'application que lorsqu'elle est exécutée au premier plan (à quelques exceptions près). Cela signifie que même si votre application a demandé et obtenu l'une de ces autorisations, si elle tente de lancer le service de premier plan alors qu'elle est en arrière-plan, le système génère une SecurityException, même si l'application bénéficie d'une exemption pour démarrer un service de premier plan depuis l'arrière-plan. Pour en savoir plus, consultez Restrictions concernant le démarrage des services de premier plan nécessitant des autorisations d'utilisation "Pendant l'utilisation".
    • Vous pouvez obtenir une SecurityException si vous avez demandé les autorisations nécessaires, mais que vous démarrez le service de premier plan avant de confirmer que les autorisations requises ont été accordées.

Solution :

Avant de lancer le service de premier plan, demandez toutes les autorisations de service de premier plan appropriées et vérifiez que vous remplissez toutes les autres conditions préalables d'exécution.