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

Cette page décrit certaines raisons courantes pour lesquelles les services de premier plan peuvent échouer et vous aide à identifier l'origine 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

Si les services de premier plan sont utilisés de manière incorrecte, 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 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 modifications récentes peuvent 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 ne fonctionne plus
  • 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 version Preview développeur de la plate-forme, veillez à consulter la version la plus récente de la documentation Preview développeur.

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

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 Application Not Responding (ANR, L'application ne répond pas).

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

Les services de premier plan qui utilisent le type de service court doivent se terminer rapidement, en environ trois minutes. 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 automatiquement, le système déclenche une erreur "L'application ne répond pas".

Diagnostic:

Si l'erreur ANR est due à l'échec de l'arrêt d'un service de premier plan, le système génère une exception interne. Pour vérifier que c'était bien le cas, consultez Logcat. Dans ce cas, le journal 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 la limite de temps du 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 immédiatement stopSelf().

Exceptions de service de premier plan

Cette section décrit plusieurs problèmes de service de premier plan pouvant entraîner l'exception du système. Si l'application ne capture pas l'exception, une boîte de dialogue s'affiche pour indiquer à l'utilisateur que l'application s'est arrêtée.

Dans certains cas, le système génère une exception interne. Vous ne pouvez pas intercepter ces exceptions, mais vous pouvez consulter Logcat pour voir quelle exception a été générée.

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

Le système impose une limite sur la durée pendant laquelle les services de premier plan de synchronisation des données et de traitement multimédia peuvent s'exécuter 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 interne qui entraîne le plantage de l'application.

Diagnostic:

Si le délai avant expiration est dépassé, Logcat inclut le message 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 la limite de temps du 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 immédiatement stopSelf().

Exception interne: ForegroundServiceDidNotStartInTimeException

Lorsque vous lancez un service en appelant context.startForegroundService(), ce service dispose de quelques secondes pour s'auto-promouvoir en tant que service de premier plan en appelant ServiceCompat.startForeground(). Si le service ne le fait pas, le système déclenche une erreur ANR.

Diagnostic:

Si un service de premier plan ne s'est pas lancé à temps, l'application plante, ce qui fait apparaître une boîte de dialogue App has stopped (L'application s'est arrêtée). Dans ce cas, le message suivant s'affiche dans Logcat:

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 quelques secondes.

ForegroundServiceStartNotAllowedException

Erreur :

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

Cause:

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

À partir d'Android 12 (niveau d'API 31), les applications ne sont pas autorisées à démarrer de services de premier plan lorsqu'elles s'exécutent en arrière-plan, à l'exception de quelques cas particuliers. Si vous tentez de démarrer un service de premier plan en arrière-plan et que vous ne remplissez pas les conditions requises de l'une des exceptions, 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 et le lancement d'un service de premier plan. Dans ce cas, il existe un risque que l'utilisateur clique sur le bouton, puis mette immédiatement l'application en arrière-plan. Dans ce cas, l'application tenterait de lancer le service en arrière-plan. Si l'application ne répond pas à l'une des exceptions spécifiées, le système génère une exception ForegroundServiceStartNotAllowedException.

De plus, certaines exceptions sont soumises à une courte limite de temps. Par exemple, une courte exemption s'applique 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 recevez une ForegroundServiceStartNotAllowedException.

Les exceptions 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 répond toujours à l'une des exceptions autorisées.

Solution :

Modifiez le workflow de votre application afin qu'elle n'ait pas besoin de lancer de services de premier plan lorsqu'elle est en arrière-plan, ou vérifiez que votre application répond à l'une des exceptions.

Vous pouvez utiliser des composants compatibles avec le cycle de vie pour gérer le cycle de vie de votre application afin de ne pas essayer par inadvertance de lancer un service de premier plan en arrière-plan.

SecurityException

Erreur :

Le système génère une exception 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 tous les prérequis pour son type de service de premier plan. Ces prérequis sont détaillés 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. 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é l'une de ces autorisations et qu'elle lui a été accordée, 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 dispose d'une exception pour démarrer un service de premier plan en arrière-plan. 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.
    • Vous pouvez obtenir un 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 tous les autres prérequis d'exécution.