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 aborde les problèmes suivants :

Avant de procéder au dépannage

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

Si les services de premier plan sont utilisés de manière inappropriée, ils 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 apportent souvent des modifications au 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 et vérifiez 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 de service de premier plan qui fonctionnait auparavant échoue désormais
  • Vous venez de commencer les tests sur 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 version preview pour les développeurs de la plate-forme, assurez-vous de consulter la version la plus récente de la documentation sur la version preview pour les développeurs.

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

Dans certaines circonstances, une application est censée 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 de service court doivent se terminer rapidement, en trois minutes environ. Lorsque le délai est é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, le système déclenche une erreur "L'application ne répond pas".

Diagnostiquer :

Si l'erreur ANR est due à un service de premier plan qui n'a pas réussi à s'arrêter, le système génère une exception interne. Vous pouvez vérifier que c'est le cas en consultant les rapports ANR. Si tel est le problème, 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.

Demandez à vos services de premier plan d'implémenter Service.onTimeout(int,int). Assurez-vous que votre implémentation de cette méthode appelle stopSelf() immédiatement.

Exceptions de service de premier plan

Cette section décrit plusieurs problèmes de service 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 déterminer 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 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, le système génère une RemoteServiceException interne qui provoque le plantage de l'application.

Diagnostiquer :

Vous pouvez déterminer 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 à durée limitée terminent leur travail et appellent stopForeground(int) dans le délai imparti par le système.

Demandez à vos services de premier plan d'implémenter 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 service de premier plan en appelant ServiceCompat.startForeground(). Si le service ne le fait pas, le système génère une ForegroundServiceDidNotStartInTimeException interne.

Diagnostiquer :

Vous pouvez déterminer 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 workers WorkManager qui exécutent un service de premier plan (appelez setForegound ou setForegroundAsync). Lorsque le cycle de vie de deux workers de premier plan se chevauche, car un worker tente de démarrer un service de premier plan tandis qu'un service de premier plan précédemment exécuté tente de s'arrêter, ce plantage sera accompagné du journal suivant :

Re-initializing SystemForegroundService after a request to shut-down

Un correctif pour ce plantage a été introduit dans WorkManager version 2.10.5.

Si votre application rencontre cette exception, effectuez une mise à jour vers la dernière version de WorkManager et signalez tout problème persistant au suivi des problèmes WorkManager.

ForegroundServiceStartNotAllowedException

Erreur :

Le système génère ForegroundServiceStartNotAllowedException.

Cause:

Cela est généralement dû au lancement d'un service de premier plan par l'application en arrière-plan lorsqu'il n'existe aucune 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, à quelques exceptions près. Si vous tentez de démarrer un service de premier plan en arrière-plan et que vous ne remplissez pas les conditions requises pour l'une des exemptions, le système génère ForegroundServiceStartNotAllowedException. Le système le fait également si vous ne remplissez pas les conditions requises pour l'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 immédiatement mettre l'application en arrière-plan. L'application tente alors de lancer le service en arrière-plan. Si l'application ne remplit pas l'une des exemptions spécifiées, le système génère une ForegroundServiceStartNotAllowedException.

De plus, certaines exemptions sont soumises à une limite de temps courte. Par exemple, il existe une brève exemption si votre application lance un service de premier plan en réponse à un message FCM haute priorité. Si vous ne lancez pas le service assez rapidement, vous obtenez une 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 exemptions 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 exemptions.

Vous pouvez utiliser des composants qui tiennent compte des cycles 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 en 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 une 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 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 lorsqu'elle est en arrière-plan, le système générera une SecurityException, même si l'application bénéficie d'une exemption pour démarrer un service de premier plan en arrière-plan. Pour en savoir plus, consultez Restrictions concernant le démarrage de services de premier plan nécessitant des autorisations d'utilisation des autorisations.
    • 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 avez rempli toutes les autres conditions préalables à l'exécution.