كيف يمكنك استكشاف أخطاء إعادة توجيه WebView على أنظمة Android وiOS وإصلاحها؟ حدد ما إذا كان الفشل يتضمن تنقل HTTPS قياسياً، أو مخطط عناوين URL مخصصاً، أو رابط intent:// على نظام Android، أو طلب نافذة جديدة، ثم افحص التنقل عبر Chrome DevTools أو Safari Web Inspector وتتبع الوكيل الأصلي المقابل (مثل shouldOverrideUrlLoading، أو onCreateWindow، أو decidePolicyForNavigationAction، أو createWebViewWith). تحقق من دقة التطبيق المستهدف، وقوائم السماح لعناوين URI، وسياسات الإطارات وتفاعل المستخدم، والتوجيه الاحتياطي لعزل أخطاء مستوى حاوية التطبيق عن اخفاقات إرسال نظام التشغيل.
يحدث خطأ إعادة توجيه WebView عندما يفشل مكون Chromium WebView المضمن في أندرويد أو WKWebView التابع لـ WebKit في إزالة توجيه طلب التنقل إلى الوجهة المقصودة. تشمل الأسباب النموذجية مخططات عناوين URL المخصصة غير المدعومة، والطلبات غير المُعَالجَة من نوع
target="_blank"، وتصريحات رؤية الحزم المفقودة، وعمليات إعادة التوجيه الاحتياطية المرفوضة أو التي تقع في حلقة تكرارية.
لماذا تُسقِط حاويات Android WebView وiOS WKWebView المضمنة عمليات إعادة التوجيه؟

عند تصحيح أخطاء إخفاقات إعادة التوجيه، يجب على الفرق الهندسية الفصل بين سلوك محرك WebView (كيفية تحليل Chromium أو WebKit لعناوين URL، وأهداف الإطارات، وأحداث النوافذ المنبثقة) وسياسة التطبيق المضيف (كيفية تقييم المكونات المزودة من التطبيق مثل WebViewClient، أو WebChromeClient، أو WKNavigationDelegate، أو WKUIDelegate لأنواع تفاعل المستخدم، وقوائم السماح، وعمليات التسليم للتطبيقات الخارجية). تتضمن المتصفحات المستقلة موجهات عناوين URI مدمجة ومعالجات لتسليم الروابط، في حين أن مكون android.webkit.WebView ومكون WKWebView الخاص بشركة Apple هما عبارة عن مكونات عرض مدمجة تتوقع استجابات شبكة قياسية من نوع http:// أو https:// بشكل افتراضي.
عندما تُشغّل صفحة ويب مخططاً مخصصاً (مثل myapp://product/42) أو رابط intent:// على أندرويد دون تجاوز نشط للوكيل، فإن السلوك الافتراضي للحاوية يتباين عبر المنصات:
- Android Chromium WebView: وفقاً لمواصفات
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 هي ميزة دعم متصفح Safari مصممة لتصفح Safari المستقل بدلاً من واجهة برمجة تطبيقات التنقل المدمجة في WKWebView، ويجب تقييمها بشكل منفصل عن عمليات إعادة توجيه مخططات عناوين URL المخصصة داخل التطبيق.
لمحة سريعة
- الفصل بين سلوك المحرك وسياسة المضيف: حدد عما إذا كان التنقل قد فشل داخل محرك الويب (Chromium/WebKit)، أو داخل تجاوزات الوكيل الأصلي، أو عند حدود حل حزم نظام التشغيل.
- فحص عمليات إعادة التوجيه الحية قبل البرمجة: استخدم أدوات Chrome DevTools (بالأمر
chrome://inspect) وSafari Web Inspector (بالخاصيةisInspectable = true) لالتقاط سلاسل إعادة التوجيه من الفئة 3xx، وحالاتtargetFrame، وعلامات الإيماءات. - فرض التحقق من صحة عناوين URI والنوايا بما يتناسب مع المنصة: على نظام Android، قم بربط المخططات المخصصة وأهداف
intent://بنسبة 1 إلى 1 بالحزم المتحقق منها عبرIntentSanitizerدون استخدام علامات المهام المقدمة من صفحة الويب؛ وعلى نظام iOS، تحقق من بنى عناوين URI المخصصة بالكامل (مع الاعتماد على الروابط الشاملة Universal Links عند الحاجة إلى مطابقة الهوية بين التطبيق والنطاق)، وارفض مفاتيح الاستعلام المكررة على كلا المنصتين. - تطبيق الأمان متعدد الطبقات للنوافذ المنبثقة وحالات التنافس الزمنية: احصر حالة جلسة النوافذ المنبثقة في أندرويد حصرياً على خيط واجهة المستخدم (UI thread) مع فهم حدود الاستدعاء عبر
shouldInterceptRequestوshouldOverrideUrlLoading، وافصل فحوصات السياسة البحتة عن التأثيرات الجانبية للإرسال الخارجي في نظام iOSWKWebViewباستخدام إزالة التكرار على مستوى الإجراء ورموز إنشاء التنقل.
الأسباب الشائعة وخطوات التحقق من أخطاء إعادة توجيه WebView
ربط أخطاء العميل المرصودة بآليات فشل الحاوية الأساسية
استخدم مصفوفة التشخيص أدناه لربط أعراض WebView المرصودة بالأسباب الجذرية الشائعة للمنصة، وخطوات التحقق، والإصلاحات المستهدفة:
| العرض أو الخطأ المرصود | المنصة المستهدفة | السبب الجذري الشائع | خطوة التحقق التشخيصي | الإصلاح المستهدف |
|---|---|---|---|---|
يعرض WebView الخطأ net::ERR_UNKNOWN_URL_SCHEME |
Android WebView | يرجع المكون المخصص WebViewClient القيمة false أو يفتقر إلى قائمة السماح للمخططات |
فحص request.url داخل دالة shouldOverrideUrlLoading |
اعتراض عناوين URI الموجودة في قائمة السماح وإرسال نية Intent.ACTION_VIEW مرتبطة بالحزمة بنسبة 1 إلى 1 |
| توقف صمت عند النقر على رابط مخطط مخصص | iOS WKWebView | يُبطل WebKit عناوين URI التي لا تستخدم HTTP عندما يُرجع الوكيل WKNavigationDelegate القيمة .allow |
تسجيل navigationAction.request.url في decidePolicyForNavigationAction |
توجيه المخططات المتحقق منها عبر UIApplication.shared.open وتمرير القيمة .cancel |
يستبدل الوسيط target="_blank" الصفحة الحالية في WebView |
Android WebView | تتعامل الدالة setSupportMultipleWindows(false) مع النوافذ الجديدة كعمليات تحميل على المستوى الأعلى |
التحقق من webView.settings.supportMultipleWindows() |
تفعيل الدالة setSupportMultipleWindows(true) فقط في حال الحاجة إلى حاويات نوافذ منبثقة منفصلة |
لا يفعل الوسيط target="_blank" شيئاً أو يُسقط عمليات إعادة توجيه المصادقة 302 |
Android WebView | الدالة onCreateWindow مفقودة، أو أن العميل الفرعي يحظر قفزات isRedirect التي تفتقر إلى إيماءة hasGesture() |
التحقق من سجلات onCreateWindow وrequest.isRedirect وshouldInterceptRequest |
إرفاق مكون WebView منبثق مستضاف في العرض مع حالة جلسة مرتبطة بخيط واجهة المستخدم وقفزات isRedirect مقيدة |
الرابط الذي يحتوي على target="_blank" أو window.open() لا يستجيب |
iOS WKWebView | تنقل النافذة الجديدة يضبط targetFrame == nil ويتطلب استخدام WKUIDelegate |
التحقق من الشرط navigationAction.targetFrame == nil |
اكتشاف targetFrame == nil في decidePolicyForNavigationAction والمعالجة عبر WKUIDelegate |
| التطبيق المستهدف مثبت، ومع ذلك تفتح الصفحة الاحتياطية | Android 11+ (بحيث يكون targetSdk >= 30) |
تتسبب تصريحات الحزم المفقودة <queries> في إرجاع resolveActivity() أو queryIntentActivities() لنتائج غير مكتملة للحزم غير المرئية |
إضافة تسجيل على مستوى التطبيق حول resolveActivity() وفحص المخرجات عبر adb logcat |
التصريح عن نيات <queries> في حال الفحص المسبق، أو استدعاء startActivity مباشرة مع التعامل مع الاستثناء ActivityNotFoundException |
| فشل إعادة توجيه مؤقت JavaScript في فتح تطبيق خارجي | iOS / Android | إعادة التوجيه النصية التلقائية تفتقر إلى إشارة تفاعل المستخدم | التحقق من request.hasGesture() (في أندرويد) أو navigationType (في آي أو إس) |
ربط عمليات إعادة التوجيه بنقرات المستخدم المباشرة وتحديد سياسة إيماءات مضيفة صريحة |
يتم تحميل الرابط الشامل Universal Link داخل WKWebView بدلاً من التطبيق المستهدف |
iOS WKWebView | سياق التصفح، أو علاقة النطاق، أو تنقل JavaScript يبقي التحميل داخل WebKit | التحقق من navigationType والمضيف في decidePolicyForNavigationAction |
استدعاء UIApplication.shared.open مع تعيين الخيار .universalLinksOnly: true للمضيفين الخارجيين المسموح بهم |
قائمة الفحص السريع لإعادة توجيه WebView خلال خمس دقائق
- الخطوة 1: التحقق من مخطط البروتوكول في أدوات التطوير DevTools: تحقق مما إذا كانت الصفحة قد أصدرت عنواناً من نوع
https://، أو مخططاً مخصصاً، أو رابطintent://، وتأكد من عدم حظره بواسطة سياسة أمان المحتوى (CSP). - الخطوة 2: فحص تسلسل الإطارات: تحقق مما إذا كان المشغل نشئ داخل إطار فرعي تابع لجهة خارجية
<iframe>(أي!isMainFrame). قد تقوم التطبيقات المضيفة بحظر عمليات تشغيل التطبيقات الخارجية البادئة من إطارات طرف ثالث عمداً. - الخطوة 3: التمييز بين عمليات إعادة التوجيه والمؤقتات: تحقق مما إذا كان التنقل بدون إيماءة عبارة عن إعادة توجيه خادم HTTP 3xx مصرح بها (مثل
request.isRedirectعلى أندرويد) مقابل مؤقت JavaScript غير مطلوب. - الخطوة 4: التحقق من مشغلات النوافذ الجديدة: تأكد مما إذا كان
target="_blank"أوwindow.open()قد أنشأ طلب نافذة جديدة (أيtargetFrame == nilفي آي أو إس أوonCreateWindowفي أندرويد). - الخطوة 5: التحقق من حل حزم نظام التشغيل: بالنسبة للتطبيقات التي تستهدف الإصدار API 30+ على نظام Android 11+، تأكد مما إذا كانت استدعاءات فحص ما قبل التشغيل
resolveActivity()تفشل بسبب فقدان تصريحات<queries>.
يوضح سير العمل التشخيصي التالي مسار الفرز المتسلسل لعزل إخفاقات إعادة توجيه الحاوية:
[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)
كيفية فحص أحداث تنقل WebView باستخدام أدوات التصحيح عن بعد
تفعيل التصحيح عن بعد عبر Chrome DevTools وسجلات أندرويد ADB Logcat
قبل تعديل الوكلاء الأصليين، تحقق مما إذا كانت صفحة الويب المُحمَّلة تُصدر عملية إعادة التوجيه المتوقعة. وفقاً لـ دليل التصحيح عن بعد لـ Chrome DevTools في أندرويد، قم بتمكين تصحيح أخطاء WebView عن بعد صراحة في إصدارات التطوير عن طريق فحص ApplicationInfo.FLAG_DEBUGGABLE واستدعاء WebView.setWebContentsDebuggingEnabled(true). لا تقم أبداً بشحن التطبيق مع تفعيل التصحيح في الإصدارات النهائية الموجهة للإنتاج:
// Android - Enable WebView debugging exclusively in debuggable builds
if (applicationInfo.flags and ApplicationInfo.FLAG_DEBUGGABLE != 0) {
WebView.setWebContentsDebuggingEnabled(true)
}
قم بتوصيل الجهاز عبر منفذ USB، وافتح الرابط chrome://inspect/#devices في متصفح سطح المكتب Chrome، وراقب علامة التبويب Network مع تفعيل خيار Preserve log. وفي نفس الوقت، قم بتصفية سجلات وقت التشغيل الأصلية عبر الأمر adb logcat لالتقاط الأخطاء مثل ActivityNotFoundException أو SecurityException أو سجلات الغلاف المخصص. لاحظ أن تحذيرات إيقاف الدعم لتوقيع الدالة القديم shouldOverrideUrlLoading(WebView, String) تظهر أثناء تجميع Android Studio / Gradle وليس في وقت تشغيل adb logcat:
# Terminal - Filter logcat for custom WebView tags and ActivityTaskManager intent resolution
adb logcat -s "WebViewDebug" "ActivityTaskManager" "PackageManager"
تكوين الخاصية isInspectable وإرفاق Safari Web Inspector ووحدة تحكم Xcode على نظام iOS
بدءاً من إصدار iOS 16.4 وmacOS 13.3، تطلب شركة Apple من التطبيقات التسجيل صراحةً عبر الخاصية WKWebView.isInspectable والتي تكون مضبوطة افتراضياً على القيمة false. قم بتمكين الخاصية webView.isInspectable = true داخل كتل المعالجة الشرطية #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
على جهاز iOS الفعلي، انتقل إلى المسار الإعدادات > التطبيقات > Safari > متقدم (أو في إصدارات iOS الأقدم، الإعدادات > Safari > متقدم) وقم بتفعيل خيار مفتش الويب (Web Inspector). اتصل عبر USB، وافتح قائمة Develop في متصفح Safari لسطح المكتب، وراقب وحدة تحكم Xcode في نفس الوقت لمتابعة مخرجات التنفيذ الخاصة بـ decidePolicyForNavigationAction وcreateWebViewWith وUIApplication.shared.open.

معالجة عمليات إسقاط النوافذ الجديدة الصامتة وفقدان إيماءات المستخدم في نظام iOS WKWebView
الفصل بين تقييم السياسة والتأثيرات الجانبية عبر WKNavigationDelegate وWKUIDelegate
عندما يحدد رابط ويب الوسيط target="_blank" أو الدالة window.open()، فإن WebKit ينشئ طلب تنقل لنافذة جديدة تكون فيها الخاصية navigationAction.targetFrame مساوية للقيمة nil، ويتضمن ذلك التعامل مع كل من WKNavigationDelegate وWKUIDelegate. إذا لم يقم التطبيق المضيف بتنفيذ الدالة webView(_:createWebViewWithConfiguration:for:windowFeatures:)، فلن يتمكن WebKit من إنشاء مكون WebView ثانوي، وقد تبدو عمليات التنقل وكأنها تفشل في صمت.
لمنع عمليات إطلاق التطبيقات الخارجية المكررة أو تكرار زيادة رموز الإنشاء عند قيام كلا الوكيلين بفحص الطلب، افصل بين تقييم السياسة البحتة (evaluateNavigationPolicy) والتأثيرات الجانبية للتنفيذ، وقم بإزالة التكرار بناءً على مثيل WKNavigationAction المحدد (عبر ObjectIdentifier(navigationAction)) بدلاً من الاعتماد البحت على عتبة زمنية خشنة قد تؤدي إلى كبح النقرات السريعة المتكررة المقصودة من قبل المستخدم. قم بتقييم الشرط navigationAction.targetFrame == nil مباشرة داخل decidePolicyForNavigationAction: إذا أرجع التقييم خطة تسليم خارجية، قم بتنفيذها مرة واحدة (مع تسجيل معرف WKNavigationAction) ومرر القيمة .cancel؛ وإذا أرجع القيمة .allowInWebView لعنوان URL منبثق مدرج في قائمة السماح، فمرر القيمة .allow لكي تقوم الدالة createWebViewWith بتحميل النافذة المنبثقة بأمان. تحقق دائماً من الترتيب الدقيق لاستدعاءات الوكيل على إصدارات iOS المستهدفة.
سياق الرابط الشامل Universal Link، وسلامة التنافس غير المتزامن، وهيوية المخطط المخصص
يعتمد تسليم الرابط الشامل Universal Link على سياق تصفح المصدر، وعلاقة النطاق، وتكوين النطاقات المرتبطة Associated Domains (والتي يتم التحقق منها عبر ملف apple-app-site-association الخاص بالخادم المستهدف). توثق مذكرة Apple التقنية TN3155: تصحيح أخطاء الروابط الشاملة كيف أن التنقل ضمن نفس النطاق في متصفح Safari يفضل البقاء داخل المتصفح، بينما تتسبب النطاقات الفرعية المختلفة في تغيير الأهلية. قم دائماً باختبار سلوك النطاقات المرتبطة على إصدارات iOS المستهدفة داخل المكون WKWebView.
عند استدعاء الدالة UIApplication.shared.open(url, options: [.universalLinksOnly: true])، احرص على الحماية ضد حالات التنافس في التنقل غير المتزامن: إذا بدأ المستخدم أي محاولة تنقل لاحقة للإطار الرئيسي أثناء معالجة النظام لتسليم الرابط الشامل، فإن معالج اكتمال غير محمي يُرجع القيمة false يمكنه الكتابة فوق حالة التنقل الأحدث للمستخدم. قم بزيادة رمز توليد التنقل النشط الرتيب activeNavigationGeneration عند كل تقييم جديد لتنقل الإطار الرئيسي (بما في ذلك المحاولات المحظورة أو المعاد توجيهها) بحيث يتم إبطال أي رجوع غير متزامن سابق معلق على الفور، وتحقق من تطابق self.activeNavigationGeneration == requestGeneration إلى جانب الشرط self.isViewLoaded && self.view.window != nil قبل إعادة تحميل عناوين URL الاحتياطية.
التزم بحدود أمان صارمة:
- تصنيف نوع التنقل
WKNavigationType: وفقاً لوثائق Apple الخاصة بالنوعWKNavigationType، يمثل النوعformSubmittedطلباً لإرسال نموذج بدلاً من النقر على رابط، ويمكن لنصوص الصفحة البرمجية إرسال النماذج برمجياً. قم بتقييد عمليات تسليم التطبيقات الخارجية لتقتصر على أحداث.linkActivatedالمصنفة بواسطة WebKit مجتمعة مع الشرطsourceFrame.isMainFrameوقوائم السماح الكاملة لعناوين URI، بدلاً من التعامل مع.linkActivatedكرمز إيماءة مشفر معزول. - فرادة المخطط المخصص وتلوث المعلمات: وفقاً لدليل Apple حول تحديد مخطط عنوان URL مخصص لتطبيقك، يمكن لعدة تطبيقات المطالبة بنفس المخطط المخصص. تقوم الدالة
isAllowedCustomURL(_:)بالتحقق من بنية عنوان URI (المخطط، والمضيف، والمنفذ الافتراضيnil، ونمط المسار، وعدم وجود معلومات المستخدم أو الجزء، ورفض مفاتيح الاستعلام المكررة)، وليس التحقق من هوية معرف الحزمة المستهدفة (Bundle ID). استخدم الروابط الشاملة التي تم التحقق من نطاقها كلما كانت هناك حاجة إلى ربط هويّة التطبيق.
إخلاء مسؤولية بنية المرجع: التنفيذ التالي هو بنية مرجعية دفاعية. قم بالتحقق من توفر واجهة برمجة التطبيقات، وترتيب الوكلاء، وسلوك دورة الحياة مقابل إصدارات AndroidX وiOS الدقيقة التي يستخدمها تطبيقك.
// 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
}
}
إصلاح الأخطاء ERR_UNKNOWN_URL_SCHEME وأخطاء رؤية الحزم في نظام Android WebView
دالة الاستدعاء المهملة، وhasGesture()، وحدود الطلب POST
أوقف نظام Android العمل بالدالة shouldOverrideUrlLoading(WebView, String) في الإصدار API level 24 لصالح الدالة shouldOverrideUrlLoading(WebView, WebResourceRequest). يوفر الكائن WebResourceRequest خصائص مثل isForMainFrame، وisRedirect، وhasGesture(). لاحظ قيدين رسميين للنظام: لا يتم استدعاء shouldOverrideUrlLoading لعمليات استدعاء webView.loadUrl() البادئة من التطبيق أو عمليات التنقل التي تستخدم HTTP POST، وقد تُرجع الدالة hasGesture() القيمة false لعمليات إعادة توجيه JavaScript غير المتزامن الشرعية أو قفزات 302 من جانب الخادم.
معالجة النوافذ المنبثقة متعددة الطبقات وعزل الخيوط في دالة WebChromeClient.onCreateWindow
يعتمد سلوك النوافذ المنبثقة في أندرويد على الدالة WebSettings.setSupportMultipleWindows. إذا كان تطبيقك لا يتطلب نوافذ منبثقة تفاعلية، فإن إبقاء الخيار setSupportMultipleWindows(false) (أو إرجاع القيمة false من onCreateWindow) يمنع الإطارات الفرعية للأطراف الثالثة من فتح حاويات ثانوية، أو يسمح بفتح الوجهات التي تم التحقق منها عبر نقطة دخول صريحة يتحكم بها المضيف.
عند تفعيل الخاصية setSupportMultipleWindows(true)، فإن الدالة WebChromeClient.onCreateWindow لا توفر عنوان URL الوجهة في توقيع استدعائها، ولا يوجد استدعاء منفرد يغطي كل مسار تنقل. يعد فهم نموذج الخيوط الدقيق وحدود الاستدعاء أمراً أساسياً لنهج مرجعي متعدد الطبقات:
- الدالة
shouldOverrideUrlLoading(خيط واجهة المستخدم — مسؤولة عن التنقل وحالة الجلسة): تعمل حصرياً على خيط واجهة المستخدم (UI thread) وتتحكم في جميع حالات جلسة النوافذ المنبثقة القابلة للتغيير (مثلisInitialTransportLoad، وisAuthorizedPopupSession، وpopupRedirectHops، وpopupChainStartMs). فقط عندما يتطابق التحميل الأولي المتحقق منه أو إيماءة المستخدم المباشرة مع المعيارpolicy.isAllowedPopupUri، تقوم الدالةshouldOverrideUrlLoadingبتفويض الجلسة لعمليات إعادة توجيه HTTP 302 اللاحقة المقيدة (request.isRedirect)، مما يضمن ارتباط سلاسل إعادة التوجيه بجلسة مصرح بها بدلاً من الوثوق بعمليات إعادة التوجيه العشوائية. - الدالة
shouldInterceptRequest(خيط إدخال/إخراج WebView في الخلفية — حارس عديم الحالة وقراءة فقط): تعمل على خيط WebView غير تابع لواجهة المستخدم. نظراً لأنه يجب ألا تقوم أبداً بتغيير حالة جلسة خيط واجهة المستخدم، فهي تعمل حصرياً كفحص سياسة عديم الحالة وقراءة فقط على الكائنsafeClient.policy(حظر طلبات HTTP/HTTPS الخاصة بالإطار الرئيسي التي تفشل في اجتيازisAllowedPopupUriوإرسال الأمرdisposeActivePopup()إلى خيط واجهة المستخدم). لاحظ أنه وفقاً لوثائق أندرويد، يتم استدعاء الدالةshouldInterceptRequestفقط لعنوان URL للمورد الأولي، وليس لعناوين URL الخاصة بإعادة توجيه HTTP 302 اللاحقة؛ حيث يجب تقييم عناوين URL لإعادة التوجيه اللاحقة بواسطةshouldOverrideUrlLoading. - الدالة
onPageStarted(خيط واجهة المستخدم — فحص احتياطي لبدء التنقل): يتم تنفيذها عند بدء تحميل الإطار الرئيسي (وليست مرشحاً لما قبل التنقل). وهي تقوم بتحديث لافتة المصدر المرئية لضمان شفافية المستخدم وتوفر فحصاً احتياطياً لبدء التنقل يستدعيstopLoading()وdisposeActivePopup()إذا بدأ تحميل وجهة غير معتمدة.
قم دائماً باختبار عناوين URL الأولية الضارة، وسلسلة إعادة توجيه HTTP 302 عبر نطاقات مختلفة، وعمليات إعادة توجيه 302 المتتالية، والوسيط target="_blank"، والدالة window.open()، ومشغلات إطارات الأطراف الثالثة (iframe) على تصميمات WebView الفعلية المستهدفة.
رؤية الحزم في نظام Android 11+ وإرشادات الدالة المهملة canOpenURL
بموجب قواعد رؤية الحزم في نظام أندرويد، تتلقى التطبيقات التي تعمل على نظام Android 11 (المستوى API 30) أو الإصدارات الأحدث والتي تستهدف المستوى API 30 أو أعلى (بحيث يكون targetSdk >= 30) نتائج فارغة أو مساوية لـ null من intent.resolveActivity() أو queryIntentActivities() ما لم يتم التصريح عن التطبيقات المستهدفة ضمن الوسم <queries> في ملف AndroidManifest.xml. يوصي أندرويد باستدعاء الدالة startActivity(intent) مباشرة داخل كتلة try/catch للتعامل مع الاستثناءين ActivityNotFoundException وSecurityException بدلاً من توسيع نطاق وسم <queries>.
على نظام iOS، قامت شركة Apple بإلغاء دعم الدالة UIApplication.canOpenURL(_:) وتوصي بمحاولة استدعاء الدالة UIApplication.shared.open(_:options:completionHandler:) مباشره ومعالجة أي فشل في معالج الاكتمال (أو الانتقال إلى الروابط الشاملة لإزالة الحاجة إلى التحقق المسبق من المخطط). إن مفتاح LSApplicationQueriesSchemes الموجود في ملف Info.plist مطلوب فقط إذا استمر الكود القديم في استدعاء canOpenURL(_:)، بينما لا يتطلب الاستدعاء open(_:options:completionHandler:) التصريح عن المخططات في ملف Info.plist. يتحكم كل من الوسم <queries> وLSApplicationQueriesSchemes في رؤية الاستعلامات - وهما ليسَا قائمتين لأمان السماح للتحقق من عناوين URL غير الموثوقة الخاصة بالويب.
<!-- 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>
كيفية تحليل عناوين URI الخاصة بنوايا كروم (Chrome Intent URIs) بأمان ومنع حلقات إعادة التوجيه
تأمين دالة Intent.parseUri ضد ثغرات إعادة توجيه النوايا
تقوم عناوين URI الخاصة بنوايا أندرويد intent:// بترميز مخطط مستهدف، وحزمة، وعنوان URL احتياطي (S.browser_fallback_url). إن تحليل عناوين URL للويب غير الموثوقة عبر الدالة Intent.parseUri(rawUri, Intent.URI_INTENT_SCHEME) يُدخل مخاطر إعادة توجيه النوايا (Intent Redirection) الموضحة بالتفصيل في دليل أمان إعادة توجيه النوايا في أندرويد ودليل اختبار أمان تطبيقات الجوال OWASP. حتى مع إضافة أندرويد 16 (API 36) لتحصين افتراضي على مستوى النظام، يجب على التطبيقات فرض تحقق صارم قبل إرسال النوايا.

لتنفيذ تحقق بمعامل إغلاق عند الفشل (Fail-Closed) باستخدام أداة AndroidX IntentSanitizer (المتوفرة في الحزمة androidx.core:core:1.9.0+ أو androidx.core:core-ktx:1.9.0+ والتي تتضمن الحزمة androidx.core:core) دون إثارة تعارضات استبعاد متبادل للمنشئ بين allowAnyComponent() وطرق قوائم السماح للحزمة/المكون:
- فحوصات ما قبل التعقيم: قم فوراً برفض النوايا التي تحمل حقول
componentأوselectorغير فارغة (أيparsedIntent.component != null || parsedIntent.selector != null). استخرج وقم بإزالةbrowser_fallback_urlقبل عملية التعقيم، وتأكد من أنparsedIntent.data?.schemeيطابق بنسبة 1 إلى 1 الحزمةparsedIntent.packageعبرcustomSchemeTargetPackages(مما يضمن أن المخططmyapp://يحل حصرياً إلى الحزمةcom.example.targetوليس إلى أي حزمة شريكة أخرى). - تنفيذ المعقم: قم مؤقتاً بتفريغ القيمة
parsedIntent.package = nullعلى النسخة غير الموثوقة، ثم قم بتنفيذ الأمرIntentSanitizer.Builder().allowAnyComponent().allowAction(Intent.ACTION_VIEW).allowCategory(Intent.CATEGORY_BROWSABLE).allowData { ... }.build().sanitizeByThrowing(parsedIntent)(مع تصفير علامات المهام المقدمة من صفحة الويب)، وأعد تعيين الحزمة المتحقق منهاexpectedPackageوالفئةCATEGORY_BROWSABLEعلى النية المعقمة المملوكة للمضيف قبل إجراء تأكيدات ما بعد التعقيم. - علامات التشغيل المدركة للسياق: قم بحقن العلامة
Intent.FLAG_ACTIVITY_NEW_TASKداخل الموصل الأصلي (launchWithContextSafety) فقط عندما يكون الشرطview.context !is Activityمتحققاً. وللتحقق من ارتباط النطاق بالتطبيق، يُفضل استخدام روابط تطبيقات أندرويد HTTPS المتحقق منها (assetlinks.json).
منع حلقات الرجوع اللانهائية باستخدام حالة السلسلة الرتيبة
عندما تُطلق الدالة startActivity الاستثناء ActivityNotFoundException، تحقق من صحة browser_fallback_url باستخدام فحص مخصص isAllowedFallbackUri(uri) (ويشمل حصرياً: بروتوكول HTTPS، المنفذ الافتراضي، المضيف المُتحقق منه، بادئات مسار الرجوع الصريحة، عدم وجود مفاتيح استعلام مكررة، وعدم وجود أجزاء fragment). ارفض تمثيلات المنافذ الصريحة على المخططات المخصصة عن طريق التحقق من أن uri.port == -1 وأن الخاصية !uri.encodedAuthority.orEmpty().contains(":") متحققة معاً.
تتبع سلاسل الرجوع باستخدام الدالة SystemClock.elapsedRealtime() (لتجنب قفزات وقت النظام الحقيقي الفعلي System.currentTimeMillis())، واعزل السلسلة عبر الدالة fallbackLoopKey() (وليس النسخة القانونية الكاملة لمعيار IETF RFC 3986)، وأعد ضبط الحالة عبر غلاف مضيف صريحة loadNewNavigation(webView, url)، وقم بتوجيه حالات الرجوع المنبثقة إلى الحاوية الأساسية عبر onPopupFallbackHandoff بحيث لا تتم أبداً تحميل النطاقات غير المصرح بها داخل نافذة منبثقة.
إخلاء مسؤولية بنية المرجع: التنفيذ التالي هو بنية مرجعية دفاعية. قم بالتحقق من توفر واجهة برمجة التطبيقات، وترتيب الوكلاء، وسلوك دورة الحياة مقابل إصدارات AndroidX وiOS الدقيقة التي يستخدمها تطبيقك.
// 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()
}
}
الأسئلة الشائعة (FAQ)
لماذا يعرض Android WebView الخطأ net::ERR_UNKNOWN_URL_SCHEME حتى عندما يكون التطبيق المستهدف مثبتاً؟
لماذا تفشل الدالة shouldOverrideUrlLoading في العمل عندما يستدعي تطبيقي WebView loadUrl مباشرة؟
لماذا تفشل روابط الوسيط target blank التي تحتوي على مخططات مخصصة بصمت داخل WKWebView؟
الملخص وإطار اتخاذ القرار
تتطلب معالجة إخفاقات إعادة توجيه الروابط العميقة في WebView عزل سلوك محرك WebView عن سياسات تنقل التطبيق المضيف. من خلال إعادة إنتاج أحداث التنقل في Chrome DevTools أو Safari Web Inspector، وحصر حالة جلسة النوافذ المنبثقة في أندرويد حصرياً على خيط واجهة المستخدم مع ربط فحص الطلبات الأولية عديمة الحالة بفحوصات إعادة توجيه 302 المصرح بها للجلسة، وفرض قوائم السماح المغلقة لـ IntentSanitizer، وحماية عمليات الرجوع للروابط الشاملة Universal Links في نظام iOS ضد الكتابة فوق غير المتزامنة القديمة وإطلاقات الوكيل المكررة، يمكن للفرق الهندسية تقليل الرحلات المعطلة للمستخدمين والمساعدة في منع ثغرات إعادة التوجيه من جهة العميل.
بعد التحقق من الوكلاء الأصليين على مستوى الحاوية والمسارات الاحتياطية، يجب على الفرق الهندسية أيضاً التحقق من صفحات الهبوط لإسناد الإحالات من البداية إلى النهاية وسلاسل توجيه التشغيل بنقرة واحدة باستخدام منصات مثل OpoInstall للتأكد من الحفاظ على المعلمات عبر الانتقالات من المتصفح إلى التطبيق.
مسرد الكيانات
| المصطلح | التعريف | الكيان المرتبط | دور نية البحث |
|---|---|---|---|
| WebView | مكون واجهة مستخدم أصلي مدمج يُستخدَم لعرض صفحات الويب داخل تطبيق جوال. | WebViewClient / WKWebView |
معلوماتي / تقني |
| مخطط عنوان URL مخصص (Custom URL Scheme) | بادئة عنوان URI مسجلة للتطبيق (مثل myapp://) تتيح التنقل الخارجي إلى الشاشات الأصلية. |
Intent.ACTION_VIEW |
تقني / معلوماتي |
| WKNavigationDelegate | بروتوكول WebKit الذي يتيح للتطبيق المضيف قبول أو إلغاء أو إعادة توجيه إجراءات التنقل في WKWebView. |
decidePolicyForNavigationAction |
تقني |
| WKUIDelegate | بروتوكول WebKit المسؤول عن التعامل مع طلبات إنشاء نافذة جديدة في WKWebView. |
createWebViewWith |
تقني |
| WebResourceRequest | كائن أندرويد API 24+ الذي يغلف عنوان URL، والإطار، وطريقة HTTP، وإعادة التوجيه، وبيانات إيماءات البيانات الوصفية. | shouldOverrideUrlLoading |
تقني |
| WebChromeClient | واجهة استدعاء Android WebView للتعامل مع مربعات حوار JavaScript، والتقدم، والدالة onCreateWindow. |
WebViewTransport |
تقني |
| IntentSanitizer | أداة AndroidX Core المُستخدَمة لتصفية أو التحقق بدقة من حقول النوايا غير الموثوقة قبل الإرسال. | ال دفاع ضد إعادة توجيه النوايا | تقني / أمني |
| الروابط الشاملة (Universal Links) | معيار الروابط العميقة القائم على HTTPS من Apple والذي يربط نطاقات الويب المُتحقَّق منها بتطبيقات iOS المثبتة. | النطاقات المرتبطة (Associated Domains) | تقني / معلوماتي |
| رؤية الحزم (Package Visibility) | تصفية نظام التشغيل في Android 11+ (بحيث يكون targetSdk >= 30) والتي تقيد التطبيقات المثبتة التي يمكن للتطبيق المضيف الاستعلام عنها عبر PackageManager. |
وسم البيان <queries> |
تقني |
| عنوان URI للنية (Intent URI) | عنوان URI منظم لأندرويد (intent://) يقوم بترميز الحزمة المستهدفة والمخطط وعناوين URL الاحتياطية للمتصفح. |
Intent.URI_INTENT_SCHEME |
تقني |
الخط الأساسي للتوافق وحالة التحقق
-
أهداف التوافق المقصودة: أندرويد الإصدار
minSdk 24، وcompileSdk 34/35، وtargetSdk 34/35(أندرويد 14/15)، وسياق تحصين إعادة توجيه النوايا لأندرويد 16 (API 36)، وandroidx.core:core:1.9.0+(أداةIntentSanitizer)؛ ونظام iOS 15.0–18.0 (مع تقييد الخاصيةisInspectableعلى إصدارات iOS 16.4+)، وXcode 15/16، وSwift 5.9/6.0. -
حالة التحقق:
-
مراجعة واجهة برمجة التطبيقات الثابتة والمواصفات: اكتملت مقابل المواصفات الرسمية لمطوري أندرويد، وAndroidX Core، ومطوري Apple، ومعيار IETF RFC 3986، ودليل أمان تطبيقات الجوال OWASP MASTG.
-
التحقق من التجميع والجهاز الفعلي: لم يتم تنفيذه بعد في دورة المراجعة هذه. يجب على الفرق تجميع وتنفيذ الانحدار على الجهاز الفعلي لتغطية: عناوين URL الأولية الضارة للنوافذ المنبثقة، وسلاسل 302 عبر نطاقات مختلفة، وقفزات 302 المتتالية، وإنشاء نوافذ إطارات الأطراف الثالثة (iframe)، وروابط تطبيقات أندرويد (
assetlinks.json)، ونطاقات iOS المرتبطة (تخزين AASA مؤقتاً)، وإلغاء الارتباط الشامل غير المتزامن القديم، وسلاسل رجوعintent://، وإرسال الاستثناءActivityNotFoundExceptionقبل إطلاق التطبيق للإنتاج.
-
المراجع
Share this article



