فاحص ملف Web Manifest

ما هو ملف Web App Manifest؟

ملف Web App Manifest ملف JSON تربطه الصفحة عبر link rel="manifest"، ويخبر المتصفح كيف يثبّت الموقع كتطبيق: اسمه واسمه المختصر، وstart_url الذي يفتحه، وscope الذي يتحكم فيه، ونمط العرض، والأيقونات لكل موضع. ويُحل start_url وscope نسبةً إلى عنوان الملف نفسه ويجب أن يبقيا على أصله، ولا يعرض Chrome التثبيت إلا حين يحوي الملف اسماً وstart_url ونمط عرض قابلاً للتثبيت وأيقونتين بمقاسي 192 و512 بكسل، في صفحة تُقدَّم عبر HTTPS.

كيفية استخدام فاحص ملف Web Manifest

1. أدخل عنوان صفحة (فيتبع الفاحص رابط manifest فيها) أو عنوان ملف manifest نفسه — أو الصق JSON الملف في الحقل الثاني.
2. أبقِ خيار «اطلب ملفات الأيقونات» مفعّلاً للتحقق من أن الأيقونات التي يسردها الملف المجلوب موجودة فعلاً.
3. اضغط «افحص ملف manifest» واقرأ جدول معايير التثبيت أولاً: كل نتيجة «لم ينجح» سببٌ يمنع Chrome من عرض تثبيت التطبيق.
4. أصلح الأخطاء، وانظر في التحذيرات (الوصف، وid، والأيقونة القابلة للقص، ولقطات الشاشة)، ثم أعد الفحص.

مزايا فاحص ملف Web Manifest

• يعثر على ملف manifest انطلاقاً من عنوان صفحة بقراءة رابط rel="manifest" فيها، أو يقرأ عنوان ملف manifest مباشرة، عبر خادم متقن
• يتحقق من JSON الملصوق بالكامل في متصفحك، مع عنوان اختياري لحلّ مسارات start_url وscope والأيقونات
• يفحص كل عضو تستخدمه مواصفة W3C والمتصفحات الحالية: name وshort_name، وid، وstart_url وscope (الأصل الواحد، ووقوع start_url داخل scope)، وdisplay وdisplay_override، وorientation، وdir، وlang، والألوان، والأيقونات، والاختصارات، ولقطات الشاشة، والأعضاء القديمة
• يقيّم معايير التثبيت الموثّقة في Chrome واحداً واحداً — HTTPS، والاسم، وstart_url على الأصل نفسه، ونمط عرض قابل للتثبيت، وأيقونتا 192 و512 بكسل بغرض any، وعدم ضبط prefer_related_applications على true — ويذكر ما تعذّر فحصه
• يسرد الأيقونات بمقاساتها ونوعها وغرضها، ويستطيع طلب كل ملف أيقونة (حتى ثمانية، بطلب HEAD فقط) للتأكد من وجوده وتقديمه كصورة
• ينبّه حين لا يُقدَّم الملف بنوع وسائط JSON (والنوع المسجّل لملفات manifest هو application/manifest+json)، وحين يعيد عنوان manifest صفحة HTML

المدخلات والمخرجات

المدخلات

• عنوان الصفحة أو ملف manifest — صفحة عامة تربط ملفاً، أو عنوان الملف نفسه؛ ومع JSON الملصوق يقتصر دوره على حلّ الأعضاء النسبية.
• أو الصق JSON الملف — يُتحقق منه في المتصفح دون إرسال أي شيء.
• اطلب ملفات الأيقونات — مفعّل افتراضياً؛ يفحص حتى ثمانية عناوين أيقونات من الملف المجلوب بطلب HEAD.

المخرجات

• الملخص — هل استوفيت معايير التثبيت في Chrome أم لم تُستوفَ أم لم تُفحص كاملة، وعدد الأخطاء والتحذيرات والأيقونات والأعضاء.
• معايير التثبيت (Chrome) — كل معيار مع «نجح» أو «لم ينجح» أو «لم يُفحص».
• الأخطاء والتحذيرات — كل مشكلة وجدها التحقق، بجمل واضحة.
• ملف manifest — القيم الفعلية لـ name وshort_name وid وstart_url وscope وdisplay والألوان، وعنوان الملف، والصفحة التي ربطته، وContent-Type.
• الأيقونات — العنوان المحلول لكل أيقونة ومقاساتها ونوعها وغرضها ورمز حالة HTTP والنوع المقدَّم؛ ويمكن تنزيلها بصيغة CSV.

مثال على فاحص ملف Web Manifest

عنوان الصفحة أو ملف manifest: https://www.example.com/ · اطلب ملفات الأيقونات: مفعّل

Install criteria Not met · Errors 5 · Warnings 7 · Icons 1 · Members 5
Served over HTTPS Pass · start_url on the manifest's origin Fail · Installable display mode Fail · Icon of 512×512 or larger with purpose any Fail
The start_url resolves to https://other.example.org, another origin than the manifest (https://www.example.com); start_url must be on the same origin.
The display "browser" is not installable; use "standalone", "minimal-ui" or "fullscreen".
The theme_color "blue-ish" is not a CSS color.
The icon https://www.example.com/i/192.png could not be loaded: HTTP 404.
The manifest is served as text/plain, not as JSON; the specification asks for application/manifest+json (any JSON media type is accepted).

كيف تقرأ نتائج فاحص ملف Web Manifest

الأخطاء تكسر الملف أو التثبيت: JSON غير صالح، أو غياب name أو start_url، أو start_url على أصل آخر، أو display بقيمة "browser"، أو غياب أيقونتي 192 و512 بكسل بغرض any. والمتصفحات تتجاهل الأعضاء غير الصالحة، فالخطأ يعني أيضاً أن ذلك الإعداد بلا أثر.

التحذيرات تحسينات: وصف ولقطات شاشة لنافذة التثبيت الغنية، وid صريح ليمكن تغيير start_url لاحقاً، وأيقونة قابلة للقص لأندرويد، وshort_name لا يتجاوز 12 حرفاً.

«لم يُفحص» يعني أن المعلومة غير متاحة — فلا يمكن الحكم على HTTPS وقواعد الأصل الواحد في JSON ملصوق دون عنوان الملف الحقيقي — لذا فإن «لم تُفحص كاملة» ليست نجاحاً.

استيفاء المعايير يتيح لـ Chrome عرض التثبيت، لكنه لا يضمن ظهوره فوراً، لأن المتصفح ينتظر أيضاً تفاعل المستخدم، ولبعض المتصفحات معاييرها الخاصة.

متى تستخدم فاحص ملف Web Manifest

• اعرف لماذا لا يظهر زر التثبيت في المتصفح لتطبيق الويب التقدّمي الخاص بك.
• راجع ملف manifest قبل الإصدار: start_url وscope على الأصل نفسه، ومقاسات الأيقونات وأغراضها، والألوان ونمط العرض.
• بعد نقل الموقع أو تغيير CDN، تأكد أن ملف manifest وأيقوناته ما زالت تُقدَّم، وبأي Content-Type.
• تحقق من ملف manifest ما زلت تحرّره بلصقه، دون الحاجة إلى نشره.

استكشاف الأخطاء وإصلاحها

• رسالة «The manifest URL returned an HTML page, not JSON»: الرابط يشير إلى مسار يجيب بصفحة خطأ أو بالصفحة الرئيسية. تحقق من href في رابط rel="manifest" ومن نشر الملف.
• رسالة «The page links no web app manifest»: الرابط غير موجود في HTML الذي يرسله الخادم — ربما يُضاف لاحقاً عبر JavaScript الذي لا يشغّله الفاحص. أدخل عنوان الملف مباشرة.
• يفشل start_url في فحص الأصل الواحد بعد النقل إلى مضيف CDN: يجب أن يكون start_url وscope على أصل الملف نفسه، فقدّم الملف من أصل التطبيق أو استخدم عناوين نسبية.
• الأيقونات تجيب بالرمز 404 مع أنها موجودة: قيم src تُحل نسبةً إلى عنوان ملف manifest لا عنوان الصفحة؛ فالملف الموجود في /static/ مع src بقيمة "icons/a.png" يشير إلى /static/icons/a.png.
• ظهر تحذير «تعذّر طلب ملفات الأيقونات» مع رسالة بلوغ حد الطلبات: كل عنوان أيقونة يستهلك واحداً من فحوص الملفات العشرة المسموح بها في الدقيقة دون تسجيل الدخول (30 بعد تسجيل الدخول)، والصفحة وملف manifest يستهلكان عمليتين من عمليات جلب الصفحات العشر المشتركة مع الأدوات الأخرى. انتظر دقيقة، أو ألغِ تحديد «اطلب ملفات الأيقونات» لفحص ملف manifest وحده.

الأسئلة الشائعة حول فاحص ملف Web Manifest

ملاحظات تقنية

تعرّف مواصفة W3C لملف Web Application Manifest الأعضاءَ وطريقة معالجتها: يُحل start_url وscope نسبةً إلى عنوان الملف ويجب أن يشاركاه الأصل، ويجب أن يقع start_url داخل scope، ويرجع display إلى "browser" افتراضياً، وتوصف كل أيقونة بـ src وsizes وtype وpurpose (any أو maskable أو monochrome). وتسجّل المواصفة نوع الوسائط application/manifest+json.

في وضع العنوان تُطلب الصفحة عبر POST /api/v1/internet/http/fetch (مع حلّ الاسم عبر DNS over HTTPS أولاً، ورفض العناوين الخاصة، واتباع حتى خمس عمليات إعادة توجيه)؛ فإن كان Content-Type من نوع JSON أو manifest، أو بدأ المحتوى بـ "{"، عُدّ هو الملف نفسه، وإلا حُلّ أول رابط rel="manifest" في HTML نسبةً إلى عنوان الصفحة وجُلب بالطريقة نفسها. وتُرسَل ملفات الأيقونات إلى POST /api/v1/internet/http/assets بطلب HEAD.

يتبع جدول التثبيت معايير Chrome المنشورة (web.dev، «What does it take to be installable?»). أما مقاييس التفاعل التي يطبقها Chrome أيضاً — نقرة على الصفحة وبعض الوقت فيها — فتعتمد على زائر حقيقي وليست جزءاً من الفحص.

الحدود ومنهجية القياس

لا يُفحص إلا ملف manifest؛ فلا يُقيَّم عامل الخدمة (Service Worker) ولا العمل دون اتصال ولا مقاييس التفاعل، وقد تستخدم متصفحات أخرى معايير تثبيت مختلفة قليلاً.

تُجلب الصفحات وملفات manifest مرة واحدة من خادم متقن على شبكة Cloudflare دون تشغيل JavaScript، ولا يُقرأ من كل منها أكثر من 512 كيلوبايت.

تُفحص ملفات الأيقونات بطلب HEAD فقط وبحد أقصى ثمانية في الفحص الواحد؛ ولا يُتحقق من مقاسها الحقيقي بالبكسل ولا من مظهرها.

الأمان والخصوصية

JSON الملصوق لا يغادر متصفحك أبداً. وفي وضع العنوان يتسلّم خادم متقن العنوان الذي أدخلته، وعنوان ملف manifest الذي يربطه، وما يصل إلى ثمانية عناوين أيقونات، فيطلبها بترويسات ثابتة دون أي من ملفات تعريف الارتباط الخاصة بك، ولا يخزّن شيئاً.

المراجع

• Web Application ManifestW3Cمواصفة ملف manifest: أعضاؤه (name وshort_name وstart_url وscope وdisplay وicons وغيرها)، وكيف تُحل نسبةً إلى عنوان الملف، وقواعد الأصل الواحد، ونوع الوسائط application/manifest+json.
• Web application manifest — MDNMDN Web Docs (Mozilla)مرجع لكل عضو في ملف manifest تدعمه المتصفحات، مع قيمه، ومثال لملف كامل، وكيف تربطه الصفحة عبر link rel="manifest".
• What does it take to be installable?web.dev (Google)معايير Chrome لعرض التثبيت: HTTPS، وملف manifest فيه name أو short_name، وأيقونتا 192 و512 بكسل، وstart_url، ونمط عرض قابل للتثبيت، وغياب prefer_related_applications أو ضبطه على false، إضافة إلى تفاعل المستخدم.