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

Cette page aborde certaines 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 sont utilisés de manière incorrecte, les services de premier plan peuvent avoir des effets négatifs sur les performances et l'autonomie de la batterie de l'appareil. C'est pourquoi les versions de la plate-forme Android modifient souvent le comportement des services de premier plan pour 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 changements récents pourraient expliquer vos problèmes. Il est particulièrement important de vérifier les modifications dans les cas suivants :

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

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

Erreurs ANR (Application Not Responding)

Dans certaines circonstances, 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 et provoque une erreur ANR

Les services de premier plan qui utilisent le type shortService doivent se terminer rapidement, en trois minutes environ. Lorsque le délai expire, 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".

Diagnostic :

Si l'ANR est dû à un service de premier plan qui n'a pas réussi à s'arrêter, le système génère une exception interne. Pour vérifier qu'il s'agit bien du problème, consultez les rapports ANR. Si tel est le cas, le rapport inclura 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 à durée limitée 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 stopSelf() immédiatement.

Exceptions pour les services de premier plan

Cette section décrit plusieurs problèmes liés aux services de premier plan qui peuvent entraîner une exception du système. Si l'application n'intercepte pas l'exception, l'utilisateur voit une boîte de dialogue lui indiquant 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 d'attente 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 multimédia 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 lui-même, le système génère un RemoteServiceException interne qui provoque le plantage de l'application.

Diagnostic :

Pour connaître l'exception, consultez la trace de la pile. Vous pouvez également 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 à durée limitée 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 stopSelf() immédiatement.

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 un ForegroundServiceDidNotStartInTimeException interne.

Diagnostic :

Pour connaître l'exception, consultez la trace de la pile. Vous pouvez également 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() dans les secondes qui suivent.

ForegroundServiceStartNotAllowedException

Erreur :

Le système renvoie ForegroundServiceStartNotAllowedException.

Cause :

Cela est généralement dû au fait que l'application lance un service de premier plan en arrière-plan sans exemption valide.

À 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, avec quelques exceptions spécifiques. 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 d'une des exemptions, le système génère ForegroundServiceStartNotAllowedException. Le système le fait également si vous ne remplissez pas les conditions d'exemption.

Par exemple, une application peut comporter un bouton sur lequel un utilisateur peut cliquer, ce qui entraîne un traitement par l'application, puis le lancement d'un service de premier plan. Dans ce cas, l'utilisateur peut cliquer sur le bouton, puis mettre immédiatement l'application en arrière-plan. L'application essaie ensuite de lancer le service en arrière-plan. Si l'application ne répond pas à l'une des exemptions 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 haute priorité. Si vous ne lancez pas le service assez rapidement, vous recevrez une ForegroundServiceStartNotAllowedException.

Il arrive que des exemptions spécifiques deviennent 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 répond toujours à l'une des exemptions autorisées.

Solution :

Modifiez le workflow de votre application pour 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 répond à l'une des exceptions.

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

SecurityException

Erreur :

Le système génèreSecurityException.

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 répondre à tous les prérequis de son type de service de premier plan. Ces prérequis sont détaillés dans la documentation sur les types de services au 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 d'utilisation supplémentaires s'appliquent aux autorisations requises par certains types de services de premier plan. Ces autorisations ne sont accordées à l'application que lorsqu'elle est 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érera une SecurityException, même si l'application est exemptée de l'obligation de 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 en cours.
    • Vous pouvez obtenir un SecurityException si vous avez demandé les autorisations nécessaires, mais que vous avez démarré 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 avez rempli toutes les autres conditions préalables d'exécution.