WKWebViewでユニバーサルリンクをサポートするルーティング設定方法

opoinstall
2026-10-07
5 min read

iOSのWKWebView内でユニバーサルリンクを有効にするにはどうすればよいですか? ユニバーサルリンクは、WKWebView内の適切なリンクから解決可能です。WKNavigationDelegateを実装することで、ホストアプリケーションはルーティングポリシーをカスタマイズできます。具体的には、自社アプリの宛先をインターセプトし、decidePolicyForNavigationActionを通じて外部へのハンドオフを制御し、フレームレベルのセキュリティを強化します。

iOSアプリケーションのアーキテクチャにおいて、WKWebViewのナビゲーションインターセプト機能を使用すると、ユニバーサルリンク、カスタムURLスキーム、およびWeb上の目的地にわたるルーティングポリシーをアプリ側でカスタマイズできます。WKNavigationDelegate内でナビゲーションリクエストのメタデータを評価することで、アプリ内コンテンツへの遷移を内部的にルーティングし、外部ターゲットをシステムハンドラーへ委任し、フレームレベルのセキュリティポリシーを適用することが可能になります。

用語 定義 関連エンティティ 検索意図
WebView iOSアプリ内でインタラクティブなWebコンテンツを描画する、WebKitベースの埋め込みビューコンポーネント。 iOS SDK 情報提供 / 商用
ユニバーサルリンク 検証済みのWebドメインとネイティブiOSアプリの画面をリンクさせる標準的なHTTPSメカニズム。 ディープリンクルーティング 技術 / 情報提供
カスタムURLスキーム URLをネイティブアプリへルーティングするためにアプリ独自に定義されたURIスキーム。 モバイルディープリンク 情報提供

iOSにおけるWKWebViewとユニバーサルリンクルーティングの相互作用

WKNavigationDelegateはWebKitがコンテンツを読み込むか、内部ルーティングするか、外部へ引き渡すか、あるいはキャンセルするかを判断します。

WebKitのナビゲーションライフサイクルとアプリ固有のルーティングポリシー

Appleは、SafariおよびWKWebView環境でサポートされるシステムレベルのルーティングメカニズムとしてユニバーサルリンクを実装しています。ユーザーが埋め込みのWKWebView内の有効なリンクをタップすると、プラットフォームはドメインの関連付けを解決し、OSのポリシーに従って実行をルーティングします。

システムが認識するユニバーサルリンクはネイティブハンドラーへ実行を引き渡せますが、埋め込みブラウザ環境では多くの場合、アプリケーション固有のルーティングロジックが必要です。例えば、リンクがホストアプリ自身のドメインを指している場合、外部アプリの再起動を伴わずに、ネイティブのビューコントローラーで直接ナビゲーションする方が望ましいケースが多いでしょう。WKNavigationDelegateを実装することで、リンク評価に対する詳細な制御が可能になり、チームはカスタムの許可リストを適用し、アプリ内の目的地へ確実に遷移させることができます。

ユーザー体験の障壁:アプリ内WebブラウジングによるWebリダイレクトループ

埋め込みWebViewは、販促用マイクロサイト、ヘルプセンター、パートナー向けカタログ、マーケティング用ランディングページなどをiOSアプリ内で表示するために頻繁に使用されます。アプリ内Webページに、アプリ内の他のセクション(「アプリで表示」ボタンなど)やパートナーアプリへユーザーを誘導するためのリンクが含まれている場合、デフォルトのナビゲーションでは冗長なレンダリングが発生することがあります:

  • 冗長なWebレンダリング: ネイティブのビューコントローラーを表示する代わりに、アプリ内ページのWeb版が表示され、再認証を求められるなど、視覚的な一貫性が損なわれます。
  • Webトラップ: ユーザーが深いWebナビゲーションスタックから抜け出せなくなり、メインのネイティブアプリインターフェースへ直感的に戻れなくなることがあります。
  • アプリ間遷移の失敗: ナビゲーションアプリ、ソーシャル共有ダイアログ、決済ゲートウェイなどのサードパーティサービスを指すリンクをタップする際、それらのサービスがカスタムURLスキームに依存している場合は、明示的な処理(デリゲーション)が必要です。

Webからアプリへのハンドオフにおける WKWebView と SFSafariViewController の比較

iOSでアプリ内Webブラウジングを設計する際、エンジニアリングチームは WKWebView と SFSafariViewController のどちらかを選択する必要があります:

  • SFSafariViewController: 自動入力やコンテンツブロックなどの機能を備えた、システム管理の完結型Safariブラウジングインターフェースを提供します。ホストアプリは閲覧活動やWebサイトデータを検査できず、UIのカスタマイズは色調のみに制限されます。
  • WKWebView: アプリのUIプロセス内にホストされ、別のWebKitプロセスでWebコンテンツを実行する埋め込みビューコンポーネントです。深い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リソース読み込みライフサイクルの制御

decisionHandlerに渡されるWKNavigationActionPolicyは、WebKitがナビゲーションを進めるかどうかを制御します:

  • .allow: Webビュー内でのナビゲーションの続行を指示します。
  • .cancel: リクエストされたナビゲーションをキャンセルするよう指示します。このポリシーは、ホストアプリがカスタムスキームをインターセプトした場合や、アプリ独自のユニバーサルリンクを内部でルーティングする場合、あるいは外部ターゲットを UIApplication.shared.open() へ委任する場合に実行されます。

ナビゲーションポリシーの解決が停滞しないよう、decisionHandlerはナビゲーションアクションごとに必ず1回だけ呼び出す必要があります。

ナビゲーションタイプの評価:ユーザーのクリック(.linkActivated)と自動リダイレクトの区別

WKNavigationAction.navigationType を使用すると、明示的なユーザー操作と自動スクリプトによる動きを区別できます:

  • .linkActivated: ユーザーがHTMLアンカータグ (<a href="...">) を物理的にタップした場合。
  • .other: window.location.href の更新、メタリフレッシュ、または最初の webView.load() 呼び出しなどのプログラムによるナビゲーション。
  • .formSubmitted / .formResubmitted: フォームのPOSTまたはGET送信。

navigationTypeを評価することで、アプリレベルで「明示的なリンクのみ」という保守的なポリシーを強制できます。外部のカスタムスキーム呼び出しやサードパーティアプリへのハンドオフにおいて、.linkActivatedをポリシーのゲート(条件)として要求することは、バックグラウンドスクリプトが不意に自動的な外部アプリ起動を引き起こすのを防ぐのに役立ちます。

リテンションサイクルを発生させずに非同期ポリシー決定を処理する方法

ルートの検証や権限チェックのために、決定を下す前にローカルキャッシュやセキュリティバリデーターをクエリする必要がある場合:

  1. エラーやガード条件を含む、すべての実行パスでdecisionHandlerが実行されるようにします。
  2. WKWebView、そのデリゲート、および親のUIViewController間でのリテンションサイクルを防ぐため、エスケープクロージャ内では弱い参照 ([weak self]) を使用します。

ホストアプリの関連ドメインと外部ユニバーサルリンクの区別

アプリ自身のユニバーサルリンクは、WKWebViewから検証され、内部的にルーティングされるべきです。

アプリ自身の目的地とシステムレベルのリンク委任の管理

アプリ固有のルートについては、冗長なユニバーサルリンク検索を通じて同じアプリへ再入しようとすることは避けてください。アプリ自身の目的地はホストアプリの内部ルーターで直接処理し、現在のアプリを離れるべき目的地や外部サービスによって解決されるべき目的地にはシステムによるオープンを使用します。

このアーキテクチャ上の分離により、スムーズなナビゲーションが保証されます:

  • ホストアプリの関連ドメイン: URLのホストがホストアプリ自身の関連ドメイン (app.example.com) と一致する場合、Webビューのナビゲーションをキャンセル (decisionHandler(.cancel)) し、ルートパスを検証して、解析済みのパラメーターをアプリケーションの内部ナビゲーションルーターへ直接渡します。
  • 外部アプリケーション: URLが外部パートナーの目的地や許可されたカスタムスキームを指している場合、アプリレベルの明示的リンクゲート (navigationType == .linkActivated) を適用し、Webビューのナビゲーションをキャンセルして、リクエストを UIApplication.shared.open(url) へ転送し、OSに外部アプリを起動させます。

内部ルート検証のアーキテクチャ:AppRouteValidatorによるパスとクエリパラメーターの抽出

受信したURLがホストアプリケーションの関連ドメインと一致する場合、そのURL文字列はビューコントローラーの遷移をトリガーする前に、厳密なルーティングバリデーターを通過する必要があります。

AppRouteValidatorモデル:

  • サポートされている内部ルートの許可リスト(例:/open/, /product/, /promo/, /checkout/)に対してURLパスを検証します。
  • クエリパラメーター(例:id, promo, utm_source)を抽出します。
  • 文字セットの制限、長さの境界、重複キーの拒否を強制し、クリーンな ValidatedAppRoute データ構造を返します。

システム UIApplication デリゲーションによる外部サードパーティユニバーサルリンクの処理

外部ユニバーサルリンクはネイティブハンドオフを試行し、失敗した場合はWebへフォールバックできます。

WKWebView内のWebページが外部サービス(パートナーアプリ、ソーシャルプラットフォーム、外部ユーティリティなど)にリンクしている場合、ホストアプリはルーティングをiOSシステムへ委任できます:

let options: [UIApplication.OpenExternalURLOptionsKey: Any] = [
    .universalLinksOnly: true
]
UIApplication.shared.open(url, options: options) { success in
    if !success {
        // アプリケーションポリシーのフォールバック: ユニバーサルリンクを処理するネイティブアプリがない場合はWebへ移動
    }
}

アプリケーションポリシーとして .universalLinksOnly を使用することで、ユニバーサルリンクを処理する検証済みのネイティブアプリケーションがインストールされている場合にのみ、現在のアプリからユーザーを外部へ遷移させることができます。

HTTPSユニバーサルリンクと並行したカスタムURLスキームフォールバック (myapp://) の管理

HTTPSユニバーサルリンクはiOSにおける標準的なディープリンクですが、アプリ定義のカスタムスキーム (myapp:// や partnerapp://) は販促キャンペーンやパートナー統合において依然として一般的です。

統一された WKNavigationDelegate 実装において:

  • HTTP/HTTPS以外のスキームが最初に検査されます。スキームが許可されたカスタムプロトコルと一致し、明示的なリンクポリシー (navigationType == .linkActivated) を満たす場合、デリゲートはホスト、パス、パラメーターを検証してから UIApplication.shared.open() へディスパッチします。
  • 未認識のスキームや、ユーザー操作を伴わないバックグラウンドでのスキーム呼び出しは直ちにキャンセルされ、未処理のナビゲーションエラーやスクリプト主導の意図しないアプリ起動を防ぎます。
[ユーザーがiOS WKWebView内のリンクを操作]
                       │
                       ▼
[WKNavigationDelegate: decidePolicyForNavigationAction]
                       │
         ┌─────────────┴─────────────┐
         ▼                           ▼
[!action.sourceFrame.isMainFrame] [action.sourceFrame.isMainFrame]
         │                           │
         ▼                           ▼
[サブフレームセキュリティゲート]      [宛先のスキームとホストを検査]
├─ HTTP(S) -> .allow                 │
└─ 非Web -> .cancel    ┌───────────┼───────────┐
   (サブフレームを抑制)   ▼           ▼           ▼
                   [ホストドメイン] [外部Web] [カスタムスキーム]
                         │           │           │
                         ▼           ▼           ▼
                   [AppRoute]    [リンク確認]  [リンク確認]
                   ├─ 有効 ->   ├─ パートナー->   ├─ 有効かつクリック->
                   │  内部遷移  │  アプリ起動  │  アプリ起動
                   └─ 無効->  └─ Webへ->      └─ 無効/自動->
                      .cancel       .allow         .cancel

メインフレームのセキュリティ強化とiframeハイジャックの防止

WKNavigationActionのフレームオリジンとターゲットコンテキストが安全なナビゲーションポリシーを決定します。

埋め込みWebナビゲーションを信頼できない入力として扱う:OWASPディープリンクセキュリティ標準

不安全なディープリンクに関するOWASPモバイルアプリケーションセキュリティテストガイドのガイダンスに従い、モバイルナビゲーションハンドラーで処理されるすべてのURLおよびパラメーターペイロードは、信頼できない外部入力として扱う必要があります。

WKWebView内でレンダリングされるWebページは、サードパーティのスクリプト、広告バナー、またはユーザー生成コンテンツを読み込む可能性があります。もしナビゲーションデリゲートが検証なしに任意のURLをネイティブのビューコントローラーや UIApplication.shared.open() へ転送すると、予期しないパラメーターが機密性の高い内部アプリケーションルートを標的にする可能性があります。

メインフレームナビゲーションの埋め込みiframeおよび新規ウィンドウターゲットからの分離

WKNavigationActionに関するAppleの開発者ドキュメントに従い、フレームセキュリティを評価するには開始フレームを確認する必要があります:

  • sourceFrame.isMainFrame == true: ナビゲーションがプライマリの最上位ドキュメントフレームによって直接開始されたことを示します。
  • sourceFrame.isMainFrame == false: ナビゲーションが埋め込みサブフレームまたはiframeによって開始されたことを示します。
  • targetFrame == nil: 新規ウィンドウターゲット(target="_blank"を持つアンカーなど)をリクエストしていることを示します。

iframeハイジャック(埋め込みiframeが外部アプリの起動やバックグラウンドでのネイティブビュー遷移を試みる行為)を防ぐため、デリゲートは sourceFrame.isMainFrame を評価する必要があります。開始フレームがiframeである場合(sourceFrame.isMainFrame == false)、標準的なHTTP/HTTPSサブフレームナビゲーションは許可 (.allow) しつつ、Web以外のカスタムスキームやネイティブルーティングへのハンドオフはブロック (.cancel) してください。

悪意のあるサブフレームプロトコル呼び出しとバックグラウンドでのスキームフラッディングの防止

開始フレームチェックを強制することで、サブフレームが予期せぬ外部スキーム呼び出しをトリガーするのを防ぎます:

if !navigationAction.sourceFrame.isMainFrame {
    let scheme = url.scheme?.lowercased() ?? ""
    if scheme == "http" || scheme == "https" {
        decisionHandler(.allow) // 標準的なHTTP(S)サブフレームナビゲーションを許可
    } else {
        decisionHandler(.cancel) // サブフレームからのWeb以外のスキームを抑制
    }
    return
}

クライアントルーティングにおける厳格なパスおよびクエリパラメーターの許可リスト適用

内部の関連ドメインURLと外部のカスタムスキームの両方が、実行前に厳格なバリデーターモデルを通過する必要があります:

  • パスプレフィックス許可リスト: 承認されたルートプレフィックス(例:/open/, /product/, /promo/, /checkout/)を強制し、任意のパスや不正な形式のパスを拒否します。
  • クエリキーフィルタリング: パラメーター汚染を防ぐため、予期しないクエリキーを破棄し、重複するパラメーターキーを拒否します。
  • データ型および長さの制約: パラメーター値を英数字セットに制限し、最大長(≤64\le 64 文字)の境界を強制します。

SwiftでのWKNavigationDelegateの本番実装

SwiftにおけるCustomWebViewControllerとデリゲートアーキテクチャの構築

本番環境向けの WKWebView コントローラーは、Web設定、ナビゲーションポリシー評価、内部ルーティング、外部への委任を調整します。デリゲートのコールバックをクリーンでテスト可能かつ安全に保つために、検証ルールを専用のバリデータークラス(AppRouteValidatorおよびCustomSchemeValidator)にカプセル化します。

AppRouteValidator および CustomSchemeValidator モデルの実装

バリデーターモデルは厳格な「フェイルクローズ(デフォルトで拒否)」セキュリティを強制します:

  • AppRouteValidator: 内部の関連ドメインを検証し、パスプレフィックスを確認して、クエリパラメーターを構造化された ValidatedAppRoute オブジェクトへサニタイズします。
  • CustomSchemeValidator: 承認されたカスタムスキーム (myapp) を検証し、許可されたホスト (open, product, event) を確認して、クエリ値をサニタイズします。

OpoInstallは、アトリビューションやディファードパラメーター復旧のために、アプリ所有のルーティングレイヤーと併用可能です。統合の詳細については、SDK統合ドキュメントを参照してください。

以下の技術実装は、Swiftでセキュアな WKNavigationDelegate を構成する方法を示しています:

// iOS: 厳格なWKNavigationDelegateルーティングとフレームセキュリティを備えたCustomWebViewController
// 統合の参考例。メソッドのシグネチャとドメインマッピングをデプロイ済みのアーキテクチャに合わせて確認してください。
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. 安全なナビゲーションポリシーインターセプトを備えたWKWebViewをホストするUIViewController
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: iframeハイジャックを防ぐため、開始フレーム(sourceFrame)の境界を強制
        if !navigationAction.sourceFrame.isMainFrame {
            let scheme = url.scheme?.lowercased() ?? ""
            if scheme == "http" || scheme == "https" {
                decisionHandler(.allow) // 標準的なHTTP(S)サブフレームナビゲーションを許可
            } else {
                decisionHandler(.cancel) // サブフレーム/iframeからの非Webスキームを抑制
            }
            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) // Webビュー内での読み込みをキャンセルし、内部でルーティング
            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) // 未処理のスキームエラーを防ぐため、Webビュー内での読み込みをキャンセル
            return
        }

        // セキュリティチェック4: 外部の目的地および新規ウィンドウ (target="_blank") リクエストの処理
        if scheme == "http" || scheme == "https" {
            let host = url.host?.lowercased() ?? ""
            
            // 検証済みのパートナーユニバーサルリンクを、明示的なリンクポリシーで外部アプリへ委任
            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ビュー内で外部パートナーの目的地を読み込む
                        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
            }

            // 標準的なWebコンテンツはWKWebView内で読み込みを継続
            decisionHandler(.allow)
            return
        }

        decisionHandler(.allow)
    }
}

// アプリケーション固有の内部ルータープレースホルダー(OpoInstall SDK APIではありません)
class AppInternalRouter {
    static let shared = AppInternalRouter()

    func navigate(to route: ValidatedAppRoute) {
        // パスとクエリパラメーターに基づいて内部UIビューコントローラーの遷移を実行
    }
}

スレッドセーフな実行:メインアクターでのUI遷移実行の確保

現在のSwift同時実行モデルにおいて、WKNavigationDelegateのコールバックはメインアクターで隔離されています。アプリケーションのルーティングとビューコントローラーの遷移はメインアクター上で実行され、ネイティブのナビゲーションワークフロー全体でスレッドセーフティが維持されます。

WKWebViewディープリンクナビゲーションエラーと診断マトリックス

包括的なiOS WKWebViewディープリンクトラブルシューティングガイド

以下のマトリックスでは、iOS WKWebView 内でディープリンクやカスタムスキームを管理する際に遭遇する一般的なエラー、主な根本原因、および推奨されるエンジニアリング対応策をまとめています:

エラーの兆候 / 症状 主な根本原因 対象iOSバージョン 診断チェックポイント 推奨される修正策
ユニバーサルリンクがWebで開く アプリ所有ドメインのインターセプト漏れ iOS 9以降 decidePolicyForNavigationActionが未処理 ホストドメインをインターセプトし、パスを解析し、内部ルーティングして.cancelを返す
自社ドメインリンクのルーティング失敗 自社ドメインに対してUIApplication.openを呼び出し iOS 9以降 自社ホストに対してUIApplication.shared.openが実行されている 外部へのオープンを避け、直接内部ルーターへルーティングする
カスタムスキームのサイレント失敗 非HTTPプロトコルがWebKitで未認識 iOS 9以降 スキームがUIApplicationへ委任されていない デリゲート内でスキームをインターセプトし、許可リストを検証してUIApplicationで開く
iframeプロトコルハイジャック サブフレームによる外部カスタムスキームのトリガー iOS 9以降 sourceFrame.isMainFrameのチェック漏れ if !sourceFrame.isMainFrameで保護し、非Webスキームを抑制する
UIハンドオフ警告や遷移の問題 メインスレッド外でのUI遷移実行 iOS 9以降 メインアクターへのディスパッチ不足 内部ルーターおよびビューコントローラー遷移がメインアクターで実行されることを確認する

よくある質問 (FAQ)

開発者はどのようにしてWKWebView内でユニバーサルリンクをインターセプトできますか?
開発者は `WKNavigationDelegate` を実装し、`decidePolicyForNavigationAction` 内で受信したURLを検査します。URLがアプリ固有の宛先と一致する場合、デリゲートはWebビュー内のナビゲーションを `.cancel` でキャンセルし、検証済みのパラメーターをアプリの内部ルーターへ直接渡します。
WKWebViewから UIApplication.shared.open を使って自分のアプリを起動できますか?
Appleのドキュメントによると、ホストアプリの関連ドメインを指すユニバーサルリンクに対して `UIApplication.shared.open()` を呼び出しても、ユニバーサルリンクとしてアプリ内で開くことはできません。自社ドメインのリンクに対しては、Webビューのナビゲーションをキャンセルし、アプリの内部ナビゲーションルーターを直接呼び出す必要があります。
WKWebView内の埋め込みiframeが外部アプリの起動をトリガーするのを防ぐにはどうすればよいですか?
iframeハイジャックを防ぐため、`decidePolicyForNavigationAction` 内で `navigationAction.sourceFrame.isMainFrame` を確認してください。`isMainFrame` が `false` の場合は標準的なHTTP(S)サブフレームナビゲーションを `.allow` で許可しつつ、サードパーティのiframeが勝手に外部アプリを起動させるのを防ぐために、非Webのカスタムスキームは `.cancel` でキャンセルします。

まとめと判断フレームワーク

iOSの WKWebView 内でユニバーサルリンクやカスタムスキームを扱うには、WebKitのWebレンダリングコンテナとネイティブのUIKitナビゲーションライフサイクルの境界を橋渡しする必要があります。デフォルトのナビゲーションポリシーに依存していると、アプリ固有のルーティングロジックが必要な場合にスムーズなハンドオフを妨げる可能性があります。

フレーム境界を検証し、外部へのハンドオフには保守的なリンクアクティベーションポリシーを適用し、厳格なルートバリデーターを介して内部関連ドメインを解析し、外部ターゲットを安全に UIApplication.shared.open へ委任する堅牢な WKNavigationDelegate を実装することで、エンジニアリングチームはiframeプロトコルハイジャックを防ぎつつ、制御されたナビゲーションを維持できます。

ネイティブiOSのディープリンクおよびパラメータールーティングのアーキテクチャについては、SDK統合ドキュメントを参照してください。

関連資料

Share this article