‎شرحٌ مُفصَّل لملفِّ البيان ‎‎(Web App Manifest)‎‎ في تطبيقات الويب التقدميّة ‎PWA‎

‎تمهيد: التحوّل من صفحاتٍ إلى تجاربَ تطبيقية‎

ظهرت تطبيقات الويب التقدميّة ‎(Progressive Web Apps – PWA)‎ بوصفها مقاربةً تجمع أفضل ما في العالمَيْن: سهولة الوصول عبر الرابط التي يمتاز بها الويب، وتجربة المستخدم السلسة الشبيهة بالتطبيقات الأصلية ‎(Native Apps)‎ على الهواتف. ولكي تلبّي الـPWA هذه الوعود، كان لا بدّ من مستوى توصيفٍ يفهمه المتصفح كي يعرف كيف “يقدّم” الموقع في صورة تطبيق. هنا يأتي دور ملفّ البيان ‎Web App Manifest‎؛ فهو حجر الأساس الذي يصرِّح للمتصفح بكل ما يحتاجه من بيانات وصفية ليعامل الموقع كتطبيق يُثبَّت ويُشغَّل من شاشة البداية، ويعمل في وضع ملء الشاشة، بل ويستفيد من إمكانات النظام مثل الإشعارات والاختصارات.

‎المبحث الأول: ماهيّة ملفّ البيان وأهميته‎

‎تعريف الملفّ‎

ملفّ البيان وثيقة ‎JSON‎ قياسية تُسمّى ‎manifest.webmanifest‎ (أو ‎manifest.json‎) توضع في جذر الموقع غالباً، ويُستدعى رابطها عبر وسم ‎‎ في قسم ‎‎. يحتوي الملفّ على مفاتيح وقيم توضِّح:

‎لماذا هو مهمّ؟‎

من دون البيان، يبقى موقعك مجرّد صفحة ويب؛ أمّا معه فإن المتصفح يتعرّف إلى أنه تطبيق قابل للتثبيت، ويُنشئ له بطاقة تثبيت ‎(Add to Home Screen)‎ ويوفّر تجربة استخدام متماسكة وقريبة من التطبيقات الأصلية. كذلك يُتيح البيان إضافة التطبيق إلى متاجر ‎Google Play‎ و‎Microsoft Store‎ عبر ‎PWA Builder‎ أو آليات التغليف الرسمية.

‎المبحث الثاني: البنية التفصيلية لمفاتيح ‎Web App Manifest‎

‎1. الاسم وعناصر الهوية المرئية‎

‎name‎ و‎short_name‎

يُفضَّل أن يكون ‎name‎ بالغ الوضوح ويعبّر عن وظيفة التطبيق، فيما يُراعى في ‎short_name‎ ألّا يتجاوز 12–15 حرفاً لتفادي القطع. مثال:

json
CopyEdit
{
  "name": "منصة مواضيع للمحتوى العربي",
  "short_name": "مواضيع"
}

‎الأيقونات ‎icons‎

يُستحسن توفير نسخ ‎PNG‎ أو ‎SVG‎ بأبعاد 48، 72، 96، 144، 192، 256، و512 بكسل. المتصفح يختار الحجم الأنسب تبعاً للدقة والجهاز. مثال:

json
CopyEdit
"icons": [
  {
    "src": "/icons/mawade3-192.png",
    "sizes": "192x192",
    "type": "image/png",
    "purpose": "any maskable"
  },
  {
    "src": "/icons/mawade3-512.png",
    "sizes": "512x512",
    "type": "image/png"
  }
]

نصيحة فنية

إضافة السمة ‎purpose: "maskable"‎ تمكِّن نظام أندرويد من تكييف الأيقونة ضمن أشكال مختلفة من دون اقتطاع المحتوى.

‎2. نقطة الانطلاق ‎start_url‎ و‎scope‎

• start_url‎: يُفَضَّل تضمين ‎?source=pwa‎ لتتبّع زيارات التطبيق المثبَّت إحصائياً.

• scope‎: يحدِّد الحدود التي يَعُدّ المتصفح داخلها التطبيق. فإذا خرج المستخدم إلى رابط خارج ‎scope‎، سيُعاد فتحه في تبويب متصفح عادي.

json
CopyEdit
"start_url": "/?source=pwa",
"scope": "/"

‎3. وضع العرض ‎display‎

‎4. الألوان ‎theme_color‎ و‎background_color‎

• theme_color‎: يؤثر في شريط العنوان في ‎Android Chrome‎ وقوائم التبديل بين التطبيقات.

• background_color‎: يُستخدم في شاشة البداية قبل تحميل ‎index.html‎. يُنصح بمطابقة ألوان هوية العلامة.

json
CopyEdit
"theme_color": "#2d3748",
"background_color": "#ffffff"

‎5. الاتجاه ‎orientation‎

• ‎portrait‎ أو ‎landscape‎ أو ‎any‎. التزام ثابت بالاتجاه يمنع الدوران غير المرغوب أثناء التفاعل، خصوصاً في الألعاب أو تطبيقات القراءة.

‎المبحث الثالث: ميزات متقدّمة في ‎Manifest‎ (من ‎Chrome 91‎ فصاعداً)‎

‎اختصارات التطبيق ‎shortcuts‎

توفر وصولاً مباشراً لمهام داخليّة. مثال لتطبيق محتوى:

json
CopyEdit
"shortcuts": [
  {
    "name": "المقالات الجديدة",
    "short_name": "جديد",
    "url": "/latest?source=shortcut",
    "icons": [{ "src": "/icons/new.png", "sizes": "96x96" }]
  },
  {
    "name": "الأقسام",
    "short_name": "الأقسام",
    "url": "/categories",
    "icons": [{ "src": "/icons/categories.png", "sizes": "96x96" }]
  }
]

‎ملفات تعريف ‎protocol_handlers‎

تمكّن التطبيق من معالجة روابط مخصّصة ‎(مثل ‎web+music:‎). ما يزال الدعم محدوداً لكن يفتح آفاق التكامل العميق.

‎الإظهار المشروط ‎display_override‎

يسمح بتعريف مصفوفة أولويّة: إن لم يُدعَم الخيار الأول انتقل للثاني، وهكذا. مثال:

json
CopyEdit
"display_override": ["window-controls-overlay", "standalone"]

‎إثبات الأصل ‎related_applications‎

يُستخدم لربط ‎APK‎ أو ‎AppX‎ بالتطبيق الوبّي كي يقترح المتصفح التحويل إلى الإصدار الأصلي عند التثبيت.

‎المبحث الرابع: خطوات تكامل البيان عملياً‎

1. إنشاء الملفّ مع القيم الأساسية المذكورة.

2. إضافة وسم الرابط في ‎‎ وقبل أي سكربت:

   html
   CopyEdit
   <link rel="manifest" href="/manifest.webmanifest" />
   

3. تحديث خدمة العامل ‎Service Worker‎ لضمان أن ‎start_url‎ متوفّر أوفلاين.

4. اختبار الأداء عبر ‎Lighthouse‎ في أدوات مطوّري ‎Chrome‎؛ سيظهر تحذير واضح إن كان البيان مفقوداً أو ناقصاً.

5. التوقيع الرقمي (إن لزم) عند نشر ‎APK‎ ناتج من تغليف الـPWA في ‎Google Play‎.

6. مراعاة الأمان: يجب أن يُقدَّم الملفّ عبر ‎HTTPS‎ حصراً؛ المتصفحات ترفض التثبيت في حال ‎HTTP‎.

‎المبحث الخامس: الممارسات الموصى بها لتحسين الـSEO وتجربة المستخدم‎

• الموازنة بين ‎name‎ و‎short_name‎ مع الكلمات المفتاحية المستهدفة، دون حشو غير طبيعي.

• اختيار ‎theme_color‎ متباين مع لون النص في شريط الحالة لضمان قراءة واضحة.

• رفع حجم أيقونة ‎512 px‎ لتبدو حادّة على الشاشات عالية الدقة، فهو الحجم الإلزامي لـ‎Play Store‎.

• كتابة ‎description‎ غنية بما لا يقل عن 150–200 حرف، لأن متجر ‎Edge Add-ons‎ يستخدمها في نتائج البحث الداخلي.

• استخدام ‎screenshots‎ بدقة ‎1242 × 2208‎ (أيقونة عمودية) لإقناع المستخدم بالتثبيت.

• تحديث البيان دوريّاً مع تغيّر الهوية البصرية أو إضافة أقسامٍ جديدة، مع زيادة ‎version‎ (إن استُخدم مفاتيح مخصّصة).

‎المبحث السادس: مقارنة بين دعم المتصفحات‎

‎المبحث السابع: أخطاء شائعة وكيفية تفاديها‎

1. تجاهل ‎icons‎ ذات ‎purpose: maskable‎ يؤدي إلى اقتطاع شعارات دائرية في أندرويد 13+.

2. تحديد ‎start_url‎ خارج ‎scope‎ يسبّب فتح التطبيق في المتصفح بدلاً من الحاوية المستقلة.

3. نقص حجم ‎512 px‎ يعيق إدراج التطبيق في ‎Play Store‎ عبر سياسة ‎Google Play‎ الجديدة (أبريل 2024).

4. تضمين تعليقات في ‎JSON‎ إذ إن المواصفة لا تسمح بأي تعليقات، فيُرفض الملفّ بصمت.

5. إعداد ‎Mime‑Type‎ غير صحيح (يجب ‎application/manifest+json‎ أو ‎application/json‎)، ما يمنع المتصفح من قراءته.

‎خاتمة تقنية‎

ملفّ البيان ليس مجرّد وثيقة صورية بل هو عقدٌ بين مطوّر تطبيق الويب والمتصفح، يحدّد شكل التجربة، ويضمن اندماج التطبيق في بيئة نظام التشغيل. بإتقان صياغته وتحديثه تفتح أمام موقعك أبواب التوزيع في المتاجر الرسمية، وتُحسّن ولاء المستخدمين بفضل تجربة تثبيت سلسة وتفاعل قريب من التطبيقات الأصلية، مع المحافظة على مزايا الويب المفتوح من سرعة التحديث والوصول الفوري عبر الرابط.

‎المراجع‎

1. ‎W3C. “Web Application Manifest — Living Standard.” ‎https://w3c.github.io/manifest/‎.

2. ‎Mozilla Developer Network ‎(MDN)‎. “Web App Manifest.” ‎https://developer.mozilla.org/‎.