Comment configurer le routage WKWebView pour prendre en charge les Universal Links sur iOS

opoinstall
2026-10-07
5 min read

Comment activer les Universal Links au sein d'une WKWebView iOS ? Les Universal Links peuvent être résolus à partir de liens éligibles au sein d'une WKWebView. L'implémentation de WKNavigationDelegate permet à l'application hôte de personnaliser les politiques de routage : intercepter les destinations appartenant à l'application, contrôler les transferts externes via decidePolicyForNavigationAction et appliquer une sécurité au niveau des cadres (frames).

Dans l'architecture d'une application iOS, l'interception de la navigation dans WKWebView permet à l'application hôte de personnaliser les politiques de routage pour les Universal Links, les schémas d'URL personnalisés et les destinations web. En évaluant les métadonnées de la requête de navigation au sein d'un WKNavigationDelegate, l'application peut acheminer les destinations internes, déléguer les cibles externes aux gestionnaires système et appliquer des politiques de sécurité au niveau des cadres.

Terme Définition Entité liée Rôle de l'intention de recherche
WebView Composant de vue intégré basé sur WebKit qui rend du contenu web interactif dans les applications iOS. SDK iOS Informationnel / Commercial
Universal Links Mécanisme HTTPS standard reliant des domaines web vérifiés à des vues d'application native iOS. Routage Deep Link Technique / Informationnel
Custom URL Scheme Schéma d'URI défini par l'application utilisé pour router des URL vers une application native. Mobile Deep Linking Informationnel

Interaction entre WKWebView et le routage des Universal Links sur iOS

WKNavigationDelegate détermine si WebKit charge, route en interne, transfère ou annule.

Cycles de vie de navigation WebKit et politiques de routage propres à l'application

Apple implémente les Universal Links comme un mécanisme de routage au niveau du système, pris en charge dans Safari et les environnements WKWebView. Lorsqu'un utilisateur appuie sur un lien éligible au sein d'une WKWebView intégrée, la plateforme peut résoudre les associations de domaine et acheminer l'exécution conformément aux politiques du système d'exploitation.

Bien que les Universal Links reconnus par le système puissent transférer l'exécution aux gestionnaires natifs, les environnements de navigation intégrés nécessitent fréquemment une logique de routage spécifique à l'application. Par exemple, lorsqu'un lien cible le domaine propre à l'application hôte, les développeurs préfèrent souvent naviguer directement via des contrôleurs de vue natifs sans déclencher de relancement complet de l'application externe. L'implémentation de WKNavigationDelegate offre à l'application hôte un contrôle granulaire sur l'évaluation des liens, permettant aux équipes d'appliquer des listes d'autorisation personnalisées et de router les destinations internes de manière prévisible.

L'obstacle à l'expérience utilisateur : quand la navigation web intégrée piège les utilisateurs

Les WebView intégrées sont fréquemment déployées pour héberger des microsites promotionnels, des centres d'aide, des catalogues de partenaires et des pages de destination marketing au sein des applications iOS. Lorsqu'une page web intégrée inclut des liens destinés à rediriger les utilisateurs vers d'autres sections de l'application hôte (ex. : boutons « Voir dans l'application ») ou vers des applications partenaires, la navigation par défaut peut entraîner des rendus redondants :

  • Rendu web redondant : Au lieu d'afficher des contrôleurs de vue natifs, l'utilisateur peut se voir présenter des versions web responsives des pages de l'application, nécessitant des authentifications répétées et dégradant la cohérence visuelle.
  • Piège de navigation web : Les utilisateurs peuvent se retrouver coincés dans des piles de navigation web profondes sans moyens intuitifs de revenir aux interfaces natives principales.
  • Échecs de transition inter-applications : Appuyer sur des liens pointant vers des services tiers (tels que des applications de navigation, des dialogues de partage social ou des passerelles de paiement) nécessite une délégation explicite si ces services reposent sur des schémas d'URL personnalisés.

Comparaison entre WKWebView et SFSafariViewController pour les transitions web-to-app

Lors de la conception de la navigation web intégrée sur iOS, les équipes d'ingénierie doivent choisir entre WKWebView et SFSafariViewController :

  • SFSafariViewController : Fournit une interface de navigation Safari gérée par le système avec des fonctionnalités telles que le remplissage automatique (AutoFill) et le blocage de contenu. L'application hôte ne peut pas inspecter l'activité de navigation ou les données du site web, et la personnalisation de l'interface est limitée.
  • WKWebView : Un composant de vue intégré hébergé dans le processus UI de l'application tout en exécutant le contenu web dans des processus WebKit séparés. Il permet une personnalisation approfondie de l'interface, des ponts JavaScript et une intégration de mise en page personnalisée, nécessitant l'implémentation explicite de WKNavigationDelegate pour personnaliser les politiques de routage et gérer les schémas personnalisés.

Comment decidePolicyForNavigationAction intercepte le routage WebKit

Le pipeline de politique de navigation : Comprendre WKNavigationAction, request et decisionHandler

Pour contrôler le flux de navigation dans une WKWebView, les développeurs assignent un délégué personnalisé conforme aux directives d'Apple sur WKNavigationDelegate. Le point d'interception principal est la méthode du délégué :

func webView(
    _ webView: WKWebView,
    decidePolicyFor navigationAction: WKNavigationAction,
    decisionHandler: @escaping (WKNavigationActionPolicy) -> Void
)

Les actions de navigation déclenchées par les interactions de l'utilisateur, les redirections programmatiques ou les soumissions de formulaires passent par cette méthode. L'objet WKNavigationAction fournit des métadonnées clés :

  • navigationAction.request.url : L'URL cible demandée.
  • navigationAction.navigationType : Le type de déclencheur (.linkActivated, .other, .formSubmitted).
  • navigationAction.sourceFrame : Informations sur le cadre initiant la requête de navigation.
  • navigationAction.targetFrame : Informations sur le cadre de destination où le contenu doit être chargé.

Le decisionHandler est une closure de complétion qui informe WebKit s'il doit autoriser ou annuler la navigation demandée.

Quand retourner .allow vs .cancel : Contrôler le cycle de vie du chargement des ressources WebKit

La WKNavigationActionPolicy passée au decisionHandler contrôle si WebKit poursuit la navigation :

  • .allow : Informe WebKit de poursuivre la navigation demandée dans la vue web.
  • .cancel : Demande à WebKit d'annuler la navigation. Cette politique est exécutée chaque fois que l'application hôte intercepte un schéma personnalisé, route un Universal Link en interne ou délègue une cible externe à UIApplication.shared.open().

Le decisionHandler doit être appelé exactement une fois par action de navigation pour garantir que la résolution de la politique se poursuive sans blocage.

Évaluation des types de navigation : Distinguer les clics utilisateurs (.linkActivated) des redirections automatisées

WKNavigationAction.navigationType permet aux développeurs de distinguer les interactions explicites de l'utilisateur des scripts automatisés :

  • .linkActivated : L'utilisateur a physiquement appuyé sur une balise d'ancrage HTML (<a href="...">).
  • .other : Représente les navigations programmatiques, telles que les mises à jour window.location.href, les meta-rafraîchissements ou les appels webView.load() initiaux.
  • .formSubmitted / .formResubmitted : Représente les soumissions de formulaires POST ou GET.

L'évaluation du navigationType permet aux applications d'appliquer une politique stricte de lien explicite au niveau de l'application. Pour les invocations de schémas personnalisés externes ou les transferts vers des applications tierces, exiger .linkActivated comme porte d'entrée aide à empêcher les scripts en arrière-plan non sollicités de déclencher des lancements d'applications externes automatisés.

Gérer les politiques de décision asynchrones sans cycles de rétention

Lorsque la validation du routage ou les vérifications d'autorisation nécessitent d'interroger des caches locaux ou des validateurs de sécurité avant de retourner une décision :

  1. Assurez-vous que le decisionHandler est exécuté sur tous les chemins d'exécution, y compris les conditions d'erreur et de garde.
  2. Utilisez des références faibles ([weak self]) au sein des closures pour éviter les cycles de rétention entre la WKWebView, son délégué et le UIViewController parent.

Différencier les domaines associés de l'application hôte des Universal Links externes

Les Universal Links appartenant à l'application doivent valider et router en interne depuis la WKWebView.

Gestion des destinations appartenant à l'application vs délégation de liens au niveau système

Pour les routes appartenant à l'application, évitez de tenter de rentrer dans la même application via une recherche d'Universal Link redondante. Gérez les destinations internes directement via le routeur de l'application hôte, et utilisez l'ouverture système principalement pour les destinations qui doivent quitter l'application actuelle ou être résolues par des services externes.

Cette séparation architecturale assure une navigation fluide :

  • Domaines associés à l'application : Si l'hôte de l'URL correspond au domaine associé de l'application hôte (app.example.com), annulez la navigation dans la vue web (decisionHandler(.cancel)), validez le chemin de route et passez les paramètres analysés directement au routeur de navigation interne de l'application.
  • Applications externes : Si l'URL pointe vers une destination de partenaire externe ou un schéma personnalisé autorisé, appliquez une porte d'entrée de lien explicite au niveau de l'application (navigationType == .linkActivated), annulez la navigation dans la vue web et transférez la requête à UIApplication.shared.open(url) pour laisser le système d'exploitation lancer l'application externe.

Conception de la validation de route interne : Extraction des chemins et paramètres via AppRouteValidator

Lorsqu'une URL entrante correspond au domaine associé de l'application hôte, la chaîne d'URL doit passer par un validateur de routage strict avant de déclencher des transitions de contrôleur de vue.

Le modèle AppRouteValidator :

  • Valide le chemin d'URL par rapport à une liste d'autorisation de routes internes prises en charge (ex. : /open/, /product/, /promo/, /checkout/).
  • Extrait les paramètres de requête (ex. : id, promo, utm_source).
  • Applique des restrictions sur les jeux de caractères, les limites de longueur et le rejet des clés en double, retournant une structure de données ValidatedAppRoute propre.

Gestion des Universal Links tiers externes via la délégation UIApplication du système

Les Universal Links externes peuvent tenter un transfert natif et revenir au web en cas d'échec.

Lorsqu'une page web au sein d'une WKWebView pointe vers des services externes (tels que des applications partenaires, des plateformes sociales ou des utilitaires externes), l'application hôte peut déléguer le routage au système iOS :

let options: [UIApplication.OpenExternalURLOptionsKey: Any] = [
    .universalLinksOnly: true
]
UIApplication.shared.open(url, options: options) { success in
    if !success {
        // Fallback de politique d'application : charger la destination web si aucune application native ne gère l'Universal Link
    }
}

L'utilisation de .universalLinksOnly comme politique d'application garantit que l'utilisateur n'est transféré hors de l'application actuelle que si une application native vérifiée est installée pour gérer l'Universal Link.

Gestion des fallbacks de schémas d'URL personnalisés (myapp://) avec les Universal Links HTTPS

Bien que les Universal Links HTTPS représentent le deep linking standard sur iOS, les schémas personnalisés définis par l'application (myapp:// ou partnerapp://) restent courants dans les campagnes promotionnelles et les intégrations de partenaires.

Dans une implémentation unifiée de WKNavigationDelegate :

  • Les schémas non-HTTP/HTTPS sont inspectés en premier. Si le schéma correspond à un protocole personnalisé autorisé et satisfait à la politique de lien explicite (navigationType == .linkActivated), le délégué vérifie l'hôte, le chemin et les paramètres avant de transmettre à UIApplication.shared.open().
  • Les schémas non reconnus ou les invocations de schémas en arrière-plan non sollicitées sont annulés immédiatement, évitant ainsi les erreurs de navigation non gérées ou les inondations d'intentions pilotées par script.
[Utilisateur interagit avec un lien dans WKWebView iOS]
                       │
                       ▼
[WKNavigationDelegate: decidePolicyForNavigationAction]
                       │
         ┌─────────────┴─────────────┐
         ▼                           ▼
[!action.sourceFrame.isMainFrame] [action.sourceFrame.isMainFrame]
         │                           │
         ▼                           ▼
[Porte de sécurité Subframe]       [Inspecter schéma & hôte de destination]
├─ HTTP(S) -> .allow                 │
└─ Non-Web -> .cancel    ┌───────────┼───────────┐
   (Supprimer Subframe)   ▼           ▼           ▼
                   [Domaine Hôte] [Web Externe] [Schéma Perso]
                         │           │           │
                         ▼           ▼           ▼
                   [AppRoute]    [Vérif Lien]   [Vérif Lien]
                   ├─ Valide ->   ├─ Partenaire-> ├─ Valide & Clic->
                   │  Interne      │  Ouvrir App    │  Ouvrir App
                   └─ Invalide->  └─ Web ->      └─ Invalide/Auto->
                      .cancel       .allow         .cancel

Comment renforcer la sécurité du cadre principal et empêcher le détournement d'iframe

L'origine du cadre et le contexte cible de WKNavigationAction déterminent la politique de navigation sécurisée.

Traiter la navigation web intégrée comme une entrée non fiable : Normes de sécurité OWASP pour les Deep Links

Conformément aux directives du guide de test de sécurité des applications mobiles OWASP sur les deep links non sécurisés, toutes les URL et charges utiles de paramètres traitées par les gestionnaires de navigation mobiles doivent être traitées comme des entrées externes non fiables.

Les pages web rendues dans une WKWebView peuvent charger des scripts tiers, des bannières publicitaires ou du contenu généré par l'utilisateur. Si un délégué de navigation transfère des URL arbitraires vers des contrôleurs de vue natifs ou UIApplication.shared.open() sans validation, des paramètres inattendus pourraient cibler des routes internes sensibles de l'application.

Isoler les navigations du cadre principal des iframes intégrées et des cibles de nouvelle fenêtre

Conformément à la documentation pour développeurs Apple sur WKNavigationAction, l'évaluation de la sécurité du cadre nécessite de vérifier le cadre initiateur :

  • sourceFrame.isMainFrame == true : La navigation a été initiée directement par le cadre de document principal (de premier niveau).
  • sourceFrame.isMainFrame == false : La navigation a été initiée par un sous-cadre intégré ou une iframe.
  • targetFrame == nil : La navigation demande une nouvelle cible de fenêtre (comme une ancre avec target="_blank").

Pour empêcher le détournement d'iframe (où une iframe intégrée tente de lancer des applications externes ou de déclencher des transitions de vue natives en arrière-plan), le délégué doit évaluer sourceFrame.isMainFrame. Si le cadre initiateur est une iframe (sourceFrame.isMainFrame == false), autorisez la navigation standard HTTP/HTTPS des sous-cadres (.allow), mais bloquez tous les schémas personnalisés non-web ou les transferts de routage natifs (.cancel).

Prévenir les invocations de protocoles de sous-cadre malveillants et l'inondation de schémas en arrière-plan

L'application de vérifications du cadre initiateur empêche les sous-cadres de déclencher des invocations de schémas externes non sollicitées :

if !navigationAction.sourceFrame.isMainFrame {
    let scheme = url.scheme?.lowercased() ?? ""
    if scheme == "http" || scheme == "https" {
        decisionHandler(.allow) // Autoriser la navigation standard HTTP(S) des sous-cadres
    } else {
        decisionHandler(.cancel) // Supprimer les schémas non-web des sous-cadres
    }
    return
}

Appliquer des listes d'autorisation strictes de chemins et de paramètres de requête dans le routage client

Les URL de domaines associés internes et les schémas personnalisés externes doivent passer par des modèles de validation stricts avant exécution :

  • Liste d'autorisation de préfixes de chemin : Appliquez des préfixes de route approuvés (ex. : /open/, /product/, /promo/, /checkout/), en rejetant les chemins arbitraires ou malformés.
  • Filtrage des clés de requête : Éliminez les clés de requête inattendues et rejetez les clés de paramètres en double pour empêcher la pollution des paramètres.
  • Contraintes de type de données et de longueur : Restreignez les valeurs de paramètres aux jeux de caractères alphanumériques et appliquez des limites de longueur maximale (≤64\le 64 caractères).

Implémentation en production de WKNavigationDelegate en Swift

Structurer l'architecture CustomWebViewController et le délégué en Swift

Un contrôleur WKWebView en production coordonne la configuration web, l'évaluation de la politique de navigation, le routage interne et la délégation externe. L'implémentation encapsule les règles de validation au sein de classes de validateurs dédiées (AppRouteValidator et CustomSchemeValidator) pour garder les callbacks du délégué propres, testables et sécurisés.

Implémentation des modèles AppRouteValidator et CustomSchemeValidator

Les modèles de validateurs appliquent une sécurité stricte « fail-closed » :

  • AppRouteValidator valide les domaines associés internes, vérifiant les préfixes de chemin et assainissant les paramètres de requête dans un objet ValidatedAppRoute structuré.
  • CustomSchemeValidator vérifie les schémas personnalisés autorisés (myapp), valide les hôtes autorisés (open, product, event) et assainit les valeurs de requête.

OpoInstall peut être intégré parallèlement à une couche de routage appartenant à l'application pour l'attribution et la récupération différée des paramètres. Consultez la documentation d'intégration du SDK pour des guides complets.

L'implémentation technique ci-dessous démontre comment configurer un WKNavigationDelegate sécurisé en Swift :

// iOS: CustomWebViewController avec routage WKNavigationDelegate strict et sécurité des cadres
// Exemple d'intégration de référence. Vérifiez les signatures de méthode et les mappages de domaine par rapport à votre architecture déployée.
import UIKit
import WebKit

struct ValidatedAppRoute {
    let path: String
    let queryParams: [String: String]
}

// 1. Validateur pour le domaine associé de l'application hôte (routes internes)
class AppRouteValidator {
    private static let allowedPrefixes = ["/open/", "/product/", "/promo/", "/checkout/"]
    private static let allowedQueryKeys = Set(["target", "id", "promo", "utm_source"])

    static func validate(url: URL) -> ValidatedAppRoute? {
        let path = url.path
        // Appliquer la liste d'autorisation de préfixes de chemin
        guard allowedPrefixes.contains(where: { path.hasPrefix($0) }) else {
            return nil
        }

        var sanitizedParams: [String: String] = [:]
        var seenKeys = Set<String>()

        if let components = URLComponents(url: url, resolvingAgainstBaseURL: false),
           let queryItems = components.queryItems {
            let validChars = CharacterSet(charactersIn: "abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789_-")
            
            for item in queryItems {
                // Validation fail-closed : rejeter l'URL si les clés de requête ne sont pas autorisées ou si des clés en double existent
                guard allowedQueryKeys.contains(item.name), !seenKeys.contains(item.name) else { return nil }
                seenKeys.insert(item.name)

                let value = item.value ?? ""
                if value.count <= 64 && value.rangeOfCharacter(from: validChars.inverted) == nil {
                    sanitizedParams[item.name] = value
                } else {
                    return nil
                }
            }
        }

        return ValidatedAppRoute(path: path, queryParams: sanitizedParams)
    }
}

// 2. Validateur pour les schémas personnalisés externes (myapp://)
class CustomSchemeValidator {
    private static let allowedSchemes = Set(["myapp"])
    private static let allowedHosts = Set(["open", "product", "event"])
    private static let allowedPathPrefixes = ["/detail/", "/view/", "/main/"]
    private static let allowedQueryKeys = Set(["target", "id", "promo", "utm_source"])

    static func validate(url: URL) -> URL? {
        guard let scheme = url.scheme?.lowercased(), allowedSchemes.contains(scheme) else {
            return nil
        }
        guard let host = url.host?.lowercased(), allowedHosts.contains(host) else {
            return nil
        }

        let path = url.path
        if !path.isEmpty && !allowedPathPrefixes.contains(where: { path.hasPrefix($0) }) {
            return nil
        }

        var seenKeys = Set<String>()
        if let components = URLComponents(url: url, resolvingAgainstBaseURL: false),
           let queryItems = components.queryItems {
            let validChars = CharacterSet(charactersIn: "abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789_-")
            for item in queryItems {
                guard allowedQueryKeys.contains(item.name), !seenKeys.contains(item.name) else { return nil }
                seenKeys.insert(item.name)

                let value = item.value ?? ""
                if value.count > 64 || value.rangeOfCharacter(from: validChars.inverted) != nil {
                    return nil
                }
            }
        }

        return url
    }
}

// 3. UIViewController hébergeant WKWebView avec interception de politique de navigation sécurisée
class CustomWebViewController: UIViewController, WKNavigationDelegate {

    var webView: WKWebView!
    private let hostAssociatedDomain = "app.example.com"
    private let allowedExternalPartnerHosts = Set(["partner.example.com"])

    override func viewDidLoad() {
        super.viewDidLoad()

        let configuration = WKWebViewConfiguration()
        webView = WKWebView(frame: view.bounds, configuration: configuration)
        webView.navigationDelegate = self
        view.addSubview(webView)
    }

    func webView(
        _ webView: WKWebView,
        decidePolicyFor navigationAction: WKNavigationAction,
        decisionHandler: @escaping (WKNavigationActionPolicy) -> Void
    ) {
        guard let url = navigationAction.request.url else {
            decisionHandler(.allow)
            return
        }

        // Vérification de sécurité 1 : Appliquer la frontière du cadre initiateur (sourceFrame) pour empêcher le détournement d'iframe
        if !navigationAction.sourceFrame.isMainFrame {
            let scheme = url.scheme?.lowercased() ?? ""
            if scheme == "http" || scheme == "https" {
                decisionHandler(.allow) // Autoriser la navigation standard HTTP(S) des sous-cadres
            } else {
                decisionHandler(.cancel) // Supprimer les schémas non-web des sous-cadres/iframes
            }
            return
        }

        let scheme = url.scheme?.lowercased() ?? ""
        let isExplicitLinkActivation = (navigationAction.navigationType == .linkActivated)

        // Vérification de sécurité 2 : Gérer le domaine associé de l'application hôte
        // Router en interne au lieu d'appeler UIApplication.shared.open
        if scheme == "https", let host = url.host?.lowercased(), host == hostAssociatedDomain {
            if let validatedRoute = AppRouteValidator.validate(url: url) {
                AppInternalRouter.shared.navigate(to: validatedRoute)
            }
            decisionHandler(.cancel) // Annuler le chargement dans la webview pour router en interne
            return
        }

        // Vérification de sécurité 3 : Gérer les schémas personnalisés autorisés (myapp://) avec la politique d'activation de lien
        if scheme != "http" && scheme != "https" && scheme != "about" {
            // Exiger que les lancements d'applications externes via schémas personnalisés nécessitent une activation de lien explicite
            if isExplicitLinkActivation, let validatedURL = CustomSchemeValidator.validate(url: url) {
                UIApplication.shared.open(validatedURL, options: [:], completionHandler: nil)
            }
            decisionHandler(.cancel) // Annuler le chargement dans la webview pour éviter les erreurs de schémas non gérés
            return
        }

        // Vérification de sécurité 4 : Gérer les destinations externes et les requêtes de nouvelle fenêtre (target="_blank")
        if scheme == "http" || scheme == "https" {
            let host = url.host?.lowercased() ?? ""
            
            // Déléguer les Universal Links de partenaires vérifiés vers l'application externe avec politique de lien explicite
            if allowedExternalPartnerHosts.contains(host) && isExplicitLinkActivation {
                let options: [UIApplication.OpenExternalURLOptionsKey: Any] = [
                    .universalLinksOnly: true
                ]
                UIApplication.shared.open(url, options: options) { [weak self] success in
                    if !success {
                        // Fallback de politique d'application : charger la destination partenaire externe dans la webview si aucune application native ne la gère
                        guard let self = self else { return }
                        self.webView.load(navigationAction.request)
                    }
                }
                decisionHandler(.cancel)
                return
            }

            // Si targetFrame est nil (requête de nouvelle fenêtre), charger en toute sécurité dans la webView actuelle
            if navigationAction.targetFrame == nil {
                webView.load(navigationAction.request)
                decisionHandler(.cancel)
                return
            }

            // Le contenu web standard continue de se charger dans WKWebView
            decisionHandler(.allow)
            return
        }

        decisionHandler(.allow)
    }
}

// Placeholder de routeur interne spécifique à l'application (pas une API SDK OpoInstall)
class AppInternalRouter {
    static let shared = AppInternalRouter()

    func navigate(to route: ValidatedAppRoute) {
        // Exécuter la transition du contrôleur de vue UI interne basée sur le chemin et les paramètres de requête
    }
}

Exécution thread-safe : S'assurer que les transitions d'UI s'exécutent sur le Main Actor

Dans les modèles de concurrence Swift actuels, les callbacks de WKNavigationDelegate sont isolés sur le main-actor. Le routage de l'application et les transitions de contrôleur de vue s'exécutent sur le thread principal, maintenant la sécurité des threads sur les flux de navigation natifs.

Matrice de diagnostic et erreurs de navigation deep link WKWebView

Guide complet de dépannage du Deep Linking dans WKWebView iOS

La matrice ci-dessous décrit les modes de défaillance courants rencontrés lors de la gestion des deep links et des schémas personnalisés dans une WKWebView iOS, ainsi que leurs causes racines principales et les remédiations recommandées :

Signature d'erreur / Symptôme Cause racine principale Versions iOS applicables Point de vérification Remédiation recommandée
Universal Link chargé dans le Web Domaine de l'application non intercepté iOS 9+ decidePolicyForNavigationAction non géré Intercepter le domaine hôte, analyser le chemin, router en interne, .cancel
Le lien du domaine propre échoue Appel de UIApplication.open sur son propre domaine iOS 9+ UIApplication.shared.open appelé sur son propre hôte Éviter l'ouverture externe de soi-même ; router directement vers le routeur interne
Schéma personnalisé échoue silencieusement Protocole non-HTTP non reconnu par WebKit iOS 9+ Schéma non délégué à UIApplication Intercepter le schéma dans le délégué, valider, ouvrir via UIApplication
Détournement de protocole Iframe Sous-cadre déclenchant un schéma personnalisé externe iOS 9+ sourceFrame.isMainFrame non vérifié Protéger avec if !sourceFrame.isMainFrame et supprimer les schémas non-web
Problème de transition ou avertissement UI Transitions UI exécutées hors thread principal iOS 9+ Dispatch main-actor manquant Assurer l'exécution sur le thread principal pour le routeur et les transitions de vue

Questions Fréquemment Posées (FAQ)

Comment les développeurs peuvent-ils intercepter les Universal Links dans une WKWebView ?
Les développeurs implémentent <code>WKNavigationDelegate</code> et inspectent les URL entrantes dans <code>decidePolicyForNavigationAction</code>. Si l'URL correspond à une destination appartenant à l'application, le délégué annule la navigation dans la webview avec <code>.cancel</code> et transmet les paramètres validés directement au routeur interne de l'application.
Puis-je utiliser UIApplication.shared.open pour lancer ma propre application à partir d'une WKWebView ?
La documentation Apple spécifie qu'appeler <code>UIApplication.shared.open()</code> sur un Universal Link pointant vers le domaine associé de l'application hôte n'ouvrira pas le lien dans l'application en tant qu'Universal Link. Pour les liens du même domaine, l'application doit annuler la navigation dans la webview et invoquer directement son routeur de navigation interne.
Comment empêcher les iframes intégrées dans une WKWebView de déclencher des lancements d'applications externes ?
Pour éviter le détournement d'iframe, vérifiez <code>navigationAction.sourceFrame.isMainFrame</code> à l'intérieur de <code>decidePolicyForNavigationAction</code>. Si <code>isMainFrame</code> est <code>false</code>, autorisez la navigation standard HTTP(S) des sous-cadres avec <code>.allow</code>, mais annulez les schémas personnalisés non-web avec <code>.cancel</code> pour empêcher les iframes tierces d'exécuter des lancements externes non sollicités.

Résumé et cadre de décision

Gérer les Universal Links et les schémas personnalisés au sein d'une WKWebView iOS nécessite de faire le pont entre le conteneur de rendu web de WebKit et les cycles de vie de navigation natifs UIKit. S'appuyer sur les politiques de navigation par défaut peut empêcher des transitions fluides lorsque la logique de routage propre à l'application est requise.

En implémentant un WKNavigationDelegate robuste qui vérifie les frontières des cadres, applique des politiques d'activation de lien conservatrices sur les transferts externes, analyse les domaines associés internes via des validateurs de route stricts et délègue les cibles externes en toute sécurité à UIApplication.shared.open, les équipes d'ingénierie maintiennent une navigation contrôlée tout en se protégeant contre le détournement de protocole par iframe.

Pour explorer les architectures de deep linking natif iOS et de routage de paramètres, consultez la documentation d'intégration du SDK.

Matériaux connexes

Share this article