Como solucionar erros de redirecionamento em WebView no Android e iOS?

opoinstall
2026-11-19
5 min read

webview-safe-fallback-loop-prevention.webp

Como você soluciona erros de redirecionamento de WebView no Android e no iOS? Identifique se a falha envolve uma navegação HTTPS padrão, um esquema de URL personalizado, um URI intent:// do Android ou uma solicitação de nova janela, inspecione a navegação por meio do Chrome DevTools ou do Safari Web Inspector e rastreie o delegado nativo correspondente (shouldOverrideUrlLoading, onCreateWindow, decidePolicyForNavigationAction ou createWebViewWith). Verifique a resolução do aplicativo de destino, listas de permissões de URI, políticas de quadro e interação do usuário, e o roteamento de fallback para isolar erros no nível do contêiner de falhas de despacho do sistema operacional.

Ocorre um erro de redirecionamento de WebView quando um WebView do Android Chromium incorporado ou um WKWebView do iOS WebKit não consegue direcionar uma solicitação de navegação para o destino pretendido. As causas típicas incluem esquemas de URL personalizados sem suporte, solicitações target="_blank" não tratadas, declarações de visibilidade de pacote ausentes e redirecionamentos de fallback rejeitados ou em loop.

Por que os contêineres Android WebView e iOS WKWebView incorporados descartam redirecionamentos

A arquitetura em camadas de redirecionamento de WebView revela políticas nativas e falhas de despacho do sistema operacional.

Ao depurar falhas de redirecionamento, as equipes de engenharia devem separar o comportamento do mecanismo de WebView (como o Chromium ou o WebKit analisa URLs, destinos de quadros e eventos de pop-up) da política do aplicativo host (como o WebViewClient, WebChromeClient, WKNavigationDelegate ou WKUIDelegate fornecido pelo aplicativo avalia tipos de interação do usuário, listas de permissões e handoffs de aplicativos externos). Os navegadores independentes incluem despachantes de URI integrados e manipuladores de handoff de links, enquanto o android.webkit.WebView e o WKWebView da Apple são componentes de renderização incorporados que esperam respostas de rede padrão http:// ou https:// por padrão.

Quando uma página da Web aciona um esquema personalizado (como myapp://product/42) ou um link intent:// do Android sem uma substituição de delegado ativa, o comportamento padrão do contêiner diverge entre as plataformas:

  • Android Chromium WebView: De acordo com a especificação do WebViewClient do Android, se nenhum WebViewClient personalizado for atribuído, o WebView poderá pedir ao Activity Manager para resolver a URL por meio dos manipuladores de sistema disponíveis. Quando um WebViewClient personalizado é atribuído e shouldOverrideUrlLoading retorna false para um esquema personalizado sem suporte, o WebView continua carregando-o dentro do Chromium e renderiza net::ERR_UNKNOWN_URL_SCHEME.
  • iOS WebKit WKWebView: O WebKit rejeita esquemas que não sejam HTTP internamente e aborta a navegação, a menos que o WKNavigationDelegate do host intercepta a solicitação e a encaminhe para o UIApplication, muitas vezes falhando silenciosamente ou acionando NSURLErrorUnsupportedURL.

Observe também que o recurso Promovendo Apps com Banners de Aplicativos Inteligentes da Apple é um recurso de suporte do Safari projetado para navegação independente no Safari, e não uma API de navegação WKWebView incorporada, devendo ser avaliado separadamente dos redirecionamentos de esquemas de URL personalizados no aplicativo.

Resumo Rápido

  • Separar o comportamento do mecanismo da política do host: Isole se a navegação falhou dentro do mecanismo da Web (Chromium/WebKit), dentro de substituições de delegados nativos ou no limite de resolução de pacotes do SO.
  • Inspecionar redirecionamentos ativos antes de codificar: Use o Chrome DevTools (chrome://inspect) e o Safari Web Inspector (isInspectable = true) para capturar correntes de redirecionamento 3xx, estados de targetFrame e sinalizadores de gestos.
  • Aplicar validação de URI e intenção adequada à plataforma: No Android, vincule esquemas personalizados e destinos intent:// de 1 para 1 a pacotes verificados por meio do IntentSanitizer sem sinalizadores de tarefa fornecidos pela página da Web; no iOS, valide estruturas de URI personalizadas completas (confiando em Links Universais onde a identidade verificada de app para domínio for necessária) e rejeite chaves de consulta duplicadas em ambas as plataformas.
  • Aplicar defesa em profundidade para pop-ups e condições de corrida: Conecte o estado da sessão de pop-up do Android estritamente à thread de UI enquanto compreende os limites de callback em shouldInterceptRequest e shouldOverrideUrlLoading, e separe verificações de políticas puras de efeitos colaterais de despacho externo no WKWebView do iOS usando desduplicação no nível de ação e tokens de geração de navegação.

Causas comuns e etapas de verificação para erros de redirecionamento de WebView

Mapeamento de erros de cliente observados para mecanismos subjacentes de falha de contêiner

Use a matriz de diagnóstico abaixo para mapear sintomas observados do WebView para causas raiz comuns da plataforma, etapas de verificação e correções direcionadas:

Sintoma ou Erro Observado Plataforma de Destino Causa Raiz Comum Etapa de Verificação de Diagnóstico Correção Direcionada
WebView exibe net::ERR_UNKNOWN_URL_SCHEME Android WebView WebViewClient personalizado retorna false ou carece de lista de permissões de esquemas Inspecione request.url em shouldOverrideUrlLoading Interceptar URIs permitidos e despachar Intent.ACTION_VIEW vinculado a pacotes de 1 para 1
Travamento silencioso ao tocar em um link de esquema personalizado iOS WKWebView WebKit aborta URI não HTTP quando WKNavigationDelegate retorna .allow Registre navigationAction.request.url em decidePolicyForNavigationAction Roteie esquemas validados via UIApplication.shared.open e passe .cancel
target="_blank" substitui a página atual no WebView Android WebView setSupportMultipleWindows(false) trata novas janelas como carregamentos de nível superior Verifique webView.settings.supportMultipleWindows() Ative setSupportMultipleWindows(true) somente se contêineres pop-up separados forem necessários
target="_blank" não faz nada ou descarta redirecionamentos OAuth 302 Android WebView onCreateWindow está ausente ou o cliente filho bloqueia saltos isRedirect sem hasGesture() Verifique os logs de onCreateWindow, request.isRedirect e shouldInterceptRequest Anexe um WebView pop-up hospedado em visualização com estado de sessão na thread de UI e saltos isRedirect delimitados
Link com target="_blank" ou window.open() não faz nada iOS WKWebView A navegação de nova janela define targetFrame == nil e requer WKUIDelegate Verifique navigationAction.targetFrame == nil Detecte targetFrame == nil em decidePolicyForNavigationAction e trate via WKUIDelegate
O aplicativo de destino está instalado, mas a página de fallback é aberta Android 11+ (targetSdk >= 30) Declarações <queries> ausentes fazem com que resolveActivity() ou queryIntentActivities() retornem resultados incompletos para pacotes invisíveis Adicione registro em nível de aplicativo em torno de resolveActivity() e inspecione a saída via adb logcat Declare intenções <queries> se fizer a pré-verificação, ou invoque startActivity diretamente com captura de ActivityNotFoundException
O redirecionamento por temporizador JavaScript falha ao abrir o aplicativo externo iOS / Android O redirecionamento de script automatizado carece de um sinal de interação do usuário Verifique request.hasGesture() (Android) ou navigationType (iOS) Vincule redirecionamentos a toques diretos do usuário e defina uma política de gestos do host explícita
O Link Universal é carregado dentro de WKWebView em vez do aplicativo de destino iOS WKWebView O contexto de navegação, a relação de domínio ou a navegação JS mantém o carregamento no WebKit Verifique navigationType e host em decidePolicyForNavigationAction Chame UIApplication.shared.open com .universalLinksOnly: true para hosts externos permitidos

Checklist de triagem rápida de redirecionamento de WebView em cinco minutos

  • Etapa 1: Verificar o esquema de protocolo no DevTools: Verifique se a página emitiu um URI https://, esquema personalizado ou intent:// e confirme se não foi bloqueada pela Política de Segurança de Conteúdo (CSP).
  • Etapa 2: Inspecionar a hierarquia de quadros: Verifique se o gatilho se originou dentro de um <iframe> de terceiros (!isMainFrame). Os aplicativos host podem bloquear intencionalmente inicializações de aplicativos externos iniciadas a partir de iframes de terceiros.
  • Etapa 3: Distinguir redirecionamentos de temporizadores: Verifique se uma navegação sem gestos é um redirecionamento de servidor HTTP 3xx autorizado (request.isRedirect no Android) em comparação a um temporizador JavaScript não solicitado.
  • Etapa 4: Verificar gatilhos de nova janela: Confirme se target="_blank" ou window.open() criou uma solicitação de nova janela (targetFrame == nil no iOS ou onCreateWindow no Android).
  • Etapa 5: Verificar a resolução de pacotes do SO: Para aplicativos que visam a API 30+ no Android 11+, confirme se as chamadas de pré-execução resolveActivity() estão falhando devido a declarações <queries> ausentes.

O fluxo de trabalho de diagnóstico a seguir ilustra o caminho de triagem sequencial para isolar falhas de redirecionamento de contêiner:

[WebView Navigation Failure]
          │
          ▼
[Inspect URL + Network + Console via Chrome DevTools / Safari Web Inspector]
          │
          ▼
[Identify Navigation Source]
          │
          ├── App loadUrl() or HTTP POST
          │       │
          │       └── shouldOverrideUrlLoading is NOT invoked; inspect host-side call path
          │
          ├── target="_blank" or window.open()
          │       │
          │       ├── Android (multiple-windows=false) ──> Replaces current WebView page
          │       ├── Android (multiple-windows=true)  ──> Inspect onCreateWindow + shouldInterceptRequest
          │       └── iOS (targetFrame == nil)         ──> Inspect WKNavigationDelegate + WKUIDelegate
          │
          ├── HTTP / HTTPS Navigation
          │       │
          │       └── Inspect Host + Port Allowlist, 3xx Redirects, Universal Link, or App Link matching
          │
          └── Custom Scheme or Chrome intent://
                  │
                  ├── Evaluate User Interaction + Main Frame policy
                  ├── Verify Full URI Structure (Scheme, Host, Port, Path, No Duplicate Query Keys)
                  ├── Sanitize Intent (Reject Explicit Components, Verify 1-to-1 Package, Zero Webpage Flags)
                  ├── Check Target-App Resolution (<queries> / ActivityNotFoundException)
                  └── Validate Fallback Path + Query Allowlist + Monotonic Chain Guard (elapsedRealtime)

Como inspecionar eventos de navegação de WebView usando ferramentas de depuração remota

Como habilitar a depuração remota via Chrome DevTools e ADB Logcat no Android

Antes de modificar delegados nativos, verifique se a página da Web carregada emite o redirecionamento esperado. De acordo com o guia de depuração remota do Chrome DevTools para Android, habilite explicitamente a depuração remota de WebView em compilações de desenvolvimento inspecionando ApplicationInfo.FLAG_DEBUGGABLE e invocando WebView.setWebContentsDebuggingEnabled(true). Nunca envie a depuração habilitada em versões de produção:

// Android - Enable WebView debugging exclusively in debuggable builds
if (applicationInfo.flags and ApplicationInfo.FLAG_DEBUGGABLE != 0) {
    WebView.setWebContentsDebuggingEnabled(true)
}

Conecte o dispositivo via USB, abra chrome://inspect/#devices no Chrome para desktop e monitore a guia Network com Preserve log marcado. Filtre simultaneamente os logs de tempo de execução nativos via adb logcat para capturar ActivityNotFoundException, SecurityException ou logs de wrappers personalizados. Observe que os avisos de descontinuação para a assinatura legada shouldOverrideUrlLoading(WebView, String) aparecem durante a compilação do Android Studio / Gradle e não no adb logcat de tempo de execução:

# Terminal - Filter logcat for custom WebView tags and ActivityTaskManager intent resolution
adb logcat -s "WebViewDebug" "ActivityTaskManager" "PackageManager"

Configurando isInspectable e anexando o Safari Web Inspector e o Console do Xcode no iOS

A partir do iOS 16.4 e macOS 13.3, a Apple exige que os aplicativos aceitem o uso por meio de WKWebView.isInspectable, que assume como padrão false. Ative webView.isInspectable = true dentro de blocos #if DEBUG:

// iOS - Enable Safari Web Inspector opt-in on iOS 16.4+ debug builds
#if DEBUG
if #available(iOS 16.4, *) {
    webView.isInspectable = true
}
#endif

No dispositivo iOS físico, navegue até Ajustes > Apps > Safari > Avançado (em versões anteriores do iOS, Ajustes > Safari > Avançado) e ative o Inspetor da Web. Conecte via USB, abra o menu Desenvolver do Safari para desktop e monitore o Console do Xcode simultaneamente para ver a saída de conclusão nativa de decidePolicyForNavigationAction, createWebViewWith e UIApplication.shared.open.

Android WebView e iOS WKWebView usam manipuladores de pop-up e navegação nativos distintos.

Como resolver quedas silenciosas de novas janelas e gestos de usuário ausentes no iOS WKWebView

Separando a avaliação de políticas de efeitos colaterais em WKNavigationDelegate e WKUIDelegate

Quando um link da Web especifica target="_blank" ou window.open(), o WebKit cria uma solicitação de navegação de nova janela onde navigationAction.targetFrame é nil e envolve tanto o WKNavigationDelegate quanto o WKUIDelegate. Se o aplicativo host não implementar webView(_:createWebViewWithConfiguration:for:windowFeatures:), o WebKit não poderá gerar um WebView secundário e as navegações poderão parecer falhar silenciosamente.

Para evitar inicializações duplicadas de aplicativos externos ou tokens de geração incrementados duas vezes quando ambos os delegados inspecionam uma solicitação, separe a avaliação de política pura (evaluateNavigationPolicy) dos efeitos colaterais de execução e faça a desduplicação pela instância específica de WKNavigationAction (ObjectIdentifier(navigationAction)) em vez de confiar puramente em um limite de tempo bruto que poderia suprimir cliques repetidos rápidos e intencionais de um usuário. Avalie navigationAction.targetFrame == nil diretamente em decidePolicyForNavigationAction: se a avaliação retornar um plano de handoff externo, execute-o uma vez (registrando o identificador de WKNavigationAction) e passe .cancel; se retornar .allowInWebView para uma URL de pop-up permitida, passe .allow para que createWebViewWith carregue o pop-up com segurança. Sempre verifique a ordem exata dos callbacks de delegado nas versões de iOS de destino.

Contexto de Link Universal, segurança de corrida assíncrona e identidade de esquema personalizado

O handoff de Links Universais depende do contexto de navegação de origem, da relação de domínio e da configuração de Domínios Associados (verificada por meio do arquivo apple-app-site-association do servidor de destino). A nota técnica TN3155: Depurando links universais da Apple documenta como a navegação no mesmo domínio no Safari favorece a permanência no navegador, enquanto subdomínios distintos alteram a elegibilidade. Sempre teste o comportamento de Domínios Associados nas versões de iOS de destino dentro de WKWebView.

Ao chamar UIApplication.shared.open(url, options: [.universalLinksOnly: true]), proteja-se contra condições de corrida de navegação assíncrona: se um usuário iniciar qualquer tentativa subsequente de navegação no quadro principal enquanto o sistema processa o handoff do Link Universal, um manipulador de conclusão desprotegido que retorne false poderá substituir o estado de navegação mais recente do usuário. Incremente um token monotônico activeNavigationGeneration em cada nova avaliação de navegação do quadro principal (incluindo tentativas bloqueadas ou redirecionadas), de modo que qualquer fallback assíncrono anterior pendente seja invalidado imediatamente, e verifique self.activeNavigationGeneration == requestGeneration junto com self.isViewLoaded && self.view.window != nil antes de recarregar as URLs de fallback.

Observe dois limites de segurança estritos:

  • Classificação de WKNavigationType: De acordo com a documentação do WKNavigationType da Apple, formSubmitted representa uma solicitação para enviar um formulário em vez de um toque em link, e os scripts de página podem enviar formulários programaticamente. Restrinça os handoffs de aplicativos externos a eventos .linkActivated classificados pelo WebKit combinados com sourceFrame.isMainFrame e listas de permissões completas de URI, em vez de tratar .linkActivated como um token de gesto criptográfico isolado.
  • Exclusividade de esquema personalizado e poluição de parâmetros: De acordo com o guia da Apple sobre Como definir um esquema de URL personalizado para seu aplicativo, vários aplicativos podem reivindicar o mesmo esquema personalizado. isAllowedCustomURL(_:) valida a estrutura do URI (esquema, host, porta padrão nil, padrão de caminho, sem userinfo/fragmento e rejeição de chaves de consulta duplicadas), e não a identidade do Bundle ID de destino. Use Links Universais verificados por domínio sempre que a vinculação de identidade do aplicativo for necessária.

Aviso de Arquitetura de Referência: A implementação a seguir é uma arquitetura de referência defensiva. Valide a disponibilidade da API, a ordem dos delegados e o comportamento do ciclo de vida em relação às versões exatas do AndroidX e iOS usadas pelo seu aplicativo.

// iOS - WebViewContainerController.swift
// Reference architecture: compile and test against your specific project targets (iOS 15.0–18.0)
import UIKit
import WebKit

final class WebViewContainerController: UIViewController, WKNavigationDelegate, WKUIDelegate {

    private enum NavigationPlan: Equatable {
        case allowInWebView
        case launchCustomScheme(URL)
        case attemptUniversalLink(URL)
        case block
    }

    private var webView: WKWebView!

    // Explicit allowlist for external custom URL schemes, hosts, and query keys
    private let allowedCustomSchemes: Set<String> = ["myapp", "partnerapp"]
    private let allowedCustomHosts: Set<String> = ["open", "product", "promo"]
    private let allowedCustomQueryKeys: Set<String> = ["id", "ref", "promo"]

    // Explicit allowlist for HTTPS hosts permitted inside the primary WebView container
    private let allowedWebHosts: Set<String> = [
        "example.com",
        "m.example.com",
        "links.example.com"
    ]

    // Isolated allowlists specifically for child popup windows (target="_blank")
    private let allowedPopupHosts: Set<String> = ["example.com", "auth.example.com"]
    private let allowedPopupPathPrefixes: [String] = ["/oauth", "/popup", "/window"]

    // External Universal Link hosts that attempt native app handoff on link activation
    private let externalUniversalLinkHosts: Set<String> = ["links.example.com"]

    // Monotonic navigation generation token incremented on every new main-frame navigation attempt
    private var activeNavigationGeneration: UInt64 = 0

    // Action-level deduplication preventing duplicate dispatches for the same WKNavigationAction
    private var dispatchedActionIDs: [ObjectIdentifier] = []
    private let maxTrackedActionIDs = 16

    // Monotonic-uptime TTL-bounded bypass cache keyed by normalized Universal Link key
    private var bypassedUniversalLinkKeys: [String: TimeInterval] = [:]
    private let maxBypassedKeys = 10
    private let bypassTTLSeconds: TimeInterval = 300
    // Adapt significant query keys to match your application's actual routing parameters
    private let significantLoopQueryKeys: Set<String> = ["id"]

    override func viewDidLoad() {
        super.viewDidLoad()

        let configuration = WKWebViewConfiguration()
        webView = WKWebView(frame: view.bounds, configuration: configuration)
        webView.autoresizingMask = [.flexibleWidth, .flexibleHeight]
        webView.navigationDelegate = self
        webView.uiDelegate = self

        #if DEBUG
        if #available(iOS 16.4, *) {
            webView.isInspectable = true
        }
        #endif

        view.addSubview(webView)
    }

    // MARK: - WKNavigationDelegate

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

        let isMainFrame = navigationAction.sourceFrame.isMainFrame
        let isNewWindow = (navigationAction.targetFrame == nil)

        // Increment generation token on every main-frame navigation attempt (including blocked attempts)
        // so any pending prior asynchronous Universal Link fallback is invalidated immediately.
        if isMainFrame && !isNewWindow {
            activeNavigationGeneration &+= 1
        }
        let requestGeneration = activeNavigationGeneration

        let plan = evaluateNavigationPolicy(
            url: url,
            navigationType: navigationAction.navigationType,
            isMainFrame: isMainFrame,
            isNewWindow: isNewWindow
        )

        switch plan {
        case .allowInWebView:
            decisionHandler(.allow)

        case .launchCustomScheme(let targetURL):
            if isMainFrame { activeNavigationGeneration &+= 1 }
            executeExternalDispatchOnce(
                action: navigationAction,
                url: targetURL,
                isUniversalLink: false,
                requestGeneration: activeNavigationGeneration
            )
            decisionHandler(.cancel)

        case .attemptUniversalLink(let targetURL):
            if isMainFrame { activeNavigationGeneration &+= 1 }
            let currentGen = activeNavigationGeneration
            executeExternalDispatchOnce(
                action: navigationAction,
                url: targetURL,
                isUniversalLink: true,
                requestGeneration: currentGen
            )
            decisionHandler(.cancel)

        case .block:
            decisionHandler(.cancel)
        }
    }

    // MARK: - WKUIDelegate (Handles target="_blank" and window.open)

    func webView(
        _ webView: WKWebView,
        createWebViewWith configuration: WKWebViewConfiguration,
        for navigationAction: WKNavigationAction,
        windowFeatures: WKWindowFeatures
    ) -> WKWebView? {
        guard navigationAction.targetFrame == nil,
              let url = navigationAction.request.url else {
            return nil
        }

        let isMainFrame = navigationAction.sourceFrame.isMainFrame
        if isMainFrame {
            activeNavigationGeneration &+= 1
        }
        let currentGen = activeNavigationGeneration

        let plan = evaluateNavigationPolicy(
            url: url,
            navigationType: navigationAction.navigationType,
            isMainFrame: isMainFrame,
            isNewWindow: true
        )

        switch plan {
        case .allowInWebView:
            webView.load(navigationAction.request)

        case .launchCustomScheme(let targetURL):
            executeExternalDispatchOnce(
                action: navigationAction,
                url: targetURL,
                isUniversalLink: false,
                requestGeneration: currentGen
            )

        case .attemptUniversalLink(let targetURL):
            executeExternalDispatchOnce(
                action: navigationAction,
                url: targetURL,
                isUniversalLink: true,
                requestGeneration: currentGen
            )

        case .block:
            break
        }

        return nil
    }

    // MARK: - Pure Navigation Policy Evaluation (Zero Side Effects)

    private func evaluateNavigationPolicy(
        url: URL,
        navigationType: WKNavigationType,
        isMainFrame: Bool,
        isNewWindow: Bool
    ) -> NavigationPlan {
        guard let scheme = url.scheme?.lowercased() else {
            return .block
        }

        let isLinkActivated = (navigationType == .linkActivated)

        // 1. Evaluate non-HTTP/HTTPS Custom URL Schemes
        // Note: Custom scheme allowlisting validates URI structure; it cannot guarantee target Bundle ID identity.
        if scheme != "http" && scheme != "https" {
            guard isMainFrame, isLinkActivated, isAllowedCustomURL(url) else {
                return .block
            }
            return .launchCustomScheme(url)
        }

        // 2. Enforce HTTPS-only, default port (nil or 443), and Host Allowlists
        let targetHost = url.host?.lowercased()
        if isNewWindow {
            guard isMainFrame, isLinkActivated, isAllowedPopupWebURL(url) else {
                return .block
            }
        } else {
            guard isAllowedWebURL(url), let host = targetHost, allowedWebHosts.contains(host) else {
                return .block
            }
        }

        // 3. Evaluate Universal Link Handoffs for designated external hosts on link activation
        if let host = targetHost,
           externalUniversalLinkHosts.contains(host),
           isMainFrame,
           isLinkActivated,
           let loopKey = universalLinkLoopKey(for: url),
           !isBypassedKeyActive(loopKey) {
            return .attemptUniversalLink(url)
        }

        return .allowInWebView
    }

    // MARK: - Action-Level Deduplicated External Dispatch Execution

    private func executeExternalDispatchOnce(
        action: WKNavigationAction,
        url: URL,
        isUniversalLink: Bool,
        requestGeneration: UInt64
    ) {
        let actionID = ObjectIdentifier(action)
        if dispatchedActionIDs.contains(actionID) {
            return
        }
        if dispatchedActionIDs.count >= maxTrackedActionIDs {
            dispatchedActionIDs.removeFirst()
        }
        dispatchedActionIDs.append(actionID)

        if isUniversalLink {
            guard let loopKey = universalLinkLoopKey(for: url) else { return }
            UIApplication.shared.open(url, options: [.universalLinksOnly: true]) { [weak self] success in
                // Verify view lifecycle AND generation token to prevent stale async fallback overwrites
                guard let self = self,
                      self.isViewLoaded,
                      self.view.window != nil,
                      self.activeNavigationGeneration == requestGeneration else {
                    return
                }
                if !success {
                    self.recordBypassedKey(loopKey)
                    self.webView.load(URLRequest(url: url))
                }
            }
        } else {
            UIApplication.shared.open(url, options: [:]) { success in
                if !success {
                    print("[WebViewDebug] Failed to launch custom scheme (app may not be installed)")
                }
            }
        }
    }

    private func isAllowedWebURL(_ url: URL) -> Bool {
        guard let components = URLComponents(url: url, resolvingAgainstBaseURL: false),
              let scheme = components.scheme?.lowercased(),
              scheme == "https",
              components.user == nil,
              components.password == nil,
              (components.port == nil || components.port == 443) else {
            return false
        }
        return true
    }

    private func isAllowedPopupWebURL(_ url: URL) -> Bool {
        guard isAllowedWebURL(url),
              let components = URLComponents(url: url, resolvingAgainstBaseURL: false),
              let host = components.host?.lowercased(),
              allowedPopupHosts.contains(host),
              components.fragment == nil else {
            return false
        }

        let path = components.path
        return allowedPopupPathPrefixes.contains { path == $0 || path.hasPrefix("\($0)/")} 
    }

    private func isAllowedCustomURL(_ url: URL) -> Bool {
        guard let components = URLComponents(url: url, resolvingAgainstBaseURL: false),
              let scheme = components.scheme?.lowercased(),
              let host = components.host?.lowercased(),
              allowedCustomSchemes.contains(scheme),
              allowedCustomHosts.contains(host),
              components.user == nil,
              components.password == nil,
              components.port == nil, // Reject explicit ports on custom schemes
              components.fragment == nil else {
            return false
        }

        let path = components.path
        if !path.isEmpty &&
           path.range(of: "^/[A-Za-z0-9/_-]{1,64}$", options: .regularExpression) == nil {
            return false
        }

        if let queryItems = components.queryItems {
            var seenKeys = Set<String>()
            for item in queryItems {
                if seenKeys.contains(item.name) {
                    return false
                }
                seenKeys.insert(item.name)

                guard allowedCustomQueryKeys.contains(item.name),
                      let value = item.value,
                      value.count <= 64,
                      value.range(of: "^[A-Za-z0-9_-]+$", options: .regularExpression) != nil else {
                    return false
                }
            }
        }
        return true
    }

    private func universalLinkLoopKey(for url: URL) -> String? {
        guard let components = URLComponents(url: url, resolvingAgainstBaseURL: false),
              let scheme = components.scheme?.lowercased(),
              let host = components.host?.lowercased() else {
            return nil
        }

        let portPart = (components.port != nil && components.port != 443) ? ":\(components.port!)" : ""
        let significantParams = (components.queryItems ?? [])
            .filter { significantLoopQueryKeys.contains($0.name) }
            .sorted { $0.name < $1.name }
            .map { "\($0.name)=\($0.value ?? "")" }
            .joined(separator: "&")

        let querySuffix = significantParams.isEmpty ? "" : "?\(significantParams)"
        return "\(scheme)://\(host)\(portPart)\(components.path)\(querySuffix)"
    }

    private func isBypassedKeyActive(_ key: String) -> Bool {
        let now = ProcessInfo.processInfo.systemUptime
        bypassedUniversalLinkKeys = bypassedUniversalLinkKeys.filter {
            (now - $0.value) < bypassTTLSeconds
        }
        return bypassedUniversalLinkKeys[key] != nil
    }

    private func recordBypassedKey(_ key: String) {
        let now = ProcessInfo.processInfo.systemUptime
        bypassedUniversalLinkKeys = bypassedUniversalLinkKeys.filter {
            (now - $0.value) < bypassTTLSeconds
        }
        if bypassedUniversalLinkKeys.count >= maxBypassedKeys,
           let oldestKey = bypassedUniversalLinkKeys.min(by: { $0.value < $1.value })?.key {
            bypassedUniversalLinkKeys.removeValue(forKey: oldestKey)
        }
        bypassedUniversalLinkKeys[key] = now
    }
}

Corrigindo ERR_UNKNOWN_URL_SCHEME e falhas de visibilidade de pacotes no Android WebView

Callacks descontinuados, hasGesture() e limites de POST

O Android descontinuou shouldOverrideUrlLoading(WebView, String) na API nível 24 em favor de shouldOverrideUrlLoading(WebView, WebResourceRequest). O WebResourceRequest fornece isForMainFrame, isRedirect e hasGesture(). Observe duas restrições oficiais da plataforma: shouldOverrideUrlLoading não é invocado para chamadas webView.loadUrl() iniciadas pelo host ou navegações HTTP POST, e hasGesture() pode retornar false para redirecionamentos JavaScript assíncronos legítimos ou saltos 302 do lado do servidor.

Tratamento de pop-up de defesa em profundidade e isolamento de thread em WebChromeClient.onCreateWindow

O comportamento de pop-up do Android depende de WebSettings.setSupportMultipleWindows. Se o seu aplicativo não exigir pop-ups interativos, manter setSupportMultipleWindows(false) (ou retornar false de onCreateWindow) evita que iframes de terceiros abram contêineres secundários — ou abra destinos verificados por meio de um ponto de entrada explícito e controlado pelo host.

Quando setSupportMultipleWindows(true) está habilitado, WebChromeClient.onCreateWindow não fornece a URL de destino em sua assinatura de callback, e nenhum callback único cobre todos os vetores de navegação. Compreender o modelo de thread exato e os limites de callback é essencial para uma abordagem de referência de defesa em profundidade:

  • shouldOverrideUrlLoading (Thread de UI — Proprietário do estado de navegação e sessão): É executado exclusivamente na thread de UI e possui todo o estado mutável da sessão de pop-up (isInitialTransportLoad, isAuthorizedPopupSession, popupRedirectHops e popupChainStartMs). Somente quando um carregamento inicial verificado ou um gesto direto do usuário corresponde a policy.isAllowedPopupUri, o shouldOverrideUrlLoading autoriza a sessão para redirecionamentos HTTP 302 limitados subsequentes (request.isRedirect), garantindo que as correntes de redirecionamento retornem a uma sessão autorizada em vez de confiar em redirecionamentos arbitrários.
  • shouldInterceptRequest (Thread de E/S do WebView em segundo plano — Proteção sem estado e somente leitura): É executado em uma thread de WebView que não é de UI. Como nunca deve modificar o estado da sessão da thread de UI, ele opera estritamente como uma verificação de política sem estado e somente leitura em safeClient.policy (bloqueando solicitações HTTP/HTTPS do quadro principal que falham em isAllowedPopupUri e despachando disposeActivePopup() na thread principal). Observe que, de acordo com a documentação do Android, shouldInterceptRequest é chamado apenas para a URL do recurso inicial, não para URLs de redirecionamento HTTP 302 subsequentes; as URLs de redirecionamento subsequentes devem ser avaliadas por shouldOverrideUrlLoading.
  • onPageStarted (Thread de UI — Verificação de fallback de início de navegação): É executado quando o carregamento do quadro principal começa (não como um filtro pré-navegação). Ele atualiza o banner de origem visível para transparência do usuário e fornece uma verificação de fallback de início de navegação chamando stopLoading() e disposeActivePopup() se um destino não aprovado começar a carregar.

Sempre teste URLs iniciais maliciosas, correntes HTTP 302 entre domínios, redirecionamentos 302 consecutivos, target="_blank", window.open() e gatilhos de iframe de terceiros em builds de WebView físicos de destino.

Visibilidade de pacotes no Android 11+ e orientação descontinuada sobre canOpenURL

Sob as regras de visibilidade de pacotes do Android, aplicativos executados no Android 11 (API nível 30) ou superior e direcionados à API nível 30 ou superior (targetSdk >= 30) recebem resultados nulos ou vazios de intent.resolveActivity() ou queryIntentActivities(), a menos que os aplicativos de destino sejam declarados em <queries> no AndroidManifest.xml. O Android recomenda chamar startActivity(intent) diretamente dentro de um bloco try/catch para ActivityNotFoundException e SecurityException, em vez de expandir <queries>.

No iOS, a Apple descontinuou UIApplication.canOpenURL(_:) e recomenda tentar UIApplication.shared.open(_:options:completionHandler:) diretamente e tratar qualquer falha no manipulador de conclusão (ou migrar para Links Universais para remover a pré-validação de esquemas). O parâmetro LSApplicationQueriesSchemes no Info.plist só é necessário se o código legado continuar chamando canOpenURL(_:), enquanto open(_:options:completionHandler:) não exige a declaração de esquemas no Info.plist. Tanto <queries> quanto LSApplicationQueriesSchemes controlam a visibilidade de consultas — eles não são listas de permissões de segurança para validar URIs da Web não confiáveis.

<!-- Manifest Fragment: Merge <queries> into your existing AndroidManifest.xml -->
<!-- Required for targetSdk >= 30 on Android 11+ ONLY if calling resolveActivity or queryIntentActivities -->
<queries>
    <intent>
        <action android:name="android.intent.action.VIEW" />
        <category android:name="android.intent.category.BROWSABLE" />
        <data android:scheme="myapp" />
    </intent>
    <intent>
        <action android:name="android.intent.action.VIEW" />
        <category android:name="android.intent.category.BROWSABLE" />
        <data android:scheme="partnerapp" />
    </intent>
</queries>
<!-- Info.plist Fragment: Insert under the root <dict> in Info.plist -->
<!-- Legacy: Required on iOS ONLY if calling deprecated UIApplication.shared.canOpenURL; open(_:options:completionHandler:) does not require this key -->
<key>LSApplicationQueriesSchemes</key>
<array>
    <string>myapp</string>
    <string>partnerapp</string>
</array>

Como analisar com segurança URIs de intent do Chrome e evitar loops de redirecionamento

Protegendo Intent.parseUri contra explorações de redirecionamento de intent

Os URIs intent:// do Android codificam um esquema de destino, pacote e URL de fallback (S.browser_fallback_url). A análise de URIs da Web não confiáveis via Intent.parseUri(rawUri, Intent.URI_INTENT_SCHEME) introduz riscos de Redirecionamento de Intent detalhados no guia de segurança de redirecionamento de intent do Android e no Guia de Teste de Segurança de Aplicativos Móveis da OWASP (MASTG). Mesmo com o Android 16 (API 36) adicionando endurecimento padrão no nível da plataforma, os aplicativos devem impor validação rigorosa antes de despachar Intents.

A validação de URI em camadas bloqueia intents de WebView não seguros antes do despacho para o aplicativo externo.

Para implementar a validação de falha fechada usando o utilitário IntentSanitizer do AndroidX (androidx.core:core:1.9.0+ ou androidx.core:core-ktx:1.9.0+, que inclui o androidx.core:core) sem disparar conflitos de exclusão mútua do builder entre allowAnyComponent() e os métodos de lista de permissões de pacotes/componentes:

  • Verificações de Pré-Sanitização: Rejeite imediatamente intents que carreguem campos component ou selector não nulos (parsedIntent.component != null || parsedIntent.selector != null). Extraia e remova browser_fallback_url antes da sanitização e verifique nativamente se parsedIntent.data?.scheme mapeia de 1 para 1 para parsedIntent.package via customSchemeTargetPackages (garantindo que myapp:// seja resolvido estritamente para com.example.target, nunca para outro pacote parceiro).
  • Execução do Sanitizer: Limpe temporariamente parsedIntent.package = null na cópia não confiável, execute IntentSanitizer.Builder().allowAnyComponent().allowAction(Intent.ACTION_VIEW).allowCategory(Intent.CATEGORY_BROWSABLE).allowData { ... }.build().sanitizeByThrowing(parsedIntent) (sem sinalizadores de tarefa fornecidos pela página da Web) e reatribua o expectedPackage validado e CATEGORY_BROWSABLE no Intent sanitizado de propriedade do host antes das declarações de pós-sanitização.
  • Sinalizadores de inicialização conscientes do contexto: Injete Intent.FLAG_ACTIVITY_NEW_TASK dentro do despachante nativo (launchWithContextSafety) somente quando view.context !is Activity. Para verificação de associação de domínio a aplicativo, prefira Links de Aplicativos Android HTTPS verificados (assetlinks.json).

Evitando loops infinitos de fallback com estado de corrente monotônico

Quando startActivity lança ActivityNotFoundException, valide browser_fallback_url com uma verificação dedicada isAllowedFallbackUri(uri) (estritamente HTTPS, porta padrão, host verificado, prefixos explícitos de caminho de fallback, sem chaves de consulta duplicadas e sem fragmentos). Rejeite representações de portas explícitas em esquemas personalizados verificando tanto uri.port == -1 quanto !uri.encodedAuthority.orEmpty().contains(":").

Rastreie correntes de fallback usando SystemClock.elapsedRealtime() (evitando saltos de relógio de parede System.currentTimeMillis()), isole correntes via fallbackLoopKey() (sem a canonização completa da IETF RFC 3986), redefina o estado por meio de um wrapper de host explícito loadNewNavigation(webView, url) e roteie fallbacks de pop-up para o contêiner primário via onPopupFallbackHandoff para que domínios não autorizados nunca sejam carregados dentro de uma caixa de diálogo pop-up.

Aviso de Arquitetura de Referência: A implementação a seguir é uma arquitetura de referência defensiva. Valide a disponibilidade da API, a ordem dos delegados e o comportamento do ciclo de vida em relação às versões exatas do AndroidX e iOS usadas pelo seu aplicativo.

// Android - SafeWebViewModules.kt
// Reference architecture: compile and test against your specific project targets
// Requires androidx.core:core:1.9.0+ (or androidx.core:core-ktx:1.9.0+) for IntentSanitizer; targets minSdk >= 24.
package com.example.hostapp.webview

import android.app.Activity
import android.app.Dialog
import android.content.ActivityNotFoundException
import android.content.Intent
import android.content.pm.ApplicationInfo
import android.net.Uri
import android.os.Bundle
import android.os.Message
import android.os.SystemClock
import android.util.Log
import android.view.ViewGroup
import android.widget.TextView
import android.webkit.WebChromeClient
import android.webkit.WebResourceRequest
import android.webkit.WebResourceResponse
import android.webkit.WebView
import android.webkit.WebViewClient
import androidx.appcompat.app.AppCompatActivity
import androidx.core.content.IntentSanitizer
import java.io.ByteArrayInputStream
import java.net.URISyntaxException

// 1. Policy Module (Immutable / Thread-Safe for read-only access from IO & UI threads)
class CustomUriPolicy(
    val customSchemeTargetPackages: Map<String, String> = mapOf(
        "myapp" to "com.example.target",
        "partnerapp" to "com.partner.app"
    ),
    val allowedCustomHosts: Set<String> = setOf("open", "product", "promo"),
    val allowedCustomQueryKeys: Set<String> = setOf("id", "ref", "promo"),
    val allowedWebHosts: Set<String> = setOf("example.com", "downloads.example.com"),
    val allowedFallbackHosts: Set<String> = setOf("downloads.example.com", "example.com"),
    val allowedFallbackPathPrefixes: List<String> = listOf("/download", "/app", "/landing"),
    val allowedFallbackQueryKeys: Set<String> = setOf("id", "ref", "promo", "utm_source"),
    // Isolated allowlists explicitly for popup windows; distinct from general web hosts
    val allowedPopupHosts: Set<String> = setOf("example.com", "auth.example.com"),
    val allowedPopupPathPrefixes: List<String> = listOf("/oauth", "/popup", "/window")
) {
    val allowedCustomSchemes: Set<String> get() = customSchemeTargetPackages.keys
    val allowedTargetPackages: Set<String> get() = customSchemeTargetPackages.values.toSet()

    private val pathPattern = Regex("^/[A-Za-z0-9/_-]{1,64}$")
    private val queryValuePattern = Regex("^[A-Za-z0-9_-]{1,64}$")

    fun isAllowedWebUri(uri: Uri): Boolean {
        val scheme = uri.scheme?.lowercase() ?: return false
        val host = uri.host?.lowercase() ?: return false
        return scheme == "https" &&
            host in allowedWebHosts &&
            (uri.port == -1 || uri.port == 443) &&
            uri.userInfo == null
    }

    fun isAllowedPopupUri(uri: Uri): Boolean {
        val scheme = uri.scheme?.lowercase() ?: return false
        val host = uri.host?.lowercase() ?: return false
        if (scheme != "https" || host !in allowedPopupHosts) return false
        if ((uri.port != -1 && uri.port != 443) || uri.userInfo != null || uri.fragment != null) return false

        val path = uri.path.orEmpty()
        return allowedPopupPathPrefixes.any { path == it || path.startsWith("$it/") } && pathPattern.matches(path)
    }

    fun isAllowedFallbackUri(uri: Uri): Boolean {
        val scheme = uri.scheme?.lowercase() ?: return false
        val host = uri.host?.lowercase() ?: return false
        if (scheme != "https" || host !in allowedFallbackHosts) return false
        if ((uri.port != -1 && uri.port != 443) || uri.userInfo != null || uri.fragment != null) {
            return false
        }

        val path = uri.path.orEmpty()
        if (allowedFallbackPathPrefixes.none { path == it || path.startsWith("$it/") } ||
            !pathPattern.matches(path)
        ) {
            return false
        }

        // Validate query keys, enforce value syntax, and reject duplicate keys
        val queryNames = uri.queryParameterNames
        for (paramName in queryNames) {
            if (paramName !in allowedFallbackQueryKeys) return false
            val values = uri.getQueryParameters(paramName)
            if (values.size != 1 || !queryValuePattern.matches(values[0])) return false
        }
        return true
    }

    fun isAllowedCustomUri(uri: Uri): Boolean {
        val scheme = uri.scheme?.lowercase() ?: return false
        val host = uri.host?.lowercase() ?: return false
        if (scheme !in allowedCustomSchemes || host !in allowedCustomHosts) return false

        // Reject network ports strictly by checking both uri.port == -1 and raw authority colon absence
        val rawAuthority = uri.encodedAuthority.orEmpty()
        if (uri.userInfo != null || uri.port != -1 || rawAuthority.contains(":") || uri.fragment != null) {
            return false
        }

        val path = uri.path.orEmpty()
        if (path.isNotEmpty() && !pathPattern.matches(path)) return false

        // Validate query keys, enforce value syntax, and reject duplicate keys
        val queryNames = uri.queryParameterNames
        for (paramName in queryNames) {
            if (paramName !in allowedCustomQueryKeys) return false
            val values = uri.getQueryParameters(paramName)
            if (values.size != 1 || !queryValuePattern.matches(values[0])) return false
        }
        return true
    }
}

// 2. Fallback Manager: Monotonic Elapsed-Time Chain State (Isolates active chain from repeat sessions)
class FallbackLoopGuard(
    private val maxHopsPerChain: Int = 3,
    private val chainTtlMs: Long = 30_000L,
    private val significantQueryKeys: Set<String> = setOf("id")
) {
    private var chainStartElapsedMs: Long = 0L
    private var fallbackHopCount: Int = 0
    private val visitedInCurrentChain = mutableSetOf<String>()

    fun resetChain() {
        chainStartElapsedMs = 0L
        fallbackHopCount = 0
        visitedInCurrentChain.clear()
    }

    fun canLoadFallback(uri: Uri, currentWebViewUrl: String?): Boolean {
        val now = SystemClock.elapsedRealtime()

        if (chainStartElapsedMs == 0L || (now - chainStartElapsedMs) > chainTtlMs) {
            chainStartElapsedMs = now
            fallbackHopCount = 0
            visitedInCurrentChain.clear()
        }

        val loopKey = fallbackLoopKey(uri)
        val currentKey = currentWebViewUrl?.let { fallbackLoopKey(Uri.parse(it)) }

        if (fallbackHopCount >= maxHopsPerChain ||
            loopKey == currentKey ||
            loopKey in visitedInCurrentChain
        ) {
            return false
        }

        visitedInCurrentChain.add(loopKey)
        fallbackHopCount++
        return true
    }

    // Application-level loop key normalizing default HTTPS port and preserving significant query keys
    private fun fallbackLoopKey(uri: Uri): String {
        val scheme = uri.scheme?.lowercase().orEmpty()
        val host = uri.host?.lowercase().orEmpty()
        val portSuffix = if (uri.port != -1 && uri.port != 443) ":${uri.port}" else ""
        val path = uri.path.orEmpty()

        val sigParams = uri.queryParameterNames
            .filter { it in significantQueryKeys }
            .sorted()
            .joinToString("&") { key -> "$key=${uri.getQueryParameter(key).orEmpty()}" }

        val querySuffix = if (sigParams.isEmpty()) "" else "?$sigParams"
        return "$scheme://$host$portSuffix$path$querySuffix"
    }
}

// 3. Router & Fail-Closed IntentSanitizer WebViewClient (UI Thread Only)
class SafeRedirectWebViewClient(
    val policy: CustomUriPolicy = CustomUriPolicy(),
    val loopGuard: FallbackLoopGuard = FallbackLoopGuard(),
    private val onPopupFallbackHandoff: ((fallbackUri: Uri) -> Unit)? = null
) : WebViewClient() {

    // Explicit host-initiated navigation API that resets fallback chain state prior to loadUrl()
    fun loadNewNavigation(webView: WebView, url: String) {
        val targetUri = Uri.parse(url)
        if (!policy.isAllowedWebUri(targetUri)) {
            Log.w("WebViewDebug", "Blocked host-initiated navigation to untrusted URL")
            return
        }
        loopGuard.resetChain()
        webView.loadUrl(url)
    }

    // Dedicated fallback loader with internal validation preserving active chain state
    fun loadFallbackNavigation(webView: WebView, fallbackUri: Uri) {
        if (!policy.isAllowedFallbackUri(fallbackUri)) {
            Log.w("WebViewDebug", "Blocked untrusted fallback navigation attempt")
            return
        }
        webView.loadUrl(fallbackUri.toString())
    }

    override fun shouldOverrideUrlLoading(view: WebView, request: WebResourceRequest): Boolean {
        return handleNavigation(
            view = view,
            uri = request.url,
            isForMainFrame = request.isForMainFrame,
            hasUserGesture = request.hasGesture(),
            isPopupContext = false
        )
    }

    fun handleNavigation(
        view: WebView,
        uri: Uri?,
        isForMainFrame: Boolean,
        hasUserGesture: Boolean,
        isPopupContext: Boolean
    ): Boolean {
        val targetUri = uri ?: return true
        val scheme = targetUri.scheme?.lowercase() ?: return true

        // 1. Enforce HTTPS-only & Web Host Allowlist on all HTTP/HTTPS navigations
        if (scheme == "http" || scheme == "https") {
            if (!policy.isAllowedWebUri(targetUri)) {
                Log.w("WebViewDebug", "Blocked non-HTTPS, custom-port, or untrusted web host")
                return true
            }
            if (hasUserGesture && isForMainFrame) {
                loopGuard.resetChain()
            }
            return false
        }

        // 2. Enforce main-frame and user-gesture constraints on external app launches
        if (!isForMainFrame || !hasUserGesture) {
            Log.w("WebViewDebug", "Blocked non-main-frame or non-gesture scheme: $scheme")
            return true
        }

        // 3. Parse and fail-closed sanitize Chrome intent:// URIs
        if (scheme == "intent") {
            return handleIntentUri(view, targetUri.toString(), isPopupContext)
        }

        // 4. Validate and explicitly bind allowlisted custom URL schemes to 1-to-1 verified target packages
        if (policy.isAllowedCustomUri(targetUri)) {
            val expectedPackage = policy.customSchemeTargetPackages[scheme] ?: return true
            val viewIntent = Intent(Intent.ACTION_VIEW, targetUri).apply {
                addCategory(Intent.CATEGORY_BROWSABLE)
                `package` = expectedPackage
            }
            launchIntentSafely(view, viewIntent)
            return true
        }

        // 5. Block all unrecognized schemes
        Log.w("WebViewDebug", "Blocked unrecognized URL scheme: $scheme")
        return true
    }

    // UI-Thread Navigation Evaluator for child popup WebViews tying 302 redirects to authorized sessions
    fun handlePopupNavigation(
        view: WebView,
        uri: Uri?,
        isForMainFrame: Boolean,
        hasUserGesture: Boolean,
        isRedirect: Boolean,
        isInitialTransportLoad: Boolean,
        isAuthorizedPopupSession: Boolean,
        onAuthorizedInitialSession: () -> Unit,
        canProceedPopupRedirect: () -> Boolean
    ): Boolean {
        val targetUri = uri ?: return true
        val scheme = targetUri.scheme?.lowercase() ?: return true

        if (scheme == "http" || scheme == "https") {
            if (!isForMainFrame) {
                Log.w("WebViewDebug", "Blocked subframe HTTPS navigation inside popup")
                return true
            }
            if (!policy.isAllowedPopupUri(targetUri)) {
                Log.w("WebViewDebug", "Blocked untrusted popup HTTPS host or path navigation")
                return true
            }
            // Authorize session only on UI thread when initial load or user tap matches allowlist
            if (isInitialTransportLoad || hasUserGesture) {
                onAuthorizedInitialSession()
                return false
            }
            // Permit bounded server-side 302 redirects ONLY for previously authorized popup sessions
            if (isRedirect && isAuthorizedPopupSession && canProceedPopupRedirect()) {
                return false
            }

            Log.w("WebViewDebug", "Blocked unauthorized redirect or non-gesture popup navigation")
            return true
        }

        return handleNavigation(view, targetUri, isForMainFrame, hasUserGesture, isPopupContext = true)
    }

    private fun handleIntentUri(view: WebView, rawUri: String, isPopupContext: Boolean): Boolean {
        val parsedIntent = try {
            Intent.parseUri(rawUri, Intent.URI_INTENT_SCHEME)
        } catch (e: URISyntaxException) {
            Log.w("WebViewDebug", "Malformed intent URI syntax")
            return true
        }

        val fallbackUrl = parsedIntent.getStringExtra("browser_fallback_url")
        parsedIntent.removeExtra("browser_fallback_url")

        // 1-to-1 Binding: Extract target scheme and validate natively against expected target package
        val dataUri = parsedIntent.data ?: return true
        val targetScheme = dataUri.scheme?.lowercase() ?: return true
        val expectedPackage = policy.customSchemeTargetPackages[targetScheme] ?: run {
            Log.w("WebViewDebug", "Blocked intent with unmapped custom scheme: $targetScheme")
            return true
        }

        val rawPackage = parsedIntent.`package`
        if (rawPackage != expectedPackage) {
            Log.w("WebViewDebug", "Blocked intent package mismatch: expected $expectedPackage")
            return true
        }

        // Reject webpage-specified explicit components and selectors immediately
        if (parsedIntent.component != null || parsedIntent.selector != null) {
            Log.w("WebViewDebug", "Blocked intent with explicit component or selector")
            return true
        }

        // Clear verified package temporarily before invoking IntentSanitizer with allowAnyComponent()
        // to avoid Builder mutual-exclusion constraints while strictly rejecting untrusted flags/extras.
        parsedIntent.`package` = null

        val sanitizedIntent = try {
            IntentSanitizer.Builder()
                .allowAnyComponent()
                .allowAction(Intent.ACTION_VIEW)
                .allowCategory(Intent.CATEGORY_BROWSABLE)
                .allowData { uri -> policy.isAllowedCustomUri(uri) }
                .build()
                .sanitizeByThrowing(parsedIntent)
        } catch (e: SecurityException) {
            Log.w("WebViewDebug", "IntentSanitizer threw SecurityException for disallowed fields or flags")
            return true
        } catch (e: IllegalArgumentException) {
            Log.w("WebViewDebug", "IntentSanitizer rejected invalid intent arguments")
            return true
        }

        // Re-bind verified target package + host-enforced category + post-sanitization assertions
        sanitizedIntent.`package` = expectedPackage
        sanitizedIntent.addCategory(Intent.CATEGORY_BROWSABLE)

        val sanitizedData = sanitizedIntent.data
        if (sanitizedIntent.component != null ||
            sanitizedIntent.action != Intent.ACTION_VIEW ||
            sanitizedIntent.`package` != expectedPackage ||
            sanitizedData == null ||
            !policy.isAllowedCustomUri(sanitizedData)
        ) {
            Log.w("WebViewDebug", "Post-sanitization intent assertions failed")
            return true
        }

        try {
            launchWithContextSafety(view, sanitizedIntent)
            loopGuard.resetChain()
        } catch (e: ActivityNotFoundException) {
            if (!fallbackUrl.isNullOrBlank()) {
                val fallbackUri = Uri.parse(fallbackUrl)
                if (policy.isAllowedFallbackUri(fallbackUri) &&
                    loopGuard.canLoadFallback(fallbackUri, view.url)
                ) {
                    if (isPopupContext) {
                        onPopupFallbackHandoff?.invoke(fallbackUri)
                    } else {
                        loadFallbackNavigation(view, fallbackUri)
                    }
                } else {
                    Log.w("WebViewDebug", "Blocked untrusted or looping fallback URL")
                }
            }
        } catch (e: SecurityException) {
            Log.w("WebViewDebug", "SecurityException blocked intent launch")
        }
        return true
    }

    private fun launchIntentSafely(view: WebView, intent: Intent) {
        try {
            launchWithContextSafety(view, intent)
        } catch (e: ActivityNotFoundException) {
            Log.i("WebViewDebug", "No installed application handles target package/scheme")
        } catch (e: SecurityException) {
            Log.w("WebViewDebug", "SecurityException blocked custom scheme launch")
        }
    }

    private fun launchWithContextSafety(view: WebView, intent: Intent) {
        val safeIntent = Intent(intent)
        if (view.context !is Activity) {
            safeIntent.addFlags(Intent.FLAG_ACTIVITY_NEW_TASK)
        }
        view.context.startActivity(safeIntent)
    }
}

// 4. Lifecycle-Managed Popup WebChromeClient (Strict UI-Thread Session State & Stateless Background Guard)
class SafePopupWebChromeClient(
    private val safeClient: SafeRedirectWebViewClient
) : WebChromeClient() {

    private var activeDialog: Dialog? = null
    private var activeChildWebView: WebView? = null
    private var isDisposed: Boolean = false

    private fun disposeActivePopup() {
        if (isDisposed) return
        isDisposed = true

        val dialog = activeDialog
        val child = activeChildWebView
        activeDialog = null
        activeChildWebView = null

        dialog?.setOnDismissListener(null)
        dialog?.dismiss()

        child?.let {
            (it.parent as? ViewGroup)?.removeView(it)
            it.stopLoading()
            it.webViewClient = WebViewClient()
            it.webChromeClient = null
            it.destroy()
        }
    }

    override fun onCreateWindow(
        view: WebView,
        isDialog: Boolean,
        isUserGesture: Boolean,
        resultMsg: Message?
    ): Boolean {
        if (!isUserGesture) return false

        val activity = view.context as? Activity
        if (activity == null || activity.isFinishing || activity.isDestroyed) {
            return false
        }

        val transport = resultMsg?.obj as? WebView.WebViewTransport ?: return false
        disposeActivePopup()
        isDisposed = false

        val popupDialog = Dialog(activity)
        val popupRoot = android.widget.LinearLayout(activity).apply {
            orientation = android.widget.LinearLayout.VERTICAL
            layoutParams = ViewGroup.LayoutParams(ViewGroup.LayoutParams.MATCH_PARENT, ViewGroup.LayoutParams.MATCH_PARENT)
        }

        val originBanner = TextView(activity).apply {
            setPadding(24, 16, 24, 16)
            setBackgroundColor(android.graphics.Color.DKGRAY)
            setTextColor(android.graphics.Color.WHITE)
            textSize = 12f
            text = "Loading destination..."
        }
        popupRoot.addView(originBanner)

        // All popup session state variables below are read and mutated strictly on the UI thread
        var isInitialTransportLoad = true
        var isAuthorizedPopupSession = false
        var popupRedirectHops = 0
        var popupChainStartMs = SystemClock.elapsedRealtime()
        val maxPopupRedirects = 5
        val maxPopupRedirectWindowMs = 30_000L

        val childWebView = WebView(activity).apply {
            layoutParams = android.widget.LinearLayout.LayoutParams(ViewGroup.LayoutParams.MATCH_PARENT, ViewGroup.LayoutParams.MATCH_PARENT)
            settings.apply {
                javaScriptEnabled = true
                allowFileAccess = false
                allowContentAccess = false
                setSupportMultipleWindows(false)
            }
            webViewClient = object : WebViewClient() {
                // UI Thread: Owns navigation, redirect, and session authorization state
                override fun shouldOverrideUrlLoading(
                    childView: WebView,
                    request: WebResourceRequest
                ): Boolean {
                    val hasGesture = request.hasGesture()
                    if (hasGesture) {
                        popupRedirectHops = 0
                        popupChainStartMs = SystemClock.elapsedRealtime()
                    }

                    val result = safeClient.handlePopupNavigation(
                        view = childView,
                        uri = request.url,
                        isForMainFrame = request.isForMainFrame,
                        hasUserGesture = hasGesture,
                        isRedirect = request.isRedirect,
                        isInitialTransportLoad = isInitialTransportLoad,
                        isAuthorizedPopupSession = isAuthorizedPopupSession,
                        onAuthorizedInitialSession = {
                            isAuthorizedPopupSession = true
                        },
                        canProceedPopupRedirect = {
                            val withinWindow = (SystemClock.elapsedRealtime() - popupChainStartMs) <= maxPopupRedirectWindowMs
                            if (withinWindow && popupRedirectHops < maxPopupRedirects) {
                                popupRedirectHops++
                                true
                            } else {
                                false
                            }
                        }
                    )
                    isInitialTransportLoad = false
                    return result
                }

                // Background WebView IO Thread: Strictly stateless, read-only policy check.
                // Never mutates UI-thread session state; covers initial resource URL only (not subsequent 302 hops).
                override fun shouldInterceptRequest(
                    childView: WebView,
                    request: WebResourceRequest
                ): WebResourceResponse? {
                    if (request.isForMainFrame) {
                        val targetUri = request.url
                        val scheme = targetUri?.scheme?.lowercase()
                        if ((scheme == "http" || scheme == "https") && !safeClient.policy.isAllowedPopupUri(targetUri)) {
                            Log.w("WebViewDebug", "Blocked unapproved popup main-frame request in shouldInterceptRequest")
                            childView.post { disposeActivePopup() }
                            return WebResourceResponse("text/plain", "utf-8", ByteArrayInputStream(ByteArray(0)))
                        }
                    }
                    return super.shouldInterceptRequest(childView, request)
                }

                // UI Thread: Navigation-start fallback check & origin display (not a pre-navigation filter)
                override fun onPageStarted(childView: WebView, url: String?, favicon: android.graphics.Bitmap?) {
                    super.onPageStarted(childView, url, favicon)
                    isInitialTransportLoad = false
                    val uri = url?.let { Uri.parse(it) }
                    if (uri == null || !safeClient.policy.isAllowedPopupUri(uri)) {
                        Log.w("WebViewDebug", "Navigation-start fallback check terminated unapproved popup URL")
                        childView.stopLoading()
                        disposeActivePopup()
                        return
                    }
                    isAuthorizedPopupSession = true
                    val scheme = uri.scheme?.lowercase() ?: "https"
                    val host = uri.host?.lowercase() ?: "Unknown"
                    originBanner.text = "Origin: $scheme://$host"
                }
            }
            webChromeClient = object : WebChromeClient() {
                override fun onCloseWindow(window: WebView?) {
                    disposeActivePopup()
                }
            }
        }
        popupRoot.addView(childWebView)

        popupDialog.setContentView(popupRoot)
        popupDialog.setOnDismissListener {
            disposeActivePopup()
        }

        activeDialog = popupDialog
        activeChildWebView = childWebView
        popupDialog.show()

        transport.webView = childWebView
        resultMsg.sendToTarget()
        return true
    }

    fun destroyPopups() {
        disposeActivePopup()
    }
}

// 5. Complete Host Activity Registration & Lifecycle Cleanup Example (JavaScript Enabled on Main WebView)
class SafeWebViewActivity : AppCompatActivity() {

    private lateinit var webView: WebView
    private lateinit var safeClient: SafeRedirectWebViewClient
    private lateinit var popupChromeClient: SafePopupWebChromeClient

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)

        if (applicationInfo.flags and ApplicationInfo.FLAG_DEBUGGABLE != 0) {
            WebView.setWebContentsDebuggingEnabled(true)
        }

        val policy = CustomUriPolicy()
        val loopGuard = FallbackLoopGuard()

        safeClient = SafeRedirectWebViewClient(
            policy = policy,
            loopGuard = loopGuard,
            onPopupFallbackHandoff = { fallbackUri ->
                popupChromeClient.destroyPopups()
                safeClient.loadFallbackNavigation(webView, fallbackUri)
            }
        )
        popupChromeClient = SafePopupWebChromeClient(safeClient)

        webView = WebView(this).apply {
            settings.apply {
                // Enable JavaScript explicitly for trusted landing pages requiring JS redirects or window.open()
                javaScriptEnabled = true
                allowFileAccess = false
                allowContentAccess = false
                // Enable multiple windows only if hosting interactive popup containers
                setSupportMultipleWindows(true)
            }
            webViewClient = safeClient
            webChromeClient = popupChromeClient
        }
        setContentView(webView)

        // Use explicit host wrapper rather than bare webView.loadUrl()
        safeClient.loadNewNavigation(webView, "https://example.com/landing")
    }

    override fun onDestroy() {
        popupChromeClient.destroyPopups()
        (webView.parent as? ViewGroup)?.removeView(webView)
        webView.destroy()
        super.onDestroy()
    }
}

Perguntas Frequentes (FAQ)

Por que o Android WebView mostra net::ERR_UNKNOWN_URL_SCHEME mesmo quando o aplicativo de destino está instalado?
Esse erro ocorre quando o Chromium tenta buscar um esquema de URL personalizado não HTTP em sua pilha de rede, em vez de encaminhá-lo para o Activity Manager do Android. Verifique cinco pontos de controle: confirme se um `WebViewClient` personalizado está atribuído; garanta que `shouldOverrideUrlLoading(WebView, WebResourceRequest)` retorne `true` para o esquema interceptado; confirme se a estrutura do URI e o pacote de destino de 1 para 1 passam pela sua lista de permissões; verifique se `startActivity(intent)` é executado de forma limpa (capturando `ActivityNotFoundException` ou configurando `<queries>` para `targetSdk >= 30` se chamar `resolveActivity()`); e confirme se o manifesto do aplicativo de destino declara um `<intent-filter>` correspondente com `CATEGORY_BROWSABLE`.
Por que o shouldOverrideUrlLoading falha ao ser disparado quando meu aplicativo chama WebView loadUrl diretamente?
Por design da estrutura do Android, o `shouldOverrideUrlLoading` não é invocado para chamadas `webView.loadUrl()` iniciadas pelo aplicativo ou navegações HTTP `POST`. Ele é acionado principalmente para navegações iniciadas por conteúdo da Web, interações do usuário ou redirecionamentos de servidor HTTP 3xx suportados. Dispare redirecionamentos de teste a partir de interações do DOM ou respostas do servidor dentro da página e use wrappers de host explícitos (como `loadNewNavigation`) ao auditar carregamentos iniciados pelo aplicativo.
Por que links target blank com esquemas personalizados falham silenciosamente dentro do WKWebView?
Quando um link da Web usa `target="_blank"` ou `window.open()`, o WebKit cria uma solicitação de navegação de nova janela onde `navigationAction.targetFrame` é `nil`. Como o `WKWebView` não abre novas guias automaticamente, essas navegações podem falhar silenciosamente, a menos que o aplicativo host detecte `targetFrame == nil` em `decidePolicyForNavigationAction` e implemente `WKUIDelegate.webView(_:createWebViewWith:for:windowFeatures:)` para avaliar e rotear a solicitação sob sua política de navegação unificada.

Resumo e Estrutura de Decisão

A resolução de falhas de redirecionamento de deep linking em WebView exige isolar o comportamento do mecanismo de WebView das políticas de navegação do aplicativo host. Ao reproduzir eventos de navegação no Chrome DevTools ou no Safari Web Inspector, confinar o estado da sessão de pop-up do Android estritamente à thread de UI enquanto emparelha a triagem de solicitações iniciais sem estado com verificações de redirecionamento 302 autorizadas pela sessão, aplicar listas de permissões de IntentSanitizer de falha fechada e proteger fallbacks de Links Universais do iOS contra substituições assíncronas obsoletas e disparos de delegados duplicados, as equipes de engenharia podem reduzir jornadas de usuário quebradas e ajudar a prevenir vulnerabilidades de redirecionamento do lado do cliente.

Depois que os delegados nativos no nível do contêiner e os caminhos de fallback forem verificados, as equipes de engenharia também devem validar as páginas de destino de atribuição de ponta a ponta e as cadeias de roteamento de Lançamento com Um Clique usando plataformas como OpoInstall para confirmar a preservação de parâmetros nas transições de navegador para aplicativo.

Glossário de Entidades

Termo Definição Entidade Relacionada Função de Intento de Busca
WebView Um componente de UI nativo incorporado usado para renderizar páginas da Web dentro de um aplicativo móvel. WebViewClient / WKWebView Informativo / Técnico
Esquema de URL Personalizado Um prefixo de URI registrado pelo aplicativo (por exemplo, myapp://) que permite a navegação externa para telas nativas. Intent.ACTION_VIEW Técnico / Informativo
WKNavigationDelegate O protocolo WebKit que permite que um aplicativo host aceitar, cancelar ou redirecionar ações de navegação em WKWebView. decidePolicyForNavigationAction Técnico
WKUIDelegate O protocolo WebKit responsável por lidar com solicitações de criação de novas janelas em WKWebView. createWebViewWith Técnico
WebResourceRequest O objeto do Android API 24+ que encapsula metadados de URL, quadro, método HTTP, redirecionamento e gestos. shouldOverrideUrlLoading Técnico
WebChromeClient A interface de callback do Android WebView que lida com diálogos JavaScript, progresso e onCreateWindow. WebViewTransport Técnico
IntentSanitizer O utilitário AndroidX Core usado para filtrar ou validar estritamente campos de Intent não confiáveis antes do despacho. Defesa de Redirecionamento de Intent Técnico / Segurança
Links Universais O padrão de deep linking baseado em HTTPS da Apple que vincula domínios da Web verificados a aplicativos iOS instalados. Domínios Associados Técnico / Informativo
Visibilidade de Pacotes A filtragem de SO do Android 11+ (targetSdk >= 30) que restringe quais aplicativos instalados um aplicativo host pode consultar via PackageManager. Tag de Manifesto <queries> Técnico
URI de Intent Um URI estruturado do Android (intent://) que codifica o pacote de destino, o esquema e as URLs de fallback do navegador. Intent.URI_INTENT_SCHEME Técnico

Linha de Base de Compatibilidade e Status de Verificação

  • Destinos de Compatibilidade Pretendidos: Android minSdk 24, compileSdk 34/35, targetSdk 34/35 (Android 14/15), contexto de endurecimento de redirecionamento de Intent do Android 16 (API 36), androidx.core:core:1.9.0+ (IntentSanitizer); iOS 15.0–18.0 (isInspectable vinculado ao iOS 16.4+), Xcode 15/16, Swift 5.9/6.0.

  • Status de Verificação:

    • Revisão de API Estática e Especificação: Concluída em relação às especificações oficiais do Android Developers, AndroidX Core, Apple Developer, IETF RFC 3986 e OWASP MASTG.

    • Verificação de Dispositivo Físico e Compilação: Ainda não executada neste ciclo de revisão. As equipes devem compilar e executar a regressão de dispositivo físico cobrindo URLs de pop-up iniciais maliciosas, correntes 302 entre domínios, saltos 302 consecutivos, criação de janelas de iframe de terceiros, Links de Aplicativos Android (assetlinks.json), Domínios Associados do iOS (cache AASA), cancelamento assíncrono obsoleto de Links Universais, correntes de fallback intent:// e despacho de ActivityNotFoundException antes do lançamento em produção.

Referências

Share this article