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

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

يجب أن يتضمّن كل تطبيق متقدّم بيانًا واحدًا لكل تطبيق، ويتم استضافته عادةً في المجلد الجذر، ويتم ربطه بجميع صفحات 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. تحقَّق من حقول البيان كما عالجها المتصفّح.

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

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

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

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

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

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

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

توضِّح الصورة التالية كيفية استخدام الحقل 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 (راجِع فصل الرصد لمزيد من المعلومات)، لربط تطبيق الويب التقدّمي (PWA) بالتطبيقات المثبّتة، وغالبًا ما يكون ذلك من متجر التطبيقات.

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

الموارد