Android 및 iOS에서 WebView 리디렉션 오류를 어떻게 해결할 수 있을까요? 먼저 오류가 표준 HTTPS 탐색, 커스텀 URL 스킴, Android intent:// URI 또는 새 창(popup) 요청 중 어디에서 발생하는지 파악합니다. 그 후 Chrome DevTools나 Safari Web Inspector를 통해 탐색 과정을 검사하고, 해당하는 네이티브 델리게이트(shouldOverrideUrlLoading, onCreateWindow, decidePolicyForNavigationAction 또는 createWebViewWith)를 추적합니다. 대상 앱 해상도, URI 허용 목록, 프레임 및 사용자 상호 작용 정책, 대체(fallback) 라우팅을 검증하여 컨테이너 레벨의 오류와 운영체제 디스패치 실패를 격리하세요.
WebView 리디렉션 오류는 내장된 Android Chromium WebView 또는 iOS WebKit WKWebView가 탐색 요청을 의도한 목적지로 올바르게 라우팅하지 못할 때 발생합니다. 일반적인 원인으로는 지원되지 않는 커스텀 URL 스킴, 처리되지 않은
target="_blank"요청, 패키지 가시성 선언 누락, 거부되거나 무한 루프에 빠진 대체 리디렉션 등이 있습니다.
내장된 Android WebView 및 iOS WKWebView 컨테이너가 리디렉션을 누락하는 이유

리디렉션 실패를 디버깅할 때, 엔지니어링 팀은 WebView 엔진 동작(Chromium 또는 WebKit이 URL, 프레임 대상, 팝업 이벤트를 파싱하는 방식)과 호스트 애플리케이션 정책(애플리케이션이 제공하는 WebViewClient, WebChromeClient, WKNavigationDelegate 또는 WKUIDelegate가 사용자 상호 작용 유형, 허용 목록, 외부 앱 연동을 평가하는 방식)을 명확히 구분해야 합니다. 독립형 브라우저는 내장된 URI 디스패처와 링크 연동 핸들러를 포함하고 있지만, android.webkit.WebView와 Apple의 WKWebView는 기본적으로 표준 http:// 또는 https:// 네트워크 응답을 예상하는 내장 렌더링 컴포넌트입니다.
웹페이지가 활성 델리게이트 오버라이드 없이 커스텀 스킴(예: myapp://product/42)이나 Android intent:// 링크를 트리거할 때, 플랫폼별 기본 컨테이너 동작은 다음과 같이 다릅니다:
- Android Chromium WebView: Android
WebViewClient명세에 따라, 커스텀WebViewClient가 지정되지 않은 경우 WebView는 Activity Manager에 사용 가능한 시스템 핸들러를 통해 URL을 해결하도록 요청할 수 있습니다. 커스텀WebViewClient가 지정되어 있고 지원되지 않는 커스텀 스킴에 대해shouldOverrideUrlLoading이false를 반환하면, WebView는 Chromium 내부에서 계속 로딩을 시도하다가net::ERR_UNKNOWN_URL_SCHEME을 렌더링합니다. - iOS WebKit WKWebView: WebKit은 내부적으로 비-HTTP 스킴을 거부하며, 호스트의
WKNavigationDelegate가 요청을 가로채어UIApplication에 전달하지 않는 한 탐색을 중단합니다. 이 경우 종종 조용히 실패하거나NSURLErrorUnsupportedURL을 발생시킵니다.
또한 Apple의 스마트 앱 배너를 통한 앱 홍보(Promoting Apps with Smart App Banners)는 내장 WKWebView 탐색 API가 아니라 독립형 Safari 브라우징을 지원하기 위한 기능이므로, 인앱 커스텀 URL 스킴 리디렉션과는 별도로 평가해야 합니다.
요약
- 엔지니어링 동작과 호스트 정책 분리: 탐색 실패가 웹 엔진 내부(Chromium/WebKit), 네이티브 델리게이트 오버라이드, 혹은 OS 패키지 해상도 경계 중 어디에서 발생했는지 격리합니다.
- 코딩 전 라이브 리디렉션 검사: Chrome DevTools(
chrome://inspect)와 Safari Web Inspector(isInspectable = true)를 사용하여 3xx 리디렉션 체인,targetFrame상태, 제스처 플래그를 캡처합니다. - 플랫폼에 적합한 URI 및 Intent 유효성 검사 적용: Android에서는 웹페이지가 제공하는 태스크 플래그 없이
IntentSanitizer를 통해 커스텀 스킴과intent://타겟을 검증된 패키지와 1대1로 바인딩합니다. iOS에서는 전체 커스텀 URI 구조를 검증하고(검증된 앱-도메인 신뢰관계가 필요한 경우 유니버설 링크 활용), 양 플랫폼 모두에서 중복 쿼리 키를 거부합니다. - 팝업 및 경쟁 상태에 대한 다중 방어 적용: Android 팝업 세션 상태는 UI 스레드에 엄격히 제한하고
shouldInterceptRequest와shouldOverrideUrlLoading간의 콜백 경계를 이해합니다. 또한 iOSWKWebView에서는 액션 수준의 중복 제거 및 탐색 생성 토큰을 사용하여 순수 정책 검사와 외부 디스패치 부수 효과를 분리합니다.
WebView 리디렉션 오류의 일반적인 원인과 확인 단계
감지된 클라이언트 오류를 기본 컨테이너 실패 메커니즘에 매핑
아래의 진단 매트릭스를 사용하여 감지된 WebView 증상을 일반적인 플랫폼 근본 원인, 확인 단계 및 맞춤형 해결책에 매핑하세요:
| 감지된 증상 또는 오류 | 타겟 플랫폼 | 일반적인 근본 원인 | 진단 확인 단계 | 맞춤형 해결책 |
|---|---|---|---|---|
WebView에 net::ERR_UNKNOWN_URL_SCHEME 표시됨 |
Android WebView | 커스텀 WebViewClient가 false를 반환하거나 스킴 허용 목록이 누락됨 |
shouldOverrideUrlLoading에서 request.url 검사 |
허용된 URI를 가로채어 패키지에 바인딩된 1대1 Intent.ACTION_VIEW 디스패치 |
| 커스텀 스킴 링크 탭 시 무응답 (Silent hang) | iOS WKWebView | WKNavigationDelegate가 .allow를 반환할 때 WebKit이 비-HTTP URI를 중단함 |
decidePolicyForNavigationAction에서 navigationAction.request.url 로깅 |
UIApplication.shared.open을 통해 검증된 스킴을 라우팅하고 .cancel 전달 |
target="_blank"가 WebView의 현재 페이지를 대체함 |
Android WebView | setSupportMultipleWindows(false)가 새 창을 최상위 로드로 처리함 |
webView.settings.supportMultipleWindows() 확인 |
별도의 팝업 컨테이너가 필요한 경우에만 setSupportMultipleWindows(true) 활성화 |
target="_blank"가 작동하지 않거나 OAuth 302 리디렉션을 드롭함 |
Android WebView | onCreateWindow가 누락되었거나, 하위 클라이언트가 hasGesture()가 없는 isRedirect 홉을 차단함 |
onCreateWindow, request.isRedirect 및 shouldInterceptRequest 로그 확인 |
UI 스레드 세션 상태와 제한된 isRedirect 홉을 가진 뷰 호스팅 팝업 WebView 연결 |
target="_blank" 또는 window.open() 링크가 반응하지 않음 |
iOS WKWebView | 새 창 탐색 시 targetFrame == nil이 설정되며 WKUIDelegate가 필요함 |
navigationAction.targetFrame == nil 확인 |
decidePolicyForNavigationAction에서 targetFrame == nil 감지 후 WKUIDelegate를 통해 처리 |
| 타겟 앱이 설치되어 있음에도 대체 페이지가 열림 | Android 11+ (targetSdk >= 30) |
<queries> 선언 누락으로 인해 보이지 않는 패키지에 대해 resolveActivity() 또는 queryIntentActivities()가 불완전한 결과를 반환함 |
resolveActivity() 주변에 애플리케이션 수준 로깅 추가 및 adb logcat을 통해 출력 검사 |
사전 확인 시 <queries> 인텐트 선언 또는 ActivityNotFoundException 예외 처리를 포함하여 startActivity 직접 호출 |
| JavaScript 타이머 리디렉션이 외부 앱을 여는 데 실패함 | iOS / Android | 자동 스크립트 리디렉션에 사용자 상호 작용 신호가 부족함 | request.hasGesture()(Android) 또는 navigationType(iOS) 확인 |
리디렉션을 직접 사용자 탭에 바인딩하고 명시적인 호스트 제스처 정책 정의 |
유니버설 링크가 타겟 앱 대신 WKWebView 내에서 로드됨 |
iOS WKWebView | 브라우징 컨텍스트, 도메인 관계 또는 JS 탐색으로 인해 로드가 WebKit 내에 유지됨 | decidePolicyForNavigationAction에서 navigationType 및 호스트 확인 |
허용된 외부 호스트에 대해 .universalLinksOnly: true와 함께 UIApplication.shared.open 호출 |
5분 만에 끝내는 WebView 리디렉션 빠른 진단 체크리스트
- 1단계: DevTools에서 프로토콜 스킴 확인: 페이지가
https://, 커스텀 스킴 또는intent://URI를 발생시켰는지 확인하고 콘텐츠 보안 정책(CSP)에 의해 차단되지 않았는지 검증합니다. - 2단계: 프레임 계층 구조 검사: 트리거가 타사
<iframe>내부(!isMainFrame)에서 발생했는지 확인합니다. 호스트 애플리케이션은 타사 iframe에서 시작된 외부 앱 실행을 의도적으로 차단할 수 있습니다. - 3단계: 리디렉션과 타이머 구분: 제스처가 없는 탐색이 승인된 HTTP 3xx 서버 리디렉션(Android의 경우
request.isRedirect)인지, 아니면 예기치 않은 JavaScript 타이머인지 확인합니다. - 4단계: 새 창 트리거 확인:
target="_blank"또는window.open()이 새 창 요청을 생성했는지 확인합니다(iOS의 경우targetFrame == nil, Android의 경우onCreateWindow). - 5단계: OS 패키지 해상도 검증: Android 11+의 API 30+ 타겟 앱의 경우, 누락된
<queries>선언으로 인해 사전 점검resolveActivity()호출이 실패하고 있는지 확인합니다.
다음 진단 워크플로는 컨테이너 리디렉션 실패를 격리하기 위한 순차적인 진단 경로를 보여줍니다:
[WebView 탐색 실패]
│
▼
[Chrome DevTools / Safari Web Inspector를 통한 URL + 네트워크 + 콘솔 검사]
│
▼
[탐색 소스 식별]
│
├── 앱 loadUrl() 또는 HTTP POST
│ │
│ └── shouldOverrideUrlLoading이 호출되지 않음; 호스트 측 호출 경로 검사
│
├── target="_blank" 또는 window.open()
│ │
│ ├── Android (multiple-windows=false) ──> 현재 WebView 페이지 대체
│ ├── Android (multiple-windows=true) ──> onCreateWindow + shouldInterceptRequest 검사
│ └── iOS (targetFrame == nil) ──> WKNavigationDelegate + WKUIDelegate 검사
│
├── HTTP / HTTPS 탐색
│ │
│ └── 호스트 + 포트 허용 목록, 3xx 리디렉션, 유니버설 링크 또는 앱 링크 일치 여부 검사
│
└── 커스텀 스킴 또는 Chrome intent://
│
├── 사용자 상호 작용 + 메인 프레임 정책 평가
├── 전체 URI 구조 확인 (스킴, 호스트, 포트, 경로, 중복 쿼리 키 없음)
├── 인텐트 정화 (명시적 컴포넌트 거부, 1대1 패키지 확인, 웹페이지 플래그 제로화)
├── 타겟 앱 해상도 확인 (<queries> / ActivityNotFoundException)
└── 대체 경로 + 쿼리 허용 목록 + 단조 증가 체인 가드(elapsedRealtime) 검증
원격 디버깅 도구를 사용하여 WebView 탐색 이벤트 검사하기
Android에서 Chrome DevTools 및 ADB Logcat을 통한 원격 디버깅 활성화
네이티브 델리게이트를 수정하기 전에 로드된 웹페이지가 예상되는 리디렉션을 발생시키는지 확인하세요. Android Chrome DevTools 원격 디버깅 가이드에 따라, 개발 빌드에서 ApplicationInfo.FLAG_DEBUGGABLE을 검사하고 WebView.setWebContentsDebuggingEnabled(true)를 호출하여 원격 WebView 디버깅을 명시적으로 활성화합니다. 프로덕션 릴리스에서는 절대 디버깅을 활성화한 채로 배포하지 마세요:
// Android - 디버그 가능한 빌드에서만 WebView 디버깅 활성화
if (applicationInfo.flags and ApplicationInfo.FLAG_DEBUGGABLE != 0) {
WebView.setWebContentsDebuggingEnabled(true)
}
USB를 통해 기기를 연결하고 데스크톱 Chrome에서 chrome://inspect/#devices를 연 후, Preserve log가 체크된 상태로 Network 탭을 모니터링합니다. 동시에 adb logcat을 통해 네이티브 런타임 로그를 필터링하여 ActivityNotFoundException, SecurityException 또는 커스텀 래퍼 로그를 캡처합니다. 레거시 shouldOverrideUrlLoading(WebView, String) 시그니처에 대한 지원 중단(deprecations) 경고는 런타임 adb logcat이 아니라 Android Studio / Gradle 컴파일 중에 나타난다는 점에 유의하세요:
# 터미널 - 커스텀 WebView 태그 및 ActivityTaskManager 인텐트 해상도를 위해 logcat 필터링
adb logcat -s "WebViewDebug" "ActivityTaskManager" "PackageManager"
iOS에서 isInspectable 설정 및 Safari Web Inspector와 Xcode 콘솔 연결하기
iOS 16.4 및 macOS 13.3부터 Apple은 기본값이 false인 WKWebView.isInspectable을 통해 애플리케이션이 수동으로 선택(opt-in)하도록 요구합니다. #if DEBUG 블록 내부에 webView.isInspectable = true를 활성화하세요:
// iOS - iOS 16.4+ 디버그 빌드에서 Safari Web Inspector 옵트인 활성화
#if DEBUG
if #available(iOS 16.4, *) {
webView.isInspectable = true
}
#endif
실물 iOS 기기에서 설정 > 앱 > Safari > 고급(구형 iOS 버전의 경우 설정 > Safari > 고급)으로 이동하여 웹 Inspector를 활성화합니다. USB로 연결한 후 데스크톱 Safari의 개발(Develop) 메뉴를 열고, 네이티브 decidePolicyForNavigationAction, createWebViewWith 및 UIApplication.shared.open 완료 출력을 확인하기 위해 Xcode 콘솔을 동시에 모니터링합니다.

iOS WKWebView에서 조용한 새 창 드롭 및 누락된 사용자 제스처 해결하기
WKNavigationDelegate와 WKUIDelegate 간의 정책 평가와 부수 효과 분리
웹 링크가 target="_blank" 또는 window.open()을 지정하면 WebKit은 navigationAction.targetFrame이 nil인 새 창 탐색 요청을 생성하며, WKNavigationDelegate와 WKUIDelegate 모두가 관여하게 됩니다. 호스트 앱이 webView(_:createWebViewWithConfiguration:for:windowFeatures:)를 구현하지 않으면 WebKit은 보조 WebView를 생성할 수 없으며, 탐색이 조용히 실패하는 것처럼 보일 수 있습니다.
두 델리게이트가 모두 요청을 검사할 때 외부 앱이 중복으로 실행되거나 세대 토큰(generation token)이 이중으로 증가하는 것을 방지하려면, 순수 정책 평가(evaluateNavigationPolicy)와 실행 부수 효과를 분리하고, 단순한 시간 임계값에 의존하는 대신 특정 WKNavigationAction 인스턴스(ObjectIdentifier(navigationAction))를 기준으로 중복을 제거해야 합니다. 시간 임계값은 사용자의 의도적인 빠른 연속 클릭을 억제할 수 있습니다. decidePolicyForNavigationAction에서 navigationAction.targetFrame == nil을 직접 평가합니다: 평가 결과 외부 연동 계획이 반환되면 한 번 실행하고(WKNavigationAction 식별자 기록) .cancel을 전달합니다; 허용된 팝업 URL에 대해 .allowInWebView를 반환하는 경우 .allow를 전달하여 createWebViewWith가 팝업을 안전하게 로드할 수 있도록 합니다. 대상 iOS 버전에서 정확한 델리게이트 콜백 순서를 항상 확인하세요.
유니버설 링크 컨텍스트, 비동기 경쟁 상태 안전성 및 커스텀 스킴 신원
유니버설 링크 연동은 소스 브라우징 컨텍스트, 도메인 관계 및 연결된 도메인(Associated Domains) 구성(타겟 서버의 apple-app-site-association 파일을 통해 검증됨)에 따라 달라집니다. Apple의 기술 노트 TN3155: 유니버설 링크 디버깅에서는 Safari 내의 동일 도메인 탐색이 브라우저에 유지되는 경향이 있는 반면, 서로 다른 서브도메인은 적격성을 변경하는 방식을 문서화하고 있습니다. WKWebView 내의 대상 iOS 버전에서 연결된 도메인(Associated Domains) 동작을 항상 테스트하세요.
UIApplication.shared.open(url, options: [.universalLinksOnly: true])를 호출할 때 비동기 탐색 경쟁 상태에 대비해야 합니다: 시스템이 유니버설 링크 연동을 처리하는 동안 사용자가 후속 메인 프레임 탐색 시도를 시작하는 경우, false를 반환하는 보호되지 않은 완료 핸들러가 사용자의 최신 탐색 상태를 덮어쓸 수 있습니다. 모든 새로운 메인 프레임 탐색 평가(차단되거나 리디렉션된 시도 포함)마다 단조 증가하는 activeNavigationGeneration 토큰을 증가시켜 대기 중인 이전 비동기 대체(fallback)가 즉시 무효화되도록 하고, 대체 URL을 다시 로드하기 전에 self.isViewLoaded && self.view.window != nil과 함께 self.activeNavigationGeneration == requestGeneration을 검증하세요.
다음 두 가지 엄격한 보안 경계를 준수하세요:
WKNavigationType분류: Apple의WKNavigationType문서에 따르면,formSubmitted는 링크 탭이 아니라 폼 제출 요청을 나타내며 페이지 스크립트는 폼을 프로그래밍 방식으로 제출할 수 있습니다..linkActivated를 고립된 암호화 제스처 토큰으로 취급하는 대신, 외부 앱 연동을 WebKit이 분류한.linkActivated이벤트와sourceFrame.isMainFrame및 전체 URI 허용 목록을 결합한 형태로 제한하세요.- 커스텀 스킴 고유성 및 매개변수 오염: Apple의 앱용 커스텀 URL 스킴 정의 가이드에 따라 여러 앱이 동일한 커스텀 스킴을 주장할 수 있습니다.
isAllowedCustomURL(_:)은 대상 번들 ID 신원이 아니라 URI 구조(스킴, 호스트, 기본 포트nil, 경로 패턴, 사용자 정보/프래그먼트 없음, 중복 쿼리 키 거부)를 검증합니다. 앱 신원 바인딩이 필요한 경우 항상 도메인이 검증된 유니버설 링크를 사용하세요.
참조 아키텍처 면책 조항: 다음 구현은 방어적 참조 아키텍처입니다. 애플리케이션에서 사용하는 정확한 AndroidX 및 iOS 버전에 대해 API 가용성, 델리게이트 순서 및 수명 주기 동작을 검증하세요.
// iOS - WebViewContainerController.swift
// 참조 아키텍처: 특정 프로젝트 타겟(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!
// 외부 커스텀 URL 스킴, 호스트, 쿼리 키에 대한 명시적 허용 목록
private let allowedCustomSchemes: Set<String> = ["myapp", "partnerapp"]
private let allowedCustomHosts: Set<String> = ["open", "product", "promo"]
private let allowedCustomQueryKeys: Set<String> = ["id", "ref", "promo"]
// 기본 WebView 컨테이너 내에서 허용되는 HTTPS 호스트에 대한 명시적 허용 목록
private let allowedWebHosts: Set<String> = [
"example.com",
"m.example.com",
"links.example.com"
]
// 하위 팝업 창(target="_blank")에만 특화된 격리된 허용 목록
private let allowedPopupHosts: Set<String> = ["example.com", "auth.example.com"]
private let allowedPopupPathPrefixes: [String] = ["/oauth", "/popup", "/window"]
// 링크 활성화 시 네이티브 앱 연동을 시도하는 외부 유니버설 링크 호스트
private let externalUniversalLinkHosts: Set<String> = ["links.example.com"]
// 새로운 메인 프레임 탐색 시도마다 증가하는 단조 증가 탐색 생성 토큰
private var activeNavigationGeneration: UInt64 = 0
// 동일한 WKNavigationAction에 대한 중복 디스패치를 방지하는 액션 레벨 중복 제거
private var dispatchedActionIDs: [ObjectIdentifier] = []
private let maxTrackedActionIDs = 16
// 정규화된 유니버설 링크 키를 키로 하는 단조 가동 시간 TTL 바운드 우회 캐시
private var bypassedUniversalLinkKeys: [String: TimeInterval] = [:]
private let maxBypassedKeys = 10
private let bypassTTLSeconds: TimeInterval = 300
// 애플리케이션의 실제 라우팅 매개변수와 일치하도록 주요 쿼리 키를 조정하세요.
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)
// 모든 메인 프레임 탐색 시도(차단된 시도 포함)마다 생성 토큰을 증가시켜
// 대기 중인 이전 비동기 유니버설 링크 대체가 즉시 무효화되도록 합니다.
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 (target="_blank" 및 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: - 순수 탐색 정책 평가 (부수 효과 제로)
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. 비-HTTP/HTTPS 커스텀 URL 스킴 평가
// 참고: 커스텀 스킴 허용 목록은 URI 구조를 검증하며, 대상 번들 ID 신원을 보장할 수 없습니다.
if scheme != "http" && scheme != "https" {
guard isMainFrame, isLinkActivated, isAllowedCustomURL(url) else {
return .block
}
return .launchCustomScheme(url)
}
// 2. HTTPS 전용, 기본 포트(nil 또는 443), 호스트 허용 목록 강제
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. 링크 활성화 시 지정된 외부 호스트에 대한 유니버설 링크 연동 평가
if let host = targetHost,
externalUniversalLinkHosts.contains(host),
isMainFrame,
isLinkActivated,
let loopKey = universalLinkLoopKey(for: url),
!isBypassedKeyActive(loopKey) {
return .attemptUniversalLink(url)
}
return .allowInWebView
}
// MARK: - 액션 레벨 중복 제거 외부 디스패치 실행
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
// 오래된 비동기 대체 오버라이드를 방지하기 위해 뷰 수명 주기 AND 생성 토큰 검증
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] 커스텀 스킴 실행 실패 (앱이 설치되지 않았을 수 있음)")
}
}
}
}
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, // 커스텀 스킴에서 명시적 포트 거부
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
}
}
Android WebView에서 ERR_UNKNOWN_URL_SCHEME 및 패키지 가시성 실패 수정하기
지원 중단된 콜백, hasGesture() 및 POST 경계
Android는 API 수준 24에서 shouldOverrideUrlLoading(WebView, String)을 지원 중단하고 shouldOverrideUrlLoading(WebView, WebResourceRequest)을 도입했습니다. WebResourceRequest는 isForMainFrame, isRedirect 및 hasGesture()를 제공합니다. 공식적인 두 가지 플랫폼 제약 사항에 유의하세요: 호스트가 시작한 webView.loadUrl() 호출이나 HTTP POST 탐색의 경우 shouldOverrideUrlLoading이 호출되지 않으며, 합법적인 비동기 JavaScript 리디렉션이나 서버 측 302 홉의 경우 hasGesture()가 false를 반환할 수 있습니다.
WebChromeClient.onCreateWindow에서의 다중 방어 팝업 처리 및 스레드 격리
Android 팝업 동작은 WebSettings.setSupportMultipleWindows에 따라 달라집니다. 앱에 인터랙티브 팝업이 필요하지 않은 경우 setSupportMultipleWindows(false)를 유지하거나(또는 onCreateWindow에서 false 반환) 타사 iframe이 보조 컨테이너를 여는 것을 방지하고 명시적이고 호스트가 제어하는 진입점을 통해 검증된 목적지를 열 수 있습니다.
setSupportMultipleWindows(true)가 활성화된 경우 WebChromeClient.onCreateWindow는 콜백 시그니처에 대상 URL을 제공하지 않으며 단일 콜백이 모든 탐색 벡터를 다루지 않습니다. 정확한 스레드 모델과 콜백 경계를 이해하는 것은 다중 방어 참조 접근 방식에 필수적입니다:
shouldOverrideUrlLoading(UI 스레드 — 탐색 및 세션 상태 소유자): UI 스레드에서만 독점적으로 실행되며 모든 변경 가능한 팝업 세션 상태(isInitialTransportLoad,isAuthorizedPopupSession,popupRedirectHops및popupChainStartMs)를 소유합니다. 검증된 초기 로드 또는 직접 사용자 제스처가policy.isAllowedPopupUri와 일치할 때만shouldOverrideUrlLoading이 후속 제한 HTTP 302 리디렉션(request.isRedirect)에 대한 세션을 승인하여, 임의의 리디렉션을 신뢰하는 대신 리디렉션 체인이 승인된 세션으로 다시 연결되도록 보장합니다.shouldInterceptRequest(백그라운드 WebView IO 스레드 — 상태 비저장 읽기 전용 가드): 비-UI WebView 스레드에서 실행됩니다. UI 스레드 세션 상태를 절대 변경해서는 안 되므로safeClient.policy에 대한 상태 비저장의 읽기 전용 정책 검사로 엄격하게 작동합니다(isAllowedPopupUri를 실패하는 메인 프레임 HTTP/HTTPS 요청을 차단하고 메인 스레드에서disposeActivePopup()디스패치). Android 문서에 따라shouldInterceptRequest는 후속 HTTP 302 리디렉션 URL이 아니라 초기 리소스 URL에 대해서만 호출되며, 후속 리디렉션 URL은shouldOverrideUrlLoading에 의해 평가되어야 합니다.onPageStarted(UI 스레드 — 탐색 시작 대체 검사): 메인 프레임 로딩이 시작될 때 실행됩니다(사전 탐색 필터가 아님). 사용자 투명성을 위해 보이는 원점 배너를 업데이트하고, 승인되지 않은 목적지 로딩이 시작될 때stopLoading()및disposeActivePopup()을 호출하는 탐색 시작 대체 검사를 제공합니다.
대상 실물 WebView 빌드에서 악의적인 초기 URL, 크로스 도메인 HTTP 302 체인, 연속 302 홉, target="_blank", window.open() 및 타사 iframe 트리거를 항상 테스트하세요.
Android 11+ 패키지 가시성 및 지원 중단된 canOpenURL 안내
Android 패키지 가시성 규칙에 따라, Android 11(API 수준 30) 이상을 실행하고 API 수준 30 이상(targetSdk >= 30)을 타겟팅하는 애플리케이션은 대상 앱이 AndroidManifest.xml의 <queries> 아래에 선언되지 않은 경우 intent.resolveActivity() 또는 queryIntentActivities()로부터 null 또는 빈 결과를 받게 됩니다. Android에서는 <queries>를 확장하는 대신 ActivityNotFoundException 및 SecurityException에 대한 try/catch 내에서 startActivity(intent)를 직접 호출할 것을 권장합니다.
iOS에서 Apple은 UIApplication.canOpenURL(_:)을 지원 중단했으며, UIApplication.shared.open(_:options:completionHandler:)를 직접 시도하고 완료 핸들러에서 모든 실패를 처리하거나(스킴 사전 검증을 제거하기 위해 유니버설 링크로 마이그레이션) 할 것을 권장합니다. Info.plist의 LSApplicationQueriesSchemes는 레거시 코드가 계속해서 canOpenURL(_:)을 호출하는 경우에만 필요하며, open(_:options:completionHandler:)는 Info.plist에 스킴을 선언할 필요가 없습니다. <queries>와 LSApplicationQueriesSchemes는 모두 쿼리 가시성을 제어하며 신뢰할 수 없는 웹 URI를 검증하기 위한 보안 허용 목록이 아닙니다.
<!-- 매니페스트 조각: 기존 AndroidManifest.xml에 <queries> 병합 -->
<!-- resolveActivity 또는 queryIntentActivities를 호출하는 경우에만 Android 11+의 targetSdk >= 30에 필요함 -->
<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 조각: Info.plist의 루트 <dict> 아래에 삽입 -->
<!-- 레거시: 지원 중단된 UIApplication.shared.canOpenURL을 호출하는 경우에만 iOS에서 필요함; open(_:options:completionHandler:)는 이 키가 필요하지 않음 -->
<key>LSApplicationQueriesSchemes</key>
<array>
<string>myapp</string>
<string>partnerapp</string>
</array>
Chrome Intent URI를 안전하게 파싱하고 리디렉션 루프를 방지하는 방법
인텐트 리디렉션 악용에 대응하여 Intent.parseUri 보호하기
Android intent:// URI는 타겟 스킴, 패키지 및 대체 URL(S.browser_fallback_url)을 인코딩합니다. 신뢰할 수 없는 웹 URI를 Intent.parseUri(rawUri, Intent.URI_INTENT_SCHEME)를 통해 파싱하면 Android 인텐트 리디렉션 보안 가이드 및 OWASP 모바일 애플리케이션 보안 테스트 가이드에 자세히 설명된 인텐트 리디렉션 위험이 발생합니다. Android 16(API 36)에서 플랫폼 수준의 기본 하드닝이 추가되었더라도 애플리케이션은 인텐트를 디스패치하기 전에 엄격한 유효성 검사를 적용해야 합니다.

allowAnyComponent()와 패키지/컴포넌트 허용 목록 메서드 간의 빌더 상호 배제 충돌을 유발하지 않고 AndroidX IntentSanitizer(androidx.core:core:1.9.0+ 또는 androidx.core:core-ktx:1.9.0+)를 사용하여 실패 차단(fail-closed) 유효성 검사를 구현하려면:
- 사전 정화 검사:
null이 아닌component또는selector필드를 가진 인텐트를 즉시 거부합니다(parsedIntent.component != null || parsedIntent.selector != null). 정화 전에browser_fallback_url을 추출하여 제거하고,customSchemeTargetPackages를 통해parsedIntent.data?.scheme이parsedIntent.package에 1대1로 매핑되는지 네이티브로 확인합니다(myapp://가 다른 파트너 패키지가 아닌com.example.target으로 엄격하게 해결되도록 보장). - 정화기 실행: 신뢰할 수 없는 복사본에서 임시로
parsedIntent.package = null을 지우고, 웹페이지가 제공하는 태스크 플래그 없이IntentSanitizer.Builder().allowAnyComponent().allowAction(Intent.ACTION_VIEW).allowCategory(Intent.CATEGORY_BROWSABLE).allowData { ... }.build().sanitizeByThrowing(parsedIntent)를 실행한 후, 정화 후 단언(assertion) 전에 검증된expectedPackage와CATEGORY_BROWSABLE을 정화된 호스트 소유 인텐트에 다시 할당합니다. - 컨텍스트 인식 실행 플래그:
view.context !is Activity인 경우에만 네이티브 디스패처(launchWithContextSafety) 내부에Intent.FLAG_ACTIVITY_NEW_TASK를 주입합니다. 도메인-앱 연결 검증을 위해 검증된 HTTPS Android 앱 링크(assetlinks.json)를 선호하세요.
단조 증가 체인 상태로 무한 대체 루프 방지하기
startActivity가 ActivityNotFoundException을 발생시킬 때 전용 isAllowedFallbackUri(uri) 검사를 통해 browser_fallback_url의 유효성을 검사합니다(엄격한 HTTPS, 기본 포트, 검증된 호스트, 명시적 대체 경로 접두사, 중복 쿼리 키 없음, 프래그먼트 없음). uri.port == -1과 !uri.encodedAuthority.orEmpty().contains(":")를 모두 확인하여 커스텀 스킴에 대한 명시적 포트 표현을 거부합니다.
SystemClock.elapsedRealtime()을 사용하여 대체 체인을 추적하고(벽시계 System.currentTimeMillis() 점프 방지), fallbackLoopKey()를 통해 체인을 격리하며(전체 IETF RFC 3986 정규화 아님), 명시적 loadNewNavigation(webView, url) 호스트 래퍼를 통해 상태를 재설정하고, 팝업 대화상자 내에서 승인되지 않은 도메인이 절대 로드되지 않도록 onPopupFallbackHandoff를 통해 팝업 대체 핸드오프를 기본 컨테이너로 라우팅합니다.
참조 아키텍처 면책 조항: 다음 구현은 방어적 참조 아키텍처입니다. 애플리케이션에서 사용하는 정확한 AndroidX 및 iOS 버전에 대해 API 가용성, 델리게이트 순서 및 수명 주기 동작을 검증하세요.
// Android - SafeWebViewModules.kt
// 참조 아키텍처: 특정 프로젝트 타겟에 대해 컴파일 및 테스트하세요.
// IntentSanitizer를 위해 androidx.core:core:1.9.0+(또는 androidx.core:core-ktx:1.9.0+)가 필요합니다; 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. 정책 모듈 (IO 및 UI 스레드에서의 읽기 전용 접근을 위한 불변 / 스레드 안전)
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"),
// 팝업 창을 위한 명시적 격리 허용 목록; 일반 웹 호스트와 다름
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
}
// 쿼리 키 유효성 검사, 값 구문 강제, 중복 키 거부
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
// uri.port == -1과 원시 권한 콜론 부재를 모두 확인하여 네트워크 포트를 엄격하게 거부
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
// 쿼리 키 유효성 검사, 값 구문 강제, 중복 키 거부
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. 대체 관리자: 단조 경과 시간 체인 상태 (반복 세션에서 활성 체인 격리)
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
}
// 기본 HTTPS 포트를 정규화하고 주요 쿼리 키를 보존하는 애플리케이션 수준 루프 키
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. 라우터 및 실패 차단 IntentSanitizer WebViewClient (UI 스레드 전용)
class SafeRedirectWebViewClient(
val policy: CustomUriPolicy = CustomUriPolicy(),
val loopGuard: FallbackLoopGuard = FallbackLoopGuard(),
private val onPopupFallbackHandoff: ((fallbackUri: Uri) -> Unit)? = null
) : WebViewClient() {
// loadUrl() 전에 대체 체인 상태를 재설정하는 명시적 호스트 시작 탐색 API
fun loadNewNavigation(webView: WebView, url: String) {
val targetUri = Uri.parse(url)
if (!policy.isAllowedWebUri(targetUri)) {
Log.w("WebViewDebug", "신뢰할 수 없는 URL로의 호스트 시작 탐색 차단됨")
return
}
loopGuard.resetChain()
webView.loadUrl(url)
}
// 활성 체인 상태를 보존하는 내부 유효성 검사가 포함된 전용 대체 로더
fun loadFallbackNavigation(webView: WebView, fallbackUri: Uri) {
if (!policy.isAllowedFallbackUri(fallbackUri)) {
Log.w("WebViewDebug", "신뢰할 수 없는 대체 탐색 시도 차단됨")
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. 모든 HTTP/HTTPS 탐색에서 HTTPS 전용 및 웹 호스트 허용 목록 강제
if (scheme == "http" || scheme == "https") {
if (!policy.isAllowedWebUri(targetUri)) {
Log.w("WebViewDebug", "비 HTTPS, 커스텀 포트 또는 신뢰할 수 없는 웹 호스트 차단됨")
return true
}
if (hasUserGesture && isForMainFrame) {
loopGuard.resetChain()
}
return false
}
// 2. 외부 앱 실행에 메인 프레임 및 사용자 제스처 제약 조건 강제
if (!isForMainFrame || !hasUserGesture) {
Log.w("WebViewDebug", "메인 프레임이 아니거나 제스처가 없는 스킴 차단됨: $scheme")
return true
}
// 3. Chrome intent:// URI 파싱 및 실패 차단 정화
if (scheme == "intent") {
return handleIntentUri(view, targetUri.toString(), isPopupContext)
}
// 4. 허용된 커스텀 URL 스킴의 유효성을 검사하고 1대1 검증된 타겟 패키지에 명시적으로 바인딩
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. 모든 인식할 수 없는 스킴 차단
Log.w("WebViewDebug", "인식할 수 없는 URL 스킴 차단됨: $scheme")
return true
}
// 302 리디렉션을 승인된 세션에 연결하는 하위 팝업 WebView용 UI 스레드 탐색 평가기
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", "팝업 내부의 서브프레임 HTTPS 탐색 차단됨")
return true
}
if (!policy.isAllowedPopupUri(targetUri)) {
Log.w("WebViewDebug", "신뢰할 수 없는 팝업 HTTPS 호스트 또는 경로 탐색 차단됨")
return true
}
// 초기 로드 또는 사용자 탭이 허용 목록과 일치할 때 UI 스레드에서만 세션 승인
if (isInitialTransportLoad || hasUserGesture) {
onAuthorizedInitialSession()
return false
}
// 이전에 승인된 팝업 세션에 대해서만 제한된 서버 측 302 리디렉션 허용
if (isRedirect && isAuthorizedPopupSession && canProceedPopupRedirect()) {
return false
}
Log.w("WebViewDebug", "승인되지 않은 리디렉션 또는 제스처가 없는 팝업 탐색 차단됨")
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", "잘못된 인텐트 URI 구문")
return true
}
val fallbackUrl = parsedIntent.getStringExtra("browser_fallback_url")
parsedIntent.removeExtra("browser_fallback_url")
// 1대1 바인딩: 타겟 스킴 추출 및 예상 타겟 패키지에 대해 네이티브로 유효성 검사
val dataUri = parsedIntent.data ?: return true
val targetScheme = dataUri.scheme?.lowercase() ?: return true
val expectedPackage = policy.customSchemeTargetPackages[targetScheme] ?: run {
Log.w("WebViewDebug", "매핑되지 않은 커스텀 스킴이 있는 인텐트 차단됨: $targetScheme")
return true
}
val rawPackage = parsedIntent.`package`
if (rawPackage != expectedPackage) {
Log.w("WebViewDebug", "인텐트 패키지 불일치 차단됨: 예상됨 $expectedPackage")
return true
}
// 웹페이지가 지정한 명시적 컴포넌트 및 셀렉터 즉시 거부
if (parsedIntent.component != null || parsedIntent.selector != null) {
Log.w("WebViewDebug", "명시적 컴포넌트 또는 셀렉터가 있는 인텐트 차단됨")
return true
}
// 허용되지 않는 필드/플래그에 대한 빌더 상호 배제 제약을 피하고 신뢰할 수 없는 플래그/엑스트라를 엄격하게 거부하기 위해
// allowAnyComponent()로 IntentSanitizer를 호출하기 전에 검증된 패키지를 일시적으로 지웁니다.
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가 SecurityException 발생시킴")
return true
} catch (e: IllegalArgumentException) {
Log.w("WebViewDebug", "IntentSanitizer가 잘못된 인텐트 인수를 거부함")
return true
}
// 검증된 타겟 패키지 + 호스트 강제 카테고리 + 정화 후 단언 재바인딩
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", "정화 후 인텐트 단언 실패함")
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", "신뢰할 수 없거나 루프를 유발하는 대체 URL 차단됨")
}
}
} catch (e: SecurityException) {
Log.w("WebViewDebug", "SecurityException이 인텐트 실행을 차단함")
}
return true
}
private fun launchIntentSafely(view: WebView, intent: Intent) {
try {
launchWithContextSafety(view, intent)
} catch (e: ActivityNotFoundException) {
Log.i("WebViewDebug", "타겟 패키지/스킴을 처리하는 설치된 애플리케이션이 없음")
} catch (e: SecurityException) {
Log.w("WebViewDebug", "SecurityException이 커스텀 스킴 실행을 차단함")
}
}
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. 수명 주기 관리 팝업 WebChromeClient (엄격한 UI 스레드 세션 상태 및 상태 비저장 백그라운드 가드)
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 = "목적지 로딩 중..."
}
popupRoot.addView(originBanner)
// 아래의 모든 팝업 세션 상태 변수는 UI 스레드에서 엄격하게 읽히고 변경됩니다.
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 스레드: 탐색, 리디렉션, 세션 승인 상태 소유
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
}
// 백그라운드 WebView IO 스레드: 엄격한 상태 비저장, 읽기 전용 정책 검사.
// UI 스레드 세션 상태를 절대 변경하지 않음; 초기 리소스 URL만 다룸 (후속 302 홉 제외).
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", "shouldInterceptRequest에서 승인되지 않은 팝업 메인 프레임 요청 차단됨")
childView.post { disposeActivePopup() }
return WebResourceResponse("text/plain", "utf-8", ByteArrayInputStream(ByteArray(0)))
}
}
return super.shouldInterceptRequest(childView, request)
}
// UI 스레드: 탐색 시작 대체 검사 및 원점 표시 (사전 탐색 필터 아님)
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", "탐색 시작 대체 검사가 승인되지 않은 팝업 URL을 종료함")
childView.stopLoading()
disposeActivePopup()
return
}
isAuthorizedPopupSession = true
val scheme = uri.scheme?.lowercase() ?: "https"
val host = uri.host?.lowercase() ?: "Unknown"
originBanner.text = "원점: $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. 완전한 호스트 활동 등록 및 수명 주기 정리 예제 (메인 WebView에서 JavaScript 활성화)
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 {
// JS 리디렉션이나 window.open()이 필요한 신뢰할 수 있는 랜딩 페이지에 대해 JavaScript를 명시적으로 활성화
javaScriptEnabled = true
allowFileAccess = false
allowContentAccess = false
// 인터랙티브 팝업 컨테이너를 호스팅하는 경우에만 다중 창 활성화
setSupportMultipleWindows(true)
}
webViewClient = safeClient
webChromeClient = popupChromeClient
}
setContentView(webView)
// 기본 webView.loadUrl() 대신 명시적 호스트 래퍼 사용
safeClient.loadNewNavigation(webView, "https://example.com/landing")
}
override fun onDestroy() {
popupChromeClient.destroyPopups()
(webView.parent as? ViewGroup)?.removeView(webView)
webView.destroy()
super.onDestroy()
}
}
자주 묻는 질문 (FAQ)
타겟 앱이 설치되어 있음에도 Android WebView에 net::ERR_UNKNOWN_URL_SCHEME가 표시되는 이유는 무엇인가요?
앱이 WebView loadUrl을 직접 호출할 때 shouldOverrideUrlLoading이 발생하지 않는 이유는 무엇인가요?
커스텀 스킴을 사용하는 target blank 링크가 WKWebView 내에서 조용히 실패하는 이유는 무엇인가요?
요약 및 의사결정 프레임워크
WebView 딥러닝 리디렉션 실패를 해결하려면 WebView 엔진 동작을 호스트 애플리케이션 탐색 정책에서 분리해야 합니다. Chrome DevTools 또는 Safari Web Inspector에서 탐색 이벤트를 재현하고, 상태 비저장 초기 요청 스크리닝을 세션 승인 302 리디렉션 검사와 페어링하면서 Android 팝업 세션 상태를 UI 스레드에 엄격히 제한하고, 실패 차단(fail-closed) IntentSanitizer 허용 목록을 강제하며, 오래된 비동기 덮어쓰기 및 중복 델리게이트 실행에 대비하여 iOS 유니버설 링크 대체(fallback)를 보호함으로써 엔지니어링 팀은 손상된 사용자 여정을 줄이고 클라이언트 측 리디렉션 취약점을 예방하는 데 도움을 받을 수 있습니다.
컨테이너 레벨의 네이티브 델리게이트와 대체 경로가 검증된 후, 엔지니어링 팀은 OpoInstall 같은 플랫폼을 사용하여 엔드투엔드 어트리뷰션 랜딩 페이지와 원클릭 런치 라우팅 체인을 검증함으로써 브라우저-앱 전환 전반에 걸쳐 매개변수가 보존되는지 확인해야 합니다.
엔티티 용어집
| 용어 | 정의 | 관련 엔티티 | 검색 의도 역할 |
|---|---|---|---|
| WebView | 모바일 애플리케이션 내에서 웹페이지를 렌더링하는 데 사용되는 내장 네이티브 UI 컴포넌트입니다. | WebViewClient / WKWebView |
정보성 / 기술적 |
| 커스텀 URL 스킴 | 네이티브 화면으로의 외부 탐색을 가능하게 하는 앱 등록 URI 접두사(예: myapp://)입니다. |
Intent.ACTION_VIEW |
기술적 / 정보성 |
| WKNavigationDelegate | 호스트 앱이 WKWebView에서 탐색 액션을 수락, 취소 또는 리디렉션할 수 있도록 하는 WebKit 프로토콜입니다. |
decidePolicyForNavigationAction |
기술적 |
| WKUIDelegate | WKWebView에서 새 창 생성 요청을 처리하는 역할을 담당하는 WebKit 프로토콜입니다. |
createWebViewWith |
기술적 |
| WebResourceRequest | URL, 프레임, HTTP 메서드, 리디렉션 및 제스처 메타데이터를 캡슐화하는 Android API 24+ 객체입니다. | shouldOverrideUrlLoading |
기술적 |
| WebChromeClient | JavaScript 대화상자, 진행 상황 및 onCreateWindow를 처리하는 Android WebView 콜백 인터페이스입니다. |
WebViewTransport |
기술적 |
| IntentSanitizer | 디스패치 전에 신뢰할 수 없는 인텐트 필드를 필터링하거나 엄격하게 검증하는 데 사용되는 AndroidX Core 유틸리티입니다. | 인텐트 리디렉션 방어 | 기술적 / 보안 |
| 유니버설 링크 (Universal Links) | 검증된 웹 도메인을 설치된 iOS 애플리케이션에 연결하는 Apple의 HTTPS 기반 딥러닝 표준입니다. | 연결된 도메인 (Associated Domains) | 기술적 / 정보성 |
| 패키지 가시성 (Package Visibility) | 호스트 앱이 PackageManager를 통해 쿼리할 수 있는 설치된 앱을 제한하는 Android 11+ (targetSdk >= 30) OS 필터링입니다. |
<queries> 매니페스트 태그 |
기술적 |
| 인텐트 URI | 대상 패키지, 스킴 및 브라우저 대체 URL을 인코딩하는 구조화된 Android URI(intent://)입니다. |
Intent.URI_INTENT_SCHEME |
기술적 |
호환성 기준 및 검증 상태
-
의도된 호환성 타겟: Android
minSdk 24,compileSdk 34/35,targetSdk 34/35(Android 14/15), Android 16 (API 36) 인텐트 리디렉션 하드닝 컨텍스트,androidx.core:core:1.9.0+(IntentSanitizer); iOS 15.0–18.0 (iOS 16.4+에서 게이트된isInspectable), Xcode 15/16, Swift 5.9/6.0. -
검증 상태:
-
정적 API 및 명세 검토: 공식 Android Developers, AndroidX Core, Apple Developer, IETF RFC 3986 및 OWASP MASTG 명세에 대해 완료되었습니다.
-
컴파일 및 실물 기기 검증: 이번 검토 주기에선 아직 실행되지 않았습니다. 프로덕션 롤아웃 전에 팀은 악의적인 초기 팝업 URL, 크로스 도메인 302 체인, 연속 302 홉, 타사 iframe 창 생성, Android 앱 링크(
assetlinks.json), iOS 연결된 도메인(AASA 캐싱), 오래된 비동기 유니버설 링크 취소,intent://대체 체인 및ActivityNotFoundException디스패치를 다루는 실물 기기 회귀 테스트를 컴파일하고 실행해야 합니다.
-
참고 자료
Share this article



