بيان تطبيق الويب

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

يجب أن يتضمّن كل تطبيق متقدّم بيانًا واحدًا لكل تطبيق، ويتم استضافته عادةً في المجلد الجذر، ويتم ربطه بجميع صفحات HTML التي يمكن تثبيت تطبيقك المتقدّم منها. وتكون لاحقته الرسمية هي .webmanifest، لذا يمكنك تسمية البيان باسم مثل app.webmanifest.

إضافة بيان تطبيق ويب إلى تطبيقك المتوافق مع الويب

لإنشاء بيان تطبيق ويب، عليك أولاً إنشاء ملف نصي يحتوي على عنصر JSON يتضمّن حقل name واحدًا على الأقل بقيمة سلسلة:

app.webmanifest:

{
   "name": "My First Application"
}

ولكن لا يكفي إنشاء الملف، بل يجب أن يعرف المتصفّح أنّه متوفّر أيضًا.

الربط ببيان التطبيق

لإعلام المتصفّح ببيان تطبيق الويب، عليك ربطه بتطبيقك المتوافق مع الأجهزة الجوّالة (PWA) باستخدام عنصر HTML‏ <link> وسمة rel التي تم ضبطها على manifest في جميع صفحات HTML لتطبيقك المتوافق مع الأجهزة الجوّالة. ويشبه ذلك طريقة ربط ورقة أنماط CSS بمستند.

index.html:

<html lang="en">
  <title>This is my first PWA</title>
  <link rel="manifest" href="/app.webmanifest">

تصحيح أخطاء البيان

لضمان إعداد البيان بشكلٍ صحيح، يمكنك استخدام "أداة الفحص" في Firefox و"أدوات مطوّري البرامج" في كل متصفّح يستند إلى Chromium.

لمتصفّحات Chromium

في أدوات مطوّري البرامج

  1. في اللوحة اليمنى، ضمن التطبيق، اختَر بيان التطبيق.
  2. تحقَّق من حقول البيان كما عالجها المتصفّح.

في Firefox

  1. افتح "أداة التحقّق".
  2. انتقِل إلى علامة التبويب "التطبيق".
  3. اختَر خيار البيان في اللوحة اليمنى.
  4. تحقَّق من حقول البيان كما عالجها المتصفّح.

تصميم تجربة تطبيق الويب التقدّمي

بعد ربط تطبيقك المتوافق مع الأجهزة الجوّالة بالبيان، حان الوقت لملء بقية الحقول لتحديد تجربة المستخدمين.

الحقول الأساسية

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

name
الاسم الكامل لتطبيقك المتوافق مع الأجهزة الجوّالة وسيظهر مع الرمز في الشاشة الرئيسية أو مشغِّل التطبيقات أو شريط التطبيقات المضمّنة أو القائمة في نظام التشغيل.
short_name
اسم أقصر لتطبيقك المتوافق مع الأجهزة الجوّالة، وهو اختياري ويُستخدَم عندما لا تتوفّر مساحة كافية لعرض القيمة الكاملة لحقل name. يجب ألا يزيد عن 12 حرفًا لتقليل احتمالية اقتطاعه.
icons
صفيف عناصر الرموز مع حقول src وtype وsizes وحقل purpose اختياري، يصف الصور التي يجب أن تمثّل تطبيق الويب التقدّمي
start_url
عنوان URL الذي يجب أن تحمّله تطبيقك المتوافق مع الأجهزة الجوّالة عند تشغيله من الرمز المثبَّت. ننصحك باستخدام مسار مطلق، فإذا كانت الصفحة الرئيسية لتطبيقك المتوافق مع الأجهزة الجوّالة (PWA) هي الجذر لموقعك الإلكتروني، يمكنك ضبط هذا المسار على "‎/" لفتحه عند بدء تشغيل تطبيقك. إذا لم تقدِّم عنوان URL لصفحة البداية، يمكن للمتصفّح استخدام عنوان URL الذي تم تثبيت تطبيق الويب التقدّمي منه كعنوان بداية. ويمكن أن يكون رابطًا لصفحة في التطبيق، مثل تفاصيل منتج بدلاً من الشاشة الرئيسية.
display
أحد العناصر fullscreen أو standalone أو minimal-ui أو browser، لوصف كيفية رسم نظام التشغيل لنافذة تطبيق الويب التقدّمي يمكنك الاطّلاع على مزيد من المعلومات حول أوضاع العرض المختلفة في فصل "تصميم التطبيق". تُنفِّذ معظم حالات الاستخدام standalone.
id
سلسلة تُحدِّد تطبيق الويب التقدّمي هذا بشكل فريد عن التطبيقات الأخرى التي قد تكون مستضافة على المصدر نفسه. وفي حال عدم ضبطها، سيتم استخدام start_url كقيمة احتياطية. يُرجى العِلم أنّه من خلال تغيير start_url في المستقبل (مثلاً عند تغيير قيمة سلسلة طلب البحث)، قد تزيل قدرة المتصفّح على رصد أنّه سبق تثبيت تطبيق ويب تقدّمي.

الرموز

يمثّل رمز تطبيقك المتوافق مع الأجهزة الجوّالة (PWA) هويته المرئية على أجهزة المستخدمين عند تثبيته، لذا من المهم تحديد رمز واحد على الأقل. بما أنّ سمة icons هي مجموعة من عناصر الرموز، يمكنك تحديد عدة رموز بتنسيقات مختلفة لتقديم أفضل تجربة رموز للمستخدمين. سيختار كل متصفح رمزًا واحدًا أو أكثر استنادًا إلى احتياجاته ونظام التشغيل المثبَّت عليه، مع الحرص على اختيار الرموز الأقرب إلى المواصفات المطلوبة.

إذا كنت بحاجة إلى اختيار حجم رمز واحد فقط، يجب أن يكون 512 × 512 بكسل. ومع ذلك، ننصحك بتوفير المزيد من الأحجام، بما في ذلك الصور التي تبلغ أبعادها 192 x ‏192 و384 x ‏384 و1024 x ‏1024 بكسل أيضًا.

"icons": [
   {
      "src": "icons/512.png",
      "type": "image/png",
      "sizes": "512x512"
   },
   {
      "src": "icons/1024.png",
      "type": "image/png",
      "sizes": "1024x1024"
   }
]

إذا لم تقدِّم رمزًا أو لم تكن الرموز بالحجم المُقترَح، لن تجتاز معايير التثبيت على بعض المنصات. على المنصات الأخرى، سيتم إنشاء الرمز تلقائيًا، على سبيل المثال من لقطة شاشة لتطبيق الويب التقدّمي أو باستخدام رمز عام.

الرموز القابلة للإخفاء

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

ولإجراء ذلك، يجب تقديم ملف صورة مربّع يحتوي على رمزه الرئيسي ضمن "منطقة آمنة"، وهي دائرة في وسط الرمز يبلغ نصف قطرها ‎40% من عرض الرمز. (اطّلِع على الصورة أدناه). ستتم إزالة رمز التطبيق حسب الحاجة على الأجهزة التي تتيح ذلك.

المنطقة الآمنة التي تم تمييزها كدائرة نصف قطرها 40% في وسط الرمز المربّع

في ما يلي مثال على رمز قابل للتمويه معروض بعدد من الأشكال الشائعة الاستخدام:

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

رمز غير مناسب ليكون رمزًا قابلاً للإخفاء

يمكن استخدام هذه الصورة من خلال إضافة المزيد من المسافة الفارغة.

يكون الرمز الذي يتضمّن مساحة إضافية مناسبًا للأقنعة.

يجب أن تكون الرموز القابلة للتغطية بدقة 512 × 512 بكسل على الأقل. بعد إنشاء ملف شخصي، يمكنك إضافته إلى مجموعة icons لتحسين تجربة استخدام الأجهزة المتوافقة:

"icons": [
   {
      "src": "/icons/512.png",
      "type": "image/png",
      "sizes": "512x512"
   },
   {
      "src": "/icons/1024.png",
      "type": "image/png",
      "sizes": "1024x1024"
   },
   {
      "src": "/icons/512-maskable.png",
      "type": "image/png",
      "sizes": "512x512",
      "purpose": "maskable"
   },
]

في معظم الحالات، إذا لم يكن الرمز القابل للتمويه معروضًا بشكل جيد، يمكنك تحسينه من خلال إضافة المزيد من المسافة البادئة. ‫Maskable.app هي أداة مجانية على الإنترنت لاختبار رمز تطبيقك وإنشاء نسخة قابلة للتمويه منه.

إذا كان الرمز يخدم أغراضًا عامة وقابلة للتمويه، يمكنك ضبط الحقل purpose على "any maskable". راجِع مستندات بيان تطبيق الويب على MDN للاطّلاع على التفاصيل.

المجموعة التالية من الحقول التي يجب تضمينها هي الحقول التي ستُحسِّن تجربة المستخدم، على الرغم من أنّها غير مطلوبة لإمكانية التثبيت.

theme_color
اللون التلقائي للتطبيق، والذي يؤثر أحيانًا في كيفية عرض نظام التشغيل للموقع الإلكتروني (على سبيل المثال، لون النافذة وشريط العنوان على الكمبيوتر المكتبي أو لون شريط الحالة على الأجهزة الجوّالة). يمكن إلغاء هذا اللون باستخدام عنصر HTML theme-color <meta>.
background_color
لون العنصر النائب الذي يتم عرضه في خلفية التطبيق قبل تحميل جدول الأنماط يتجاهل متصفّح Safari على iOS وiPadOS ومعظم متصفّحات أجهزة الكمبيوتر المكتبي هذا الحقل حاليًا.
scope
يؤدي هذا الإجراء إلى تغيير نطاق التنقّل في تطبيق الويب المتوافق مع الأجهزة الجوّالة، ما يتيح لك تحديد العناصر التي يتم عرضها أو عدم عرضها في نافذة التطبيق المثبَّت. على سبيل المثال، إذا أشرت إلى صفحة خارج النطاق، سيتم عرضها في متصفّح داخل التطبيق بدلاً من عرضها في نافذة تطبيقك المتوافق مع الأجهزة الجوّالة. ولن يؤدي ذلك إلى تغيير نطاق عامل الخدمة.

توضِّح الصورة التالية كيفية استخدام الحقل theme_color لشريط العنوان على جهاز كمبيوتر مكتبي عند تثبيت تطبيق متوافق مع الأجهزة الجوّالة.

تطبيق PWA نفسه مثبَّت على الكمبيوتر المكتبي بلون مظهر مختلف

.

عند تحديد الألوان في البيان، مثل theme_color وbackground_color، يجب استخدام ألوان مُسمّاة في CSS، مثل salmon أو orange، أو ألوان RGB مثل #FF5500، أو دوال ألوان بدون شفافية مثل rgb() أو hsl(). راجِع فصل تصميم التطبيق للحصول على مزيد من المعلومات.

تجربة الميزة

شاشات البداية

على بعض الأجهزة، يتم عرض صورة ثابتة أثناء تحميل تطبيقك المتوافق مع الأجهزة الجوّالة (PWA) لتقديم ملاحظات فورية للمستخدم.

يستخدم نظام التشغيل Android القيم theme_color وbackground_color وicon لإنشاء شاشة البداية.

عند تثبيت تطبيق متوافق مع الأجهزة الجوّالة على Android، سينشئ الجهاز شاشة البداية التي تتضمّن المعلومات الواردة من البيان، كما هو موضّح في المخطّط البياني التالي.

تطبيق متوافق مع الأجهزة الجوّالة على شاشة البداية في Android يعرض قيمًا مختلفة عن البيان

من ناحية أخرى، لا يستخدم Safari على نظامَي التشغيل iOS وiPadOS بيان تطبيق الويب لإنشاء شاشات البداية. بدلاً من ذلك، يتم استخدام صورة مرتبطة من عنصر <link> مملوك، تمامًا مثل الطريقة التي يتم بها التعامل مع الرموز. اطّلِع على فصل التحسين للحصول على مزيد من التفاصيل.

الحقول الموسّعة

تقدّم المجموعة التالية من الحقول معلومات إضافية عن تطبيقك المتوافق مع الأجهزة الجوّالة. وجميعها اختيارية.

lang
علامة لغة تحدّد اللغة الأساسية لقيم البيان، مثل en للغة الإنجليزية أو pt-BR للبرتغالية البرازيلية أو in للهندية.
dir
اتجاه عرض حقول البيان المتوافقة مع الاتجاه (مثل name وshort_name وdescription). القيم الصالحة هي auto وltr (من اليسار إلى اليمين) وrtl (من اليمين إلى اليسار).
orientation
اتجاه التطبيق المطلوب بعد تثبيته قد تضبط اللعبة هذا الخيار لطلب الاتجاه الأفقي فقط. يتم قبول عدة قيم، ولكن في حال تضمينها، تكون عادةً portrait أو landscape بشكل صريح.

الحقول الترويجية

تتيح لك المجموعة الرابعة من الحقول تقديم معلومات ترويجية عن تطبيقك المتوافق مع الأجهزة الجوّالة (PWA)، على سبيل المثال، في عمليات التثبيت والبيانات ونتائج البحث.

description
شرح لدور تطبيق الويب التقدّمي
screenshots
صفيف من عناصر لقطات الشاشة التي تتضمّن src وtype وsizes (مشابه لعنصر icons) بهدف عرض تطبيق الويب التقدّمي ما مِن قيود على الحجم.
categories
صفيف للفئات التي يجب أن تنتمي إليها التطبيقات المتوافقة مع الأجهزة الجوّالة (PWA) لاستخدامها كاقتراحات للبيانات، اختياريًا من قائمة الفئات المعروفة وتكون هذه القيم عادةً بأحرف صغيرة.
iarc_rating_id
رمز شهادة الاتحاد الدولي لتقييم المحتوى حسب الفئات العمرية لتطبيق الويب التقدّمي، في حال توفّره ويُقصد استخدامه لتحديد الفئات العمرية التي تناسبها تطبيقك المتوافق مع الأجهزة الجوّالة.

يمكنك الاطّلاع على هذه الحقول الترويجية في الوقت الحالي. على نظام التشغيل Android، على سبيل المثال، إذا كان تطبيقك المتوافق مع الأجهزة الجوّالة على الويب قابلاً للتثبيت وقدّمت قيمًا لحقول description وscreenshots على الأقل، ستتغيّر تجربة مربّع حوار التثبيت من شريط معلومات بسيط "إضافة إلى الشاشة الرئيسية" إلى مربّع حوار تثبيت أكثر شمولاً يشبه مربّع الحوار من متجر التطبيقات.

على أجهزة Android، يمكنك الحصول على واجهة مستخدم تثبيت أكثر جمالًا إذا قدّمت قيمًا للحقول الترويجية، كما هو موضّح في الفيديو التالي.

إليك أمثلة على استخدام هذه الحقول الترويجية:

حقول الإمكانات

أخيرًا، هناك عدد من الحقول ذات الصلة بإمكانات مختلفة يمكن لتطبيقك المتوافق مع الأجهزة الجوّالة استخدامها في المتصفحات المتوافقة، مثل حقول shortcuts وshare_target وdisplay_override كما سنتناول في فصل "الإمكانات". هناك أيضًا حقول، مثل related_apps وprefer_related_apps (اطّلِع على فصل "الاكتشاف" للحصول على مزيد من المعلومات)، لربط تطبيقك المتوافق مع الويب بالتطبيقات المثبّتة، والتي غالبًا ما تكون من متجر تطبيقات.

قد تظهر العديد من الحقول الجديدة في المستقبل عندما تضيف المتصفّحات المزيد من الإمكانات إلى تطبيقات الويب التقدّمية.

الموارد