Simplifier l'implémentation WebView avec Jetpack Webkit

Ce guide décrit les avantages de la bibliothèque Jetpack Webkit, explique son fonctionnement et comment l'implémenter dans vos projets.

Présentation

Les WebView sont un élément essentiel du développement Android, mais elles peuvent parfois être difficiles à gérer en raison des incohérences entre les fonctionnalités des différentes versions de l'OS Android. Chaque version de l'OS Android fournit un ensemble fixe d'API WebView. Comme Android est fourni à une cadence plus lente que WebView, les API Android peuvent ne pas couvrir toutes les fonctionnalités WebView disponibles. Cela entraîne un déploiement plus lent des fonctionnalités et une augmentation des coûts de test.

Jetpack Webkit résout ces problèmes en agissant comme une couche de compatibilité et en exploitant l'APK WebView à jour sur l'appareil de l'utilisateur. Il contient également des API nouvelles et modernes qui ne sont disponibles que dans cette bibliothèque.

Pourquoi utiliser Jetpack Webkit ?

En plus d'offrir une compatibilité entre les versions, Jetpack Webkit propose également des API nouvelles et modernes qui peuvent simplifier le développement et améliorer les fonctionnalités de votre application :

  • Active l'authentification moderne : WebView peut gérer de manière transparente les normes d'authentification Web modernes telles que WebAuthn, ce qui permet de se connecter à l'aide de clés d'accès. La bibliothèque androidx.webkit vous offre un contrôle total sur cette intégration à l'aide de la méthode WebSettingsCompat.setWebAuthenticationSupport, que vous pouvez utiliser pour configurer le niveau de compatibilité requis par votre application.

  • Améliore les performances : affinez les performances de WebView à l'aide d'API telles que setBackForwardCacheEnabled, ou réduisez la latence de navigation à l'aide d'API de chargement spéculatif telles que prefetchUrlAsync et prerenderUrlAsync. Pour en savoir plus, consultez la section Chargement spéculatif dans WebView.

  • Augmente la stabilité : récupérez les processus de rendu bloqués ou qui ne répondent pas sans plantage. Pour en savoir plus, consultez WebViewRenderProcess#terminate.

  • Offre un contrôle précis sur les données de navigation : pour supprimer les données de navigation stockées par WebView pour des origines spécifiques, utilisez la classe WebStorageCompat.

  • Améliore la navigation sur les pages : remplacez WebView.loadUrl par WebViewCompat.navigate pour un contrôle précis de la navigation, le remplacement des entrées d'historique , la compatibilité avec les en-têtes d'état enregistrés et le suivi corrélé du cycle de vie à l'aide de NavigationListener. Pour en savoir plus, consultez la section Navigation améliorée sur les pages avec WebViewCompat.navigate.

  • Optimise la gestion des états : protégez-vous contre TransactionTooLargeException en définissant des limites maximales d'octets lors de la sérialisation des états. Pour en savoir plus, consultez la section Gérer efficacement l'état WebView.

Comprendre les composants

Pour utiliser efficacement Jetpack Webkit, vous devez comprendre la relation entre les composants suivants :

  • Android System WebView : il s'agit du moteur de rendu basé sur Chromium que Google met régulièrement à jour via le Google Play Store à la même cadence que Chrome. Il contient les fonctionnalités les plus récentes et fournit le code d'implémentation sous-jacent pour toutes les API WebView.

  • API Framework (android.webkit) : il s'agit des API qui sont fixes pour une version spécifique de l'OS Android. Par exemple, une application sur Android 10 ne peut accéder qu'aux API disponibles lors de la sortie de cette version. Elle ne peut donc pas utiliser les nouvelles fonctionnalités ajoutées à l'APK WebView dans des mises à jour plus récentes. Par exemple, pour gérer un moteur de rendu qui ne répond pas avec WebView#getWebViewRenderProcess(), vous ne pouvez appeler cette méthode que sur Android 10 et versions ultérieures.

  • Bibliothèque Jetpack Webkit (androidx.webkit) : il s'agit d'une petite bibliothèque fournie avec votre application. Cette bibliothèque sert de pont qui appelle l'APK WebView, plutôt que les API définies dans la plate-forme Android, qui a une version d'OS fixe. Ainsi, même lorsqu'une application est installée sur un appareil exécutant une ancienne version de l'OS, comme Android 10, elle peut utiliser les dernières fonctionnalités WebView. Par exemple, WebViewCompat.getWebViewRenderProcess() fonctionne de la même manière que l'API Framework, sauf qu'elle peut également être appelée sur toutes les versions de l'OS antérieures à Android 10.

Si une API est disponible à la fois dans le framework et dans Jetpack Webkit, nous vous recommandons de choisir la version Jetpack Webkit. Cela permet de garantir un comportement et une compatibilité cohérents sur la plus large gamme d'appareils.

Interaction entre Jetpack Webkit et l'APK

Les API de Jetpack Webkit sont implémentées en deux parties :

  • Jetpack Webkit statique : la bibliothèque Jetpack Webkit statique contient une minorité du code responsable de l'implémentation de l'API.

  • APK WebView : l'APK WebView contient la majeure partie du code.

Votre application appelle l'API Jetpack Webkit, qui appelle ensuite l'APK WebView.

Bien que vous contrôliez la version de Jetpack Webkit dans votre application, vous ne pouvez pas contrôler les mises à jour de l'APK WebView sur les appareils des utilisateurs. En général, la plupart des utilisateurs disposent de versions à jour de l'APK WebView, mais votre application doit toujours veiller à ne pas appeler d'API non compatibles avec cette version spécifique de l'APK WebView.

Jetpack Webkit élimine également la nécessité de vérifier manuellement les versions de WebView. Pour déterminer si une fonctionnalité est disponible, recherchez sa constante de fonctionnalité. Par exemple, WebViewFeature.WEB_AUTHENTICATION.

Fonctionnement combiné

Jetpack Webkit comble le fossé entre l'API Framework statique et l'APK WebView fréquemment mis à jour. Lorsque vous utilisez l'API Jetpack Webkit avec le modèle de détection de fonctionnalités, la bibliothèque vérifie si la fonctionnalité est compatible avec l'APK WebView installé sur l'appareil de l'utilisateur. Cela présente l'avantage de ne pas avoir à vérifier la version de l'OS Android (framework).

Si l'APK WebView est une version suffisamment récente, la bibliothèque appelle la fonctionnalité. Sinon, elle signale que la fonctionnalité n'est pas disponible, ce qui empêche votre application de planter et vous permet de gérer la situation de manière appropriée.

Comparer les API Jetpack Webkit et Framework

Cette section compare les méthodes d'implémentation avec et sans la bibliothèque Jetpack Webkit :

Activer l'authentification moderne (WebAuthn)

Sans Jetpack Webkit

Impossible via les API Framework.

Avec Jetpack Webkit

Exploite WebViewFeature.WEB_AUTHENTICATION pour les vérifications de compatibilité.

if (WebViewFeature.isFeatureSupported(WebViewFeature.WEB_AUTHENTICATION)) {
  WebSettingsCompat.setWebAuthenticationSupport(
      webView.settings,
      WebSettingsCompat.WEB_AUTHENTICATION_SUPPORT_FOR_APP
  )
}

Supprimer des données pour une origine (stockage spécifique à un site)

Sans Jetpack WebKit

Aucune API directe pour effacer des données d'origine spécifiques. Nécessite souvent d'effacer toutes les données.

Avec Jetpack WebKit

Utilise des API de compatibilité pour une suppression précise des données. Vous pouvez utiliser l'une des options suivantes :

WebStorageCompat.getInstance().deleteBrowsingData()

Ou

WebStorageCompat.getInstance().deleteBrowsingDataForSite()

Obtenir la version de WebView

Sans Jetpack WebKit

Utilise la classe de framework standard.

val webViewPackage = WebView.getCurrentWebViewPackage()

Avec Jetpack WebKit

Utilise la couche de compatibilité pour une récupération plus sécurisée.

val webViewPackage = WebViewCompat.getCurrentWebViewPackage()

Gérer un moteur de rendu qui ne répond pas (client de rendu)

Sans Jetpack WebKit

Utilise la méthode de framework standard.

webView.setWebViewRenderProcessClient(myClient)

Avec Jetpack WebKit

Utilise WebViewCompat et une vérification des fonctionnalités pour définir le client.

if (WebViewFeature.isFeatureSupported(WebViewFeature.WEB_VIEW_RENDERER_CLIENT_BASIC_USAGE)) {
  WebViewCompat.setWebViewRenderProcessClient(webView, myClient)
}

Pour obtenir des conseils sur l'implémentation de stratégies de récupération après un plantage, consultez Gérer l'arrêt de WebView termination. Pour en savoir plus sur les API, consultez la documentation de référence androidx.webkit.

Gérer l'état enregistré et la taille des transactions

L'API WebViewCompat.saveState vous permet d'appliquer des limites d'octets et d'élaguer l'historique de navigation lors de la sérialisation, ce qui empêche les plantages TransactionTooLargeException tout en préservant l'historique de navigation essentiel.

Sans Jetpack WebKit

Utilise la méthode de framework standard, qui sérialise l'ensemble de la pile de navigation sans limite de taille et peut déclencher TransactionTooLargeException si la charge utile dépasse la limite de transaction de 1 Mo d'Android.

webView.saveState(outState)

Avec Jetpack WebKit

Utilise WebViewCompat pour appliquer une limite maximale d'octets ou supprimer les entrées de navigation, ce qui protège contre les dépassements de transaction.

WebViewCompat.saveState(webView, outState, maxSizeBytes)

Pour en savoir plus, consultez la section Gérer efficacement l'état WebView.

Pour naviguer sur des pages Web avec prise en charge du remplacement des entrées d'historique, de la compatibilité avec les en-têtes d'état enregistrés et des rappels corrélés du cycle de vie, utilisez WebViewCompat.navigate au lieu de WebView.loadUrl.

Sans Jetpack WebKit

Utilise WebView.loadUrl, qui n'est pas compatible avec le remplacement des entrées d'historique ni avec le suivi des rappels corrélés du cycle de vie.

webView.loadUrl("https://www.example.com")

Avec Jetpack WebKit

Utilise WebViewCompat.navigate avec NavigationParameters pour remplacer les entrées d'historique, conserver les en-têtes personnalisés dans l'état enregistré et suivre les états de navigation.

if (WebViewFeature.isFeatureSupported(WebViewFeature.WEBVIEW_NAVIGATE_EXPERIMENTAL_V1)) {
  val params = NavigationParameters.Builder()
      .setShouldReplaceCurrentEntry(true)
      .build()
  val navigation = WebViewCompat.navigate(webView, "https://www.example.com", params)
} else {
  webView.loadUrl("https://www.example.com")
}

Pour en savoir plus sur le suivi de la navigation et la configuration des paramètres, consultez la section Navigation améliorée sur les pages avec WebViewCompat.navigate.

Intégrer Jetpack Webkit à votre code

L'utilisation de Jetpack Webkit augmente les capacités de la classe WebView standard, mais ne remplace pas entièrement la classe WebView d'origine.

Vous pouvez continuer à utiliser la android.webkit.WebView classe. Vous pouvez l'ajouter à vos mises en page XML et obtenir une référence à l'instance dans votre code. Pour accéder aux fonctionnalités de framework standard, vous pouvez toujours appeler des méthodes directement sur l'instance WebView ou son objet de paramètres.

Pour accéder aux fonctionnalités modernes, vous utilisez les méthodes d'assistance statiques fournies par Jetpack Webkit, telles que WebViewCompat et WebSettingsCompat. Vous transmettez votre instance WebView existante à ces méthodes.

Kotlin

import android.webkit.WebView
import androidx.webkit.WebSettingsCompat
import androidx.webkit.WebViewFeature

// You still get your WebView instance the standard way.
val webView: WebView = findViewById(R.id.my_webview)

// To enable a modern feature, you pass that instance to a Jetpack Webkit helper.
if (WebViewFeature.isFeatureSupported(WebViewFeature.FORCE_DARK)) {
    WebSettingsCompat.setForceDark(webView.settings, WebSettingsCompat.FORCE_DARK_ON)
}

Java

import android.webkit.WebView;
import androidx.webkit.WebSettingsCompat;
import androidx.webkit.WebViewFeature;

// You still get your WebView instance the standard way.
WebView webView = findViewById(R.id.my_webview);

// To enable a modern feature, you pass that instance to a Jetpack Webkit helper.
if (WebViewFeature.isFeatureSupported(WebViewFeature.FORCE_DARK)) {
    WebSettingsCompat.setForceDark(webView.settings, WebSettingsCompat.FORCE_DARK_ON);
}

Implémenter Jetpack Webkit

Pour implémenter Jetpack Webkit, procédez comme suit.

Étape 1 : Ajouter la dépendance

Dans le fichier build.gradle.kts ou build.gradle de votre module, incluez la dépendance suivante pour ajouter Jetpack Webkit :

Groovy

dependencies {
    implementation "androidx.webkit:webkit:1.16.0"
}

Kotlin

dependencies {
    implementation("androidx.webkit:webkit:1.16.0")
}

Jetpack Webkit contient des wrappers fins, de sorte que l'impact sur la taille de votre application est minime.

Étape 2 : Adopter le modèle de détection de fonctionnalités

Pour éviter les plantages lors de l'appel d'API non disponibles, utilisez des vérifications de fonctionnalités. Nous vous recommandons d'entourer chaque appel d'API d'une vérification de fonctionnalités et d'envisager une logique de secours lorsque l'API n'est pas disponible.

Nous vous recommandons le modèle suivant pour utiliser une API WebView moderne :

Kotlin

import android.webkit.WebView
import androidx.webkit.WebSettingsCompat
import androidx.webkit.WebViewFeature

val webView: WebView = findViewById(R.id.my_webview)

// Before you use a modern API, first check if it is supported.
if (WebViewFeature.isFeatureSupported(WebViewFeature.FORCE_DARK)) {
    // If the check passes, it is safe to call the API.
    WebSettingsCompat.setForceDark(webView.settings, WebSettingsCompat.FORCE_DARK_ON)
} else {
    // Optionally, provide a fallback for older WebView versions.
}

Java

import android.webkit.WebView;
import androidx.webkit.WebSettingsCompat;
import androidx.webkit.WebViewFeature;

WebView webView = findViewById(R.id.my_webview);

// Before you use a modern API, first check if it is supported.
if (WebViewFeature.isFeatureSupported(WebViewFeature.FORCE_DARK)) {
    // If the check passes, it is safe to call the API.
    WebSettingsCompat.setForceDark(webView.getSettings(), WebSettingsCompat.FORCE_DARK_ON);
} else {
    // Optionally, provide a fallback for older WebView versions.
}

Ce modèle permet de garantir la robustesse de l'application. Comme la vérification des fonctionnalités s'exécute en premier, l'application ne plante pas si la fonctionnalité n'est pas disponible. La surcharge de performances de la WebViewFeature#isFeatureSupported vérification est négligeable.