كيفية استكشاف أخطاء إعادة توجيه WebView وإصلاحها على أنظمة Android وiOS؟

opoinstall
2026-11-19
5 min read

webview-safe-fallback-loop-prevention.webp

كيف يمكنك استكشاف أخطاء إعادة توجيه 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 متعددة الطبقات تكشف عن السياسة الأصلية وأعطال إرسال نظام التشغيل.

عند تصحيح أخطاء إخفاقات إعادة التوجيه، يجب على الفرق الهندسية الفصل بين سلوك محرك 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، وافصل فحوصات السياسة البحتة عن التأثيرات الجانبية للإرسال الخارجي في نظام iOS WKWebView باستخدام إزالة التكرار على مستوى الإجراء ورموز إنشاء التنقل.

الأسباب الشائعة وخطوات التحقق من أخطاء إعادة توجيه 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.

يستخدم Android WebView وiOS WKWebView معالجات تنقل ونوافذ منبثقة أصلية ومميزة.

معالجة عمليات إسقاط النوافذ الجديدة الصامتة وفقدان إيماءات المستخدم في نظام 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) لتحصين افتراضي على مستوى النظام، يجب على التطبيقات فرض تحقق صارم قبل إرسال النوايا.

التحقق من صحة عنوان URI متعدد الطبقات يحظر نواتج WebView غير الآمنة قبل إرسال التطبيق الخارجي.

لتنفيذ تحقق بمعامل إغلاق عند الفشل (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 حتى عندما يكون التطبيق المستهدف مثبتاً؟
يحدث هذا الخطأ عندما يحاول Chromium جلب مخطط عنوان URL مخصص لا يستند إلى HTTP عبر مكدس الشبكة الخاص به بدلاً من إعادة توجيهه إلى مدير الأنشطة في أندرويد. تحقق من خمس نقاط تفتيش: تأكد من تعيين <code>WebViewClient</code> مخصص؛ وتأكد من أن الدالة <code>shouldOverrideUrlLoading(WebView, WebResourceRequest)</code> ترجع القيمة <code>true</code> للمخطط المعترض؛ وتأكد من أن بنية URI وحزمة الهدف بنسبة 1 إلى 1 تجتاز قائمة السماح الخاصة بك؛ وتحقق من أن الدالة <code>startActivity(intent)</code> تعمل بسلاسة (مع التقاط الاستثناء <code>ActivityNotFoundException</code> أو تكوين الوسم `<queries>` للإصدار `targetSdk >= 30` عند استدعاء `resolveActivity()`)؛ وتأكد من أن بيان التطبيق المستهدف (Manifest) يصرح عن عنصر `<intent-filter>` متوافق مع الفئة `CATEGORY_BROWSABLE`.
لماذا تفشل الدالة shouldOverrideUrlLoading في العمل عندما يستدعي تطبيقي WebView loadUrl مباشرة؟
بموجب تصميم إطار عمل أندرويد، لا يتم استدعاء الدالة <code>shouldOverrideUrlLoading</code> لاستدعاءات <code>webView.loadUrl()</code> البادئة من التطبيق أو عمليات التنقل التي تستخدم طلبات HTTP <code>POST</code>. وهي تعمل بشكل أساسي لعمليات التنقل التي تبدأها محتويات الويب، أو تفاعلات المستخدم، أو عمليات إعادة توجيه خادم HTTP 3xx المدعومة. قم بتحفيز إعادة التوجيه التجريبية من تفاعلات DOM أو استجابات الخادم داخل الصفحة، واستخدم أغلفة المضيف الصريحة (مثل <code>loadNewNavigation</code>) عند التدقيق في عمليات التحميل البادئة من التطبيق.
لماذا تفشل روابط الوسيط target blank التي تحتوي على مخططات مخصصة بصمت داخل WKWebView؟
عندما يستخدم رابط ويب الوسيط <code>target="_blank"</code> أو الدالة <code>window.open()</code>، ينشئ WebKit طلب تنقل لنافذة جديدة تكون فيها الخاصية <code>navigationAction.targetFrame</code> مساوية للقيمة <code>nil</code>. ونظراً لأن المكون <code>WKWebView</code> لا يفتح علامات تبويب جديدة تلقائياً، فقد تفشل عمليات التنقل هذه في صمت ما لم يكتشف التطبيق المضيف أن <code>targetFrame == nil</code> داخل <code>decidePolicyForNavigationAction</code> ويقوم بتنفيذ الدالة <code>WKUIDelegate.webView(_:createWebViewWith:for:windowFeatures:)</code> لتقييم وتوجيه الطلب تحت سياسة التنقل الموحدة الخاص بها.

الملخص وإطار اتخاذ القرار

تتطلب معالجة إخفاقات إعادة توجيه الروابط العميقة في 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