java.io.IOException: Cleartext HTTP traffic to [host] not permitted signifie qu’Android a refusé une requête http:// non chiffrée conformément à la stratégie de sécurité réseau effective de l’application. Ce problème touche le plus souvent Android 9 ou une version ultérieure lorsque l’application cible le niveau d’API 28 ou supérieur, notamment pour les requêtes effectuées par les composants HTTP de la plate-forme, Media3 ou ExoPlayer. La première mesure, et la plus sûre, consiste à identifier précisément l’hôte bloqué ou la source de la redirection, puis à faire passer la requête en HTTPS si le point de terminaison le permet. N’activez pas globalement le trafic en texte clair avant d’avoir identifié la destination.

Signification de « Cleartext HTTP Traffic Not Permitted »

Le même échec de stratégie peut apparaître sous la forme java.io.IOException: Cleartext HTTP traffic to [host] not permitted, CLEARTEXT communication to [host] not permitted by network security policy ou, plus brièvement, Cleartext HTTP traffic not permitted. Media3 peut également signaler le code associé ERROR_CODE_IO_CLEARTEXT_NOT_PERMITTED ou l’exception CleartextNotPermittedException. Le libellé exact peut varier selon le composant qui émet l’erreur.

Ces signatures signifient que l’application a tenté d’établir une connexion HTTP non chiffrée et que sa stratégie effective a refusé la requête. La documentation Android sur la configuration de la sécurité réseau indique que la prise en charge du trafic en texte clair est désactivée par défaut pour les applications ciblant le niveau d’API 28 ou supérieur. Le niveau d’API cible est déterminant : le simple fait que l’appareil exécute Android 9 ou une version ultérieure ne prouve pas comment la stratégie de chaque application est configurée.

Ce guide s’applique lorsqu’une URL directe, une redirection, une réponse du serveur, une playlist multimédia, une ressource de CDN, un composant de la plate-forme ou un SDK tiers renvoie vers HTTP. Il ne s’applique pas à SSLHandshakeException, CertPathValidatorException ou android.os.NetworkOnMainThreadException, qui correspondent à d’autres types d’échecs.

Identifier le point de terminaison HTTP bloqué par Android

Identifiez la destination utilisée à l’exécution avant de modifier la stratégie de l’application. L’URL visible dans le code source peut ne pas être celle qu’Android finit par bloquer.

  1. Relevez l’hôte indiqué dans l’exception ou la sortie de Logcat.
  2. Vérifiez si l’URL de la requête initiale commence par http://.
  3. Vérifiez si une requête HTTPS initiale est redirigée vers HTTP.
  4. Vérifiez si une réponse du serveur, une playlist multimédia ou un CDN fournit l’URL HTTP d’une ressource.
  5. Utilisez la trace de la pile pour déterminer si la requête provient d’un composant de la plate-forme, de Media3 ou ExoPlayer, de WebView, ou d’une bibliothèque ou d’un SDK tiers.

La lecture multimédia peut échouer même si l’URL initiale semble correcte, car une playlist ou une ressource référencée peut renvoyer vers HTTP. La page officielle de dépannage de Media3 identifie l’utilisation d’une URL HTTP avec une stratégie interdisant le trafic en texte clair comme la cause de cette famille d’erreurs.

Les URL HTTP directes, les redirections vers HTTP et les ressources HTTP renvoyées par un serveur appellent toutes la même première décision : déterminer si cette destination précise peut utiliser HTTPS. Ne créez aucune exception de domaine avant d’avoir identifié l’hôte réellement utilisé à l’exécution.

Correctif 1 : faire passer la requête défaillante en HTTPS

Quand utiliser ce correctif : utilisez-le lorsque vous contrôlez le serveur ou le point de terminaison multimédia, ou lorsque vous pouvez modifier la source de l’URL et que la ressource est disponible en HTTPS.

Conditions préalables :

  • Vous contrôlez le point de terminaison ou pouvez modifier la source qui fournit son URL.
  • La ressource est disponible en HTTPS.
  1. Remplacez http:// par https:// dans la source de l’URL.
  2. Modifiez les redirections afin qu’elles restent en HTTPS.
  3. Testez de nouveau la requête ou le parcours de lecture précis qui échouait.

Résultat attendu : si toutes les ressources du parcours testé restent en HTTPS, Android ne devrait plus refuser cette opération au motif qu’elle utilise du trafic en texte clair. Une redirection ultérieure, une entrée de playlist ou une URL HTTP fournie par le serveur peut encore déclencher l’erreur et doit être vérifiée séparément.

Risque et retour arrière : il s’agit d’une modification de configuration à faible risque, sans risque attendu de perte de données. Rétablissez l’ancienne URL uniquement si le déploiement HTTPS échoue. N’étendez pas cette étape au dépannage sans rapport des certificats : les échecs de validation de certificat ne relèvent pas de cette erreur.

Vérifier le manifeste fusionné et la stratégie de sécurité réseau intégrée

Quand utiliser ce correctif : utilisez cette procédure de diagnostic confirmée lorsque le manifeste source ou la configuration de sécurité réseau semble correct, mais que la version exécutée bloque toujours la requête.

Condition préalable : vous devez pouvoir inspecter le manifeste fusionné ou les ressources intégrées de la version concernée.

  1. Vérifiez le manifeste fusionné, et pas seulement le fichier XML source.
  2. Confirmez que le fichier network_security_config.xml est présent dans l’application générée.
  3. Vérifiez que l’hôte de la requête correspond exactement au domaine autorisé.
  4. Vérifiez si une redirection ou une playlist renvoie vers HTTP.
  5. Effectuez un nouveau test sur la variante de build cible.

Résultat attendu : l’inspection doit montrer si l’application générée contient la référence android:networkSecurityConfig et la stratégie prévues, et si cette stratégie couvre l’hôte réellement bloqué. Elle peut également révéler qu’une autre variante de build ou une ressource HTTP ultérieure est en cause.

Risque et retour arrière : cette inspection présente un faible risque, n’entraîne aucun risque de perte de données et ne nécessite aucun retour arrière. Ne supposez pas qu’une modification du fichier source est active tant que vous n’avez pas vérifié les résultats fusionnés et intégrés.

Correctif 2 : autoriser le trafic en texte clair uniquement pour le domaine requis

Quand utiliser ce correctif : n’utilisez une exception propre à un domaine que lorsque HTTP est inévitable et que vous avez identifié précisément la destination qui en a besoin.

Conditions préalables :

  • L’application cible le niveau d’API 24 ou supérieur.
  • Vous pouvez identifier précisément l’hôte ou le sous-domaine.
  • Vous acceptez que le trafic HTTP en texte clair puisse exposer les données transmises à une interception ou à une modification.
  1. Ajoutez un fichier XML de configuration de la sécurité réseau.
  2. Définissez un élément domain-config avec cleartextTrafficPermitted="true" uniquement pour l’hôte requis.
  3. Laissez includeSubdomains sur false, sauf si tous les sous-domaines nécessitent réellement HTTP.
  4. Référencez le fichier XML avec android:networkSecurityConfig.
  5. Testez de nouveau le point de terminaison bloqué.

Résultat attendu : la destination indiquée peut être autorisée à utiliser HTTP, tandis que les autres destinations restent soumises aux restrictions de l’application relatives au trafic en texte clair. La réussite dépend de la correspondance entre le domaine configuré et l’hôte réellement utilisé à l’exécution, y compris après une redirection ou pour une ressource multimédia.

Risque et retour arrière : il s’agit d’une modification de sécurité à risque moyen, sans risque attendu de perte de données. Le trafic en texte clair reste vulnérable, même lorsque la destination est digne de confiance. Pour annuler l’exception, supprimez l’élément domain-config ou faites passer le point de terminaison en HTTPS. N’étendez pas la configuration à d’autres domaines et n’activez pas includeSubdomains dans le seul but de faire aboutir une requête.

Comportement selon le niveau d’API et solution de repli android:usesCleartextTraffic

Pour la plage cible concernée, le trafic en texte clair est bloqué par défaut à partir du niveau d’API 28. La configuration de la sécurité réseau permet de contrôler ce trafic à partir du niveau d’API 24. Pour les niveaux d’API 23 et inférieurs, les indications Android fournies exigent android:usesCleartextTraffic en complément d’une stratégie de configuration réseau.

Une configuration de sécurité réseau peut remplacer le comportement de android:usesCleartextTraffic à partir d’Android N. Surtout, la documentation officielle de l’attribut d’application usesCleartextTraffic indique que cet attribut est ignoré pour les applications ciblant le niveau d’API 38 ou supérieur. Il ne constitue donc pas une solution de remplacement pérenne à la configuration de sécurité réseau.

Quand utiliser la solution de repli globale : utilisez android:usesCleartextTraffic="true" uniquement pour assurer une compatibilité temporaire, ou lorsque tout le trafic en texte clair doit être autorisé dans une ancienne plage cible et qu’aucune option limitée à un domaine n’est actuellement disponible.

Conditions préalables :

  • Vous comprenez que ce paramètre réduit largement la sécurité du transport.
  • Vous ne disposez pas encore d’une solution plus limitée à un domaine.
  1. Définissez android:usesCleartextTraffic="true" sur l’élément application.
  2. Vérifiez le manifeste fusionné dans l’APK ou l’AAB généré.
  3. Si une configuration réseau est également présente, confirmez que l’application continue de bloquer les destinations non prévues.
  4. Planifiez la migration vers une configuration de sécurité réseau ou vers HTTPS.

Résultat attendu : dans les plages cibles où cet attribut est pris en compte, l’application peut être autorisée à effectuer des requêtes en texte clair, sauf si une configuration de sécurité réseau effective impose un comportement différent. Cette solution de repli ne fonctionnera pas pour les applications ciblant le niveau d’API 38 ou supérieur.

Risque et retour arrière : cette solution de repli présente un risque de sécurité élevé, car elle peut autoriser le trafic en texte clair dans toute l’application. Elle n’efface pas les données de l’application, mais peut exposer les données transmises à une interception ou à une modification. Pour revenir en arrière, rétablissez l’attribut sur false et supprimez les dépendances HTTP.

Vérifier localhost, 10.0.2.2, les adresses IP numériques, les redirections et les URL multimédias

Le développement local et les URL de ressources générées nécessitent une vérification propre à l’application. Si la destination est localhost, une adresse de bouclage, 10.0.2.2 ou une adresse IP numérique, confirmez l’hôte réellement utilisé à l’exécution et l’environnement de build prévu avant de modifier la stratégie. Les signalements concernant ces destinations constituent des indices utiles au diagnostic, mais ils ne permettent pas d’établir comment la configuration d’une application donnée fera correspondre son hôte.

  • Confirmez si la destination est réservée au développement.
  • Vérifiez si la même stratégie relative au trafic en texte clair est intégrée par erreur dans une version de production.
  • Examinez les redirections, les playlists multimédias, les ressources de CDN et les URL fournies par le serveur afin de repérer les destinations HTTP.
  • Déterminez si HttpURLConnection, OkHttp, WebView, MediaPlayer, DownloadManager, Media3, ExoPlayer ou un SDK tiers a émis l’erreur avant de tirer des conclusions propres à un composant.
  • Testez manuellement l’hôte et la variante de build concernés au lieu de supposer qu’une exception de domaine correspond à toutes les destinations locales ou numériques.

N’activez pas le trafic en texte clair dans toute l’application de production uniquement pour prendre en charge un serveur de développement. Si HTTP est temporairement inévitable, limitez toute exception confirmée à la destination requise et vérifiez qu’elle n’est pas plus étendue que nécessaire.

Confirmer la résolution exacte de l’erreur sans élargir l’accès HTTP en texte clair

  1. Testez de nouveau la requête, la chaîne de redirections ou le parcours de lecture précis ayant initialement produit l’erreur.
  2. Testez la variante de build cible concernée au lieu de supposer qu’une variante représente toutes les versions.
  3. Après toute modification de stratégie, vérifiez de nouveau le manifeste fusionné et la configuration de sécurité réseau intégrée.
  4. Si vous avez utilisé une exception de domaine, confirmez que seule la destination requise est autorisée et que les autres destinations HTTP restent bloquées.
  5. Avant d’interpréter le comportement du manifeste, notez si la version cible le niveau d’API 28 ou supérieur et le niveau d’API 38 ou supérieur.

L’opération initiale doit s’exécuter sans produire la signature de refus du trafic en texte clair, tandis que l’application conserve la stratégie la plus restrictive possible. La seule modification d’un fichier source ne confirme pas la résolution. Si l’erreur persiste, vérifiez de nouveau l’hôte utilisé à l’exécution, la chaîne de redirections, les ressources de la playlist, la configuration intégrée et la bibliothèque à l’origine de la requête, plutôt que d’élargir l’exception.