Как включить поддержку Universal Links внутри iOS WKWebView? Universal Links могут обрабатываться внутри WKWebView для соответствующих ссылок. Реализация WKNavigationDelegate позволяет хост-приложению настраивать политики маршрутизации: перехватывать внутренние переходы приложения, контролировать передачу управления внешним обработчикам через decidePolicyForNavigationAction и обеспечивать безопасность на уровне фреймов.
В архитектуре iOS-приложений перехват навигации WKWebView позволяет приложению адаптировать политику маршрутизации для Universal Links, пользовательских схем URL и веб-ресурсов. Анализируя метаданные запросов навигации в рамках WKNavigationDelegate, приложение может направлять внутренние переходы напрямую, делегировать внешние цели системным обработчикам и применять политики безопасности для фреймов.
| Термин | Определение | Связанная сущность | Роль в поиске |
|---|---|---|---|
| WebView | Встраиваемый компонент на базе WebKit для отображения интерактивного веб-контента в приложениях iOS. | iOS SDK | Информационный / Коммерческий |
| Universal Links | Стандартный механизм HTTPS для связи верифицированных веб-доменов с нативными экранами приложений iOS. | Маршрутизация Deep Link | Технический / Информационный |
| Custom URL Scheme | Определяемая приложением схема URI для передачи URL в нативное приложение. | Mobile Deep Linking | Информационный |
Взаимодействие WKWebView и маршрутизации Universal Links в iOS

Жизненный цикл навигации WebKit и политики внутренней маршрутизации
Apple реализовала Universal Links как системный механизм маршрутизации, поддерживаемый как в Safari, так и в WKWebView. Когда пользователь нажимает на подходящую ссылку внутри встроенного WKWebView, система может распознать ассоциацию с доменом и выполнить маршрутизацию в соответствии с политиками ОС.
Хотя системно распознаваемые Universal Links могут передавать выполнение нативным обработчикам, встроенные браузерные окружения часто требуют специфической для приложения логики маршрутизации. Например, если ссылка ведет на собственный домен приложения, разработчики часто предпочитают переходить напрямую через нативные контроллеры представлений, избегая полного перезапуска внешнего приложения. Использование WKNavigationDelegate дает приложению детальный контроль над обработкой ссылок, позволяя командам применять списки разрешенных доменов и предсказуемо направлять внутренние переходы.
Барьер пользовательского опыта: когда встроенные WebView зацикливают пользователей
Встроенные WebView часто используются для отображения рекламных микросайтов, центров поддержки, каталогов партнеров и маркетинговых целевых страниц внутри iOS-приложений. Когда веб-страница внутри приложения содержит ссылки, предназначенные для перенаправления пользователя в другие разделы того же приложения (например, кнопки «Открыть в приложении») или в приложения партнеров, навигация по умолчанию может привести к дублирующему рендерингу:
- Избыточный веб-рендеринг: Вместо открытия нативных контроллеров пользователю демонстрируются веб-версии страниц, что требует повторной аутентификации и нарушает визуальную целостность интерфейса.
- Веб-ловушка: Пользователи могут оказаться заблокированы в стеке навигации WebView без интуитивно понятных способов вернуться к основным интерфейсам приложения.
- Сбои при переходе между приложениями: При нажатии на ссылки сторонних сервисов (например, навигационных приложений, диалогов соцсетей или платежных шлюзов) требуется явное делегирование, если эти сервисы полагаются на пользовательские схемы URL.
Сравнение WKWebView и SFSafariViewController для связки Web-to-App
При архитектурной разработке встроенного веб-браузера для iOS команды должны выбирать между WKWebView и SFSafariViewController:
SFSafariViewController: Предоставляет управляемый системой, изолированный интерфейс Safari с функциями автозаполнения и блокировки контента. Хост-приложение не может проверять активность просмотра или данные сайта, а настройка UI ограничена цветами оттенков (tint colors).WKWebView: Встраиваемый компонент представления, размещенный в процессе UI приложения, в то время как веб-контент выполняется в отдельных процессах WebKit. Он обеспечивает глубокую настройку UI, JavaScript-мосты и интеграцию пользовательской верстки, требуя явной реализацииWKNavigationDelegateдля настройки политики маршрутизации и обработки кастомных схем.
Как decidePolicyForNavigationAction перехватывает маршрутизацию WebKit
Конвейер политики навигации: WKNavigationAction, request и decisionHandler
Для контроля потока навигации внутри WKWebView разработчики назначают делегат, соответствующий рекомендациям Apple по WKNavigationDelegate. Основной точкой перехвата является метод делегата:
func webView(
_ webView: WKWebView,
decidePolicyFor navigationAction: WKNavigationAction,
decisionHandler: @escaping (WKNavigationActionPolicy) -> Void
)
Действия навигации, инициированные взаимодействием пользователя, программными редиректами или отправкой форм, проходят через этот метод. Объект WKNavigationAction предоставляет ключевые метаданные:
navigationAction.request.url: ЦелевойURLзапроса.navigationAction.navigationType: Тип триггера (.linkActivated,.other,.formSubmitted).navigationAction.sourceFrame: Информация о фрейме, инициировавшем запрос.navigationAction.targetFrame: Информация о целевом фрейме, где должен загрузиться контент.
decisionHandler — это замыкание завершения, которое информирует WebKit, разрешить или отменить запрошенную навигацию.
Когда возвращать .allow, а когда .cancel: управление загрузкой ресурсов WebKit
WKNavigationActionPolicy, передаваемый в decisionHandler, определяет дальнейшие действия WebKit:
.allow: Дает команду WebKit продолжить навигацию внутри веб-представления..cancel: Дает команду WebKit отменить навигацию. Эта политика применяется, если хост-приложение перехватывает кастомную схему, направляет Universal Link внутри приложения или делегирует переход внешнему приложению черезUIApplication.shared.open().
decisionHandler должен быть вызван ровно один раз для каждого действия навигации, чтобы предотвратить зависание процесса.
Оценка типов навигации: различение кликов (.linkActivated) и автоматических редиректов
WKNavigationAction.navigationType позволяет разработчикам отличить осознанные действия пользователя от работы автоматических скриптов:
.linkActivated: Пользователь физически нажал на HTML-анкор (<a href="...">)..other: Представляет программную навигацию, такую как обновлениеwindow.location.href, мета-рефреши или начальные вызовыwebView.load()..formSubmitted/.formResubmitted: Представляет отправку форм методом POST или GET.
Оценка navigationType позволяет приложениям соблюдать консервативную политику навигации. Для вызова внешних схем или перехода в сторонние приложения требование .linkActivated в качестве шлюза помогает предотвратить запуск внешних приложений скриптами в фоновом режиме.
Обработка асинхронных политик без retain-циклов
Когда для принятия решения требуется запрос к локальным кэшам или проверка безопасности:
- Убедитесь, что
decisionHandlerвызывается во всех ветках выполнения, включая условия ошибок и guard-условия. - Используйте слабые ссылки (
[weak self]) внутри замыканий, чтобы предотвратить циклы удержания памяти междуWKWebView, его делегатом и родительскимUIViewController.
Отличие ассоциированных доменов приложения от внешних Universal Links

Управление собственными маршрутами против делегирования системных ссылок
Для маршрутов, принадлежащих самому приложению, избегайте попыток повторного входа через стандартный Universal Link. Обрабатывайте такие назначения напрямую через внутренний роутер приложения, а системный запуск используйте в основном для переходов, которые должны покинуть текущее приложение или обрабатываться внешними сервисами.
Такое разделение архитектуры обеспечивает плавную навигацию:
- Ассоциированные домены хост-приложения: Если URL соответствует собственному ассоциированному домену приложения (
app.example.com), отмените навигацию в веб-представлении (decisionHandler(.cancel)), проверьте путь маршрута и передайте параметры напрямую внутреннему роутеру приложения. - Внешние приложения: Если URL указывает на внешний ресурс партнера или разрешенную кастомную схему, примените шлюз явной активации (
navigationType == .linkActivated), отмените навигацию и перенаправьте запрос вUIApplication.shared.open(url), позволяя системе запустить внешнее приложение.
Архитектура проверки внутренних маршрутов: извлечение путей и параметров через AppRouteValidator
Когда входящий URL соответствует ассоциированному домену, он должен пройти через строгий валидатор маршрутов перед переходом к контроллеру представления.
Модель AppRouteValidator:
- Проверяет путь URL по «белому списку» поддерживаемых внутренних маршрутов (например,
/open/,/product/,/promo/,/checkout/). - Извлекает параметры запроса (например,
id,promo,utm_source). - Применяет ограничения по набору символов, длине и отклоняет дубликаты ключей, возвращая очищенную структуру данных
ValidatedAppRoute.
Обработка сторонних Universal Links через делегирование UIApplication

Когда веб-страница внутри WKWebView ссылается на внешние сервисы (например, приложения партнеров, соцсети или утилиты), хост-приложение может делегировать маршрутизацию системе iOS:
let options: [UIApplication.OpenExternalURLOptionsKey: Any] = [
.universalLinksOnly: true
]
UIApplication.shared.open(url, options: options) { success in
if !success {
// Фолбэк политики: загрузить веб-назначение, если нативное приложение не обработало Universal Link
}
}
Использование .universalLinksOnly гарантирует, что пользователь покинет текущее приложение только в том случае, если на устройстве установлено верифицированное нативное приложение для обработки данной ссылки.
Управление фолбэками пользовательских схем (myapp://) вместе с HTTPS Universal Links
Хотя HTTPS Universal Links представляют стандарт глубоких ссылок в iOS, определяемые приложениями схемы (myapp:// или partnerapp://) остаются распространенными в акциях и партнерских интеграциях.
В единой реализации WKNavigationDelegate:
- Сначала проверяются схемы, не являющиеся HTTP/HTTPS. Если схема соответствует разрешенному протоколу и удовлетворяет политике активации (
navigationType == .linkActivated), делегат верифицирует хост, путь и параметры перед отправкой вUIApplication.shared.open(). - Нераспознанные схемы или автоматические вызовы схем немедленно отменяются, предотвращая ошибки или попытки навязанного перехода.
[Пользователь взаимодействует со ссылкой внутри iOS WKWebView]
│
▼
[WKNavigationDelegate: decidePolicyForNavigationAction]
│
┌─────────────┴─────────────┐
▼ ▼
[!action.sourceFrame.isMainFrame] [action.sourceFrame.isMainFrame]
│ │
▼ ▼
[Защита от фреймов] [Проверка схемы и хоста]
├─ HTTP(S) -> .allow │
└─ Не-веб -> .cancel ┌───────────┼───────────┐
(Блок фрейма) ▼ ▼ ▼
[Хост домена] [Внешний веб] [Кастомная схема]
│ │ │
▼ ▼ ▼
[AppRoute] [Check Link] [Check Link]
├─ Valid -> ├─ Partner-> ├─ Valid & Click->
│ Internal │ Open App │ Open App
└─ Invalid-> └─ Web -> └─ Invalid/Auto->
.cancel .allow .cancel
Обеспечение безопасности главного фрейма и предотвращение iframe-захвата

Отношение к встроенной веб-навигации как к недоверенным данным: стандарты безопасности OWASP
В соответствии с руководством OWASP по тестированию безопасности мобильных приложений (Insecure Deep Links), все URL и параметры, обрабатываемые навигационными обработчиками, должны считаться недоверенными, внешними данными.
Веб-страницы, отображаемые в WKWebView, могут загружать сторонние скрипты, рекламные баннеры или пользовательский контент. Если навигационный делегат пересылает произвольные URL нативным контроллерам без проверки, неожиданные параметры могут направить пользователя на чувствительные внутренние маршруты.
Изоляция навигации главного фрейма от встроенных iframes и новых окон
В соответствии с документацией Apple по WKNavigationAction, оценка безопасности требует проверки инициирующего фрейма:
sourceFrame.isMainFrame == true: Навигация инициирована напрямую первичным фреймом верхнего уровня.sourceFrame.isMainFrame == false: Навигация инициирована встроенным подфреймом или iframe.targetFrame == nil: Запрос навигации в новое окно (например, анкор сtarget="_blank").
Чтобы предотвратить iframe-захват (когда внедренный iframe пытается запустить внешнее приложение или вызвать смену нативных экранов в фоне), делегат должен проверять sourceFrame.isMainFrame. Если это iframe (false), разрешайте стандартную навигацию HTTP/HTTPS (.allow), но блокируйте любые нестандартные схемы или нативные переходы (.cancel).
Предотвращение вредоносных вызовов из подфреймов
Проверка инициирующего фрейма предотвращает несанкционированные попытки запуска схем из подфреймов:
if !navigationAction.sourceFrame.isMainFrame {
let scheme = url.scheme?.lowercased() ?? ""
if scheme == "http" || scheme == "https" {
decisionHandler(.allow) // Разрешить стандартную HTTP(S) навигацию в подфрейме
} else {
decisionHandler(.cancel) // Заблокировать не-веб схемы из подфреймов
}
return
}
Принудительное использование «белых списков» путей и параметров
Как внутренние домены, так и внешние кастомные схемы должны проходить через строгие модели валидации перед выполнением:
- Белый список префиксов путей: Разрешайте только одобренные маршруты (например,
/open/,/product/,/promo/,/checkout/), отклоняя произвольные или поврежденные пути. - Фильтрация ключей запроса: Удаляйте неожиданные ключи и отклоняйте дубликаты параметров для предотвращения «загрязнения» параметров.
- Ограничения типов и длины: Ограничивайте значения параметров буквенно-цифровым набором и максимальной длиной (≤ 64 символов).
Реализация WKNavigationDelegate в Swift для продакшена
Архитектура CustomWebViewController и делегатов в Swift
Контроллер WKWebView для продакшена координирует настройки, оценку политики, внутреннюю маршрутизацию и внешнее делегирование. Реализация инкапсулирует правила проверки внутри специализированных классов-валидаторов (AppRouteValidator и CustomSchemeValidator), сохраняя чистоту, тестируемость и безопасность кода.
Реализация моделей AppRouteValidator и CustomSchemeValidator
Валидаторы обеспечивают строгое соблюдение безопасности:
AppRouteValidatorпроверяет внутренние ассоциированные домены, контролируя префиксы путей и санируя параметры в объектValidatedAppRoute.CustomSchemeValidatorверифицирует авторизованные схемы (myapp), проверяет разрешенные хосты (open,product,event) и очищает значения параметров.
OpoInstall может быть интегрирован вместе со слоем маршрутизации приложения для атрибуции и восстановления параметров (deferred deep linking). Изучите документацию по интеграции SDK для получения комплексных руководств.
Техническая реализация ниже демонстрирует, как настроить безопасный WKNavigationDelegate на языке Swift:
// iOS: CustomWebViewController со строгой маршрутизацией WKNavigationDelegate и защитой фреймов
// Пример интеграции. Проверьте сигнатуры методов и доменные маппинги для вашей архитектуры.
import UIKit
import WebKit
struct ValidatedAppRoute {
let path: String
let queryParams: [String: String]
}
// 1. Валидатор для ассоциированного домена приложения (внутренние маршруты)
class AppRouteValidator {
private static let allowedPrefixes = ["/open/", "/product/", "/promo/", "/checkout/"]
private static let allowedQueryKeys = Set(["target", "id", "promo", "utm_source"])
static func validate(url: URL) -> ValidatedAppRoute? {
let path = url.path
// Принудительный белый список префиксов путей
guard allowedPrefixes.contains(where: { path.hasPrefix($0) }) else {
return nil
}
var sanitizedParams: [String: String] = [:]
var seenKeys = Set<String>()
if let components = URLComponents(url: url, resolvingAgainstBaseURL: false),
let queryItems = components.queryItems {
let validChars = CharacterSet(charactersIn: "abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789_-")
for item in queryItems {
// Безопасная валидация: отклонить URL при наличии неавторизованных ключей или дубликатов
guard allowedQueryKeys.contains(item.name), !seenKeys.contains(item.name) else { return nil }
seenKeys.insert(item.name)
let value = item.value ?? ""
if value.count <= 64 && value.rangeOfCharacter(from: validChars.inverted) == nil {
sanitizedParams[item.name] = value
} else {
return nil
}
}
}
return ValidatedAppRoute(path: path, queryParams: sanitizedParams)
}
}
// 2. Валидатор для внешних кастомных схем (myapp://)
class CustomSchemeValidator {
private static let allowedSchemes = Set(["myapp"])
private static let allowedHosts = Set(["open", "product", "event"])
private static let allowedPathPrefixes = ["/detail/", "/view/", "/main/"]
private static let allowedQueryKeys = Set(["target", "id", "promo", "utm_source"])
static func validate(url: URL) -> URL? {
guard let scheme = url.scheme?.lowercased(), allowedSchemes.contains(scheme) else {
return nil
}
guard let host = url.host?.lowercased(), allowedHosts.contains(host) else {
return nil
}
let path = url.path
if !path.isEmpty && !allowedPathPrefixes.contains(where: { path.hasPrefix($0) }) {
return nil
}
var seenKeys = Set<String>()
if let components = URLComponents(url: url, resolvingAgainstBaseURL: false),
let queryItems = components.queryItems {
let validChars = CharacterSet(charactersIn: "abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789_-")
for item in queryItems {
guard allowedQueryKeys.contains(item.name), !seenKeys.contains(item.name) else { return nil }
seenKeys.insert(item.name)
let value = item.value ?? ""
if value.count > 64 || value.rangeOfCharacter(from: validChars.inverted) != nil {
return nil
}
}
}
return url
}
}
// 3. UIViewController с WKWebView и безопасным перехватом политики навигации
class CustomWebViewController: UIViewController, WKNavigationDelegate {
var webView: WKWebView!
private let hostAssociatedDomain = "app.example.com"
private let allowedExternalPartnerHosts = Set(["partner.example.com"])
override func viewDidLoad() {
super.viewDidLoad()
let configuration = WKWebViewConfiguration()
webView = WKWebView(frame: view.bounds, configuration: configuration)
webView.navigationDelegate = self
view.addSubview(webView)
}
func webView(
_ webView: WKWebView,
decidePolicyFor navigationAction: WKNavigationAction,
decisionHandler: @escaping (WKNavigationActionPolicy) -> Void
) {
guard let url = navigationAction.request.url else {
decisionHandler(.allow)
return
}
// Проверка 1: Граница фрейма (sourceFrame) для предотвращения iframe-захвата
if !navigationAction.sourceFrame.isMainFrame {
let scheme = url.scheme?.lowercased() ?? ""
if scheme == "http" || scheme == "https" {
decisionHandler(.allow) // Разрешить стандартную HTTP(S) навигацию в подфрейме
} else {
decisionHandler(.cancel) // Заблокировать не-веб схемы
}
return
}
let scheme = url.scheme?.lowercased() ?? ""
let isExplicitLinkActivation = (navigationAction.navigationType == .linkActivated)
// Проверка 2: Ассоциированный домен хоста
// Маршрутизировать внутри вместо вызова UIApplication.shared.open
if scheme == "https", let host = url.host?.lowercased(), host == hostAssociatedDomain {
if let validatedRoute = AppRouteValidator.validate(url: url) {
AppInternalRouter.shared.navigate(to: validatedRoute)
}
decisionHandler(.cancel) // Отменить загрузку в webview для внутренней маршрутизации
return
}
// Проверка 3: Кастомные схемы (myapp://) с политикой активации ссылкой
if scheme != "http" && scheme != "https" && scheme != "about" {
// Запуск внешнего приложения требует явного клика пользователя
if isExplicitLinkActivation, let validatedURL = CustomSchemeValidator.validate(url: url) {
UIApplication.shared.open(validatedURL, options: [:], completionHandler: nil)
}
decisionHandler(.cancel) // Отменить в webview во избежание ошибок неизвестных схем
return
}
// Проверка 4: Внешние цели и запросы target="_blank"
if scheme == "http" || scheme == "https" {
let host = url.host?.lowercased() ?? ""
// Делегировать партнерские Universal Links внешнему приложению
if allowedExternalPartnerHosts.contains(host) && isExplicitLinkActivation {
let options: [UIApplication.OpenExternalURLOptionsKey: Any] = [
.universalLinksOnly: true
]
UIApplication.shared.open(url, options: options) { [weak self] success in
if !success {
// Фолбэк: загрузить внешнюю партнерскую цель внутри web view
guard let self = self else { return }
self.webView.load(navigationAction.request)
}
}
decisionHandler(.cancel)
return
}
// Если targetFrame равен nil (новое окно), безопасно загрузить в текущий webView
if navigationAction.targetFrame == nil {
webView.load(navigationAction.request)
decisionHandler(.cancel)
return
}
// Стандартный веб-контент загружается внутри WKWebView
decisionHandler(.allow)
return
}
decisionHandler(.allow)
}
}
// Внутренний роутер приложения (не API SDK OpoInstall)
class AppInternalRouter {
static let shared = AppInternalRouter()
func navigate(to route: ValidatedAppRoute) {
// Выполнить переход к UI контроллеру на основе пути и параметров
}
}
Потокобезопасность: выполнение UI-переходов в Main Actor
В текущих моделях параллелизма Swift обратные вызовы WKNavigationDelegate изолированы в Main Actor. Маршрутизация приложения и переходы к контроллерам выполняются в основном потоке, что обеспечивает безопасность потоков в нативных рабочих процессах.
Ошибки навигации Deep Link в WKWebView и матрица диагностики
Комплексное руководство по устранению неполадок Deep Linking в iOS WKWebView
Матрица ниже описывает распространенные сбои при работе с глубокими ссылками и кастомными схемами в iOS WKWebView, а также рекомендации по их устранению:
| Симптом ошибки | Основная причина | Версии iOS | Контрольная точка | Рекомендованное решение |
|---|---|---|---|---|
| Universal Link открывается в Web | Домен приложения не перехвачен | iOS 9+ | decidePolicyForNavigationAction не обработан |
Перехватить домен, распарсить путь, маршрутизировать внутри, .cancel |
| Ссылка на собственный домен не работает | Вызов UIApplication.open на свой домен |
iOS 9+ | UIApplication.shared.open для своего хоста |
Избегать внешнего вызова; использовать внутренний роутер напрямую |
| Кастомная схема не работает (тихо) | WebKit не распознал протокол | iOS 9+ | Схема не передана в UIApplication |
Перехватить схему в делегате, валидировать, открыть через UIApplication |
| Iframe-захват протокола | Подфрейм инициирует внешнюю схему | iOS 9+ | sourceFrame.isMainFrame не проверен |
Использовать if !sourceFrame.isMainFrame и подавить не-веб схемы |
| Проблемы с переходом UI | UI-переходы не в главном потоке | iOS 9+ | Отсутствует вызов в MainActor |
Обеспечить выполнение UI-переходов в основном потоке |
Часто задаваемые вопросы (FAQ)
Как разработчики могут перехватывать Universal Links в WKWebView?
Могу ли я использовать UIApplication.shared.open для открытия своего приложения из WKWebView?
Как предотвратить запуск внешних приложений через встроенные iframes в WKWebView?
Резюме и фреймворк принятия решений
Обработка Universal Links и пользовательских схем внутри iOS WKWebView требует преодоления границы между контейнером рендеринга WebKit и нативным жизненным циклом UIKit. Полагаться на политики навигации по умолчанию может помешать бесшовной работе, если требуется логика маршрутизации самого приложения.
Реализуя надежный WKNavigationDelegate, который проверяет границы фреймов, обеспечивает консервативные политики активации ссылок, анализирует внутренние ассоциированные домены через строгие валидаторы и безопасно делегирует внешние цели в UIApplication.shared.open, инженерные команды поддерживают контролируемую навигацию, защищаясь при этом от iframe-захвата протоколов.
Чтобы подробнее изучить архитектуру глубоких ссылок и маршрутизации параметров для нативных iOS-приложений, обратитесь к документации по интеграции SDK.
Сопутствующие материалы
-
Концепции: Маршрутизация iOS WebView, перехват Universal Links, WKNavigationDelegate, изоляция границ фреймов
-
Технологии: Apple WebKit, iOS UIKit, WKWebView, OpoInstall iOS SDK
-
Стандарты: IETF RFC 3986 (URI), спецификация ассоциированных доменов Apple, руководство OWASP по тестированию мобильных приложений (MASTG)
-
API:
WKNavigationDelegate.decidePolicyForNavigationAction,WKNavigationAction.sourceFrame,UIApplication.shared.open -
Официальная документация и ссылки:
Share this article



