پیش از این در بحث چیستی PWA گفتیم یک برنامه‌ی وبی پیشرو همانند نرم افزارهای غیر وبی در دستگاه کاربر قابل نصب است و آیکون آن در صفحه‌اصلی قابل نمایش خواهد بود و به صورت آفلاین هم کار می‌کند. در مورد چگونگی پیاده‌سازی برنامه به طوری که بتواند به صورت آفلاین هم اجرا شود قبلاً در موضوع Service Worker بحث کردیم. اکنون می‌خواهیم در مورد قابلیت نصب PWA صحبت کنیم.
اگر قرار باشد برنامه‌ی وبی نصب شود، لازم است یک جایی مشخص کنیم از چه آیکونی برای نصب استفاده شود، یا نام برنامه چه چیزی باشد، یا اینکه وقتی روی آیکون برنامه کلیک کرد کدام زیرصفحه از برنامه اجرا شود. این تنظیمات در قالب یک فایل JSON که به آن «اعلامیه‌ی وب‌اپلیکیشن» یا «Web app manifest» گفته می‌شود نوشته می‌شود.
از لحاظ فنّی حداقل چیزی که برای قابل نصب کردن PWA لازم داریم Service Worker و اعلامیه‌ی وب‌اپلیکیشن و فعّال بودن SSL است، در غیر این صورت اصلاً PWA قابل نصب نخواهد بود. یا بهتر بگوییم: در غیر این صورت برنامه‌ی وبی ما اصلاً PWA نیست!
تقریباً تمام مرورگرها از اعلامیه‌ی وب‌اپلیکیشن پشتیبانی می‌کنند، به غیر از مرورگر Safari که پشتیبانی ناقصی از این اعلامیه دارد. به اعتقاد بعضی‌ها امروز ما از شرّ مرورگر Internet Explorer خلاص شده‌ایم، ولی با Internet Explorer دومی درگیر شده‌ایم به نام Safari 😶.
ایجاد Web app manifest
یک فایل جدید با هر اسمی که دوست داشتید بسازید. البته معمولاً اسم آن را manifest.json می‌گذارند. این فایل را باید در root سایت قرار بدهید (مثلاً اگر پروژه‌ی شما روی folan.com است، اعلامیه را روی آدرس folan.com/manifest.json قرار دهید و آن را درون زیرپوشه‌ای قرار ندهید). البته فرمت این فایل را غیر از json می توانید webmanifest هم بگذارید، ولی خوب همان json قابل فهم‌تر است.
برای معرفی این فایل در HTML از یک عنصر <link> به این صورت داخل <head> استفاده می‌کنیم:
<link rel="manifest" href="manifest.json">سپس محتوایی مشابه کد زیر را درون آن کپی می‌کنیم:
{
"short_name": "Weather",
"name": "Weather: Do I need an umbrella?",
"icons": [
{
"src": "/images/icons-192.png",
"type": "image/png",
"sizes": "192x192"
},
{
"src": "/images/icons-512.png",
"type": "image/png",
"sizes": "512x512"
}
],
"start_url": "/?source=pwa",
"background_color": "#3367D6",
"display": "standalone",
"scope": "/",
"theme_color": "#3367D6",
"shortcuts": [
{
"name": "How's weather today?",
"short_name": "Today",
"description": "View weather information for today",
"url": "/today?source=pwa",
"icons": [{ "src": "/images/today.png", "sizes": "192x192" }]
},
{
"name": "How's weather tomorrow?",
"short_name": "Tomorrow",
"description": "View weather information for tomorrow",
"url": "/tomorrow?source=pwa",
"icons": [{ "src": "/images/tomorrow.png", "sizes": "192x192" }]
}
],
"description": "Weather forecast information",
"screenshots": [
{
"src": "/images/screenshot1.png",
"type": "image/png",
"sizes": "540x720"
},
{
"src": "/images/screenshot2.jpg",
"type": "image/jpg",
"sizes": "540x720"
}
]
}در ادامه با چند تا از فیلدهای مهم‌تر web app manifest آشنا می‌شویم.
تنظیمات مهم Web app manifest
short_name یا name
نوشتن مقدار برای یکی از دو فیلد name یا short_name از ضروریات اعلامیه‌ی وب اپلیکیشن است. این دو فیلد نام برنامه را مشخص می‌کنند. این نام پس از نصب PWA زیر آیکون نمایش داده خواهد شد. اگر مقدار هر دوی این فیلدها را وارد کنید، در بیشتر جاها نام کوتاه (short_name) مورد استفاده قرار می‌گیرد، زیرا در بیشتر جاها برای نمایش نام طولانی محدودیت فضا داریم.
icons
برای تعیین آیکون PWA پس از نصب که در صفحه اصلی یا سایر جاها دیده می‌شود از این فیلد استفاده می‌شود. فیلد icons آرایه‌ای از اشیاء آیکون را می‌گیرد که هر کدام یک ویژگی src برای تعیین آدرس آیکون، یک ویژگی type برای تعیین نوع آیکون و یک ویژگی sizes برای تعیین اندازه‌ی آیکون می‌گیرند.
در مرورگر کروم اگر آیکون برنامه‌ی خود را تنها در دو سایز ۱۹۲×۱۹۲پیکسل و ۵۱۲×۵۱۲پیکسل معرّفی کنید کافیست و خود مرورگر برای سایر سایزها آیکون را تغییر اندازه می‌دهد. ولی اگر خیلی وسواسی هستید می‌توانید کلاً هر چه آیکون از مضرب ۴۸ وجود دارد در اینجا معرّفی کنید.
start_url
تعیین می‌کند که هنگام کلیک روی آیکون PWA نصب‌شده، کدام زیرصفحه از برنامه‌ی وبی پیشروی ما باز شود.
این url باید مستقیماً کاربر را وارد برنامه کند، نه اینکه او را وارد صفحه‌ی فرودی کند که مثلاً در مورد امکانات و چیستی محصول توضیح می‌دهد.
background_color
این فیلد رنگ صفحه‌ی Splash را که پیش از باز شدن PWA خیلی سریع نشان داده می‌شود را تعیین می‌کند.
display
تعیین می‌کند رابط کاربری مرورگر در زمانی که PWA نصب‌شده را باز می‌کند چه طور باشد. مثلاً آیا نوار آدرس مرورگر دیده شود یا نه. حتّی می‌توانید تنظیم کنید برنامه‌ی شما به صورت تمام‌صفحه اجرا شود که برای بازی‌های تحت وب کاربردی است.
مقادیر مجاز display به این شرح است:
| مقدار | کاربرد |
|---|---|
fullscreen | PWA به صورت تمام‌صفحه بدون اینکه هیچ قسمتی از نوار آدرس مرورگر و رابط کاربری آن دیده شود باز می‌شود. |
standalone | PWA را در یک پنجره‌ی مجزّا از مرورگر باز می‌کند که شامل نوار آدرس و سایر عناصر رابط کاربری مرورگر نیست. هدف این است که PWA به شکل یک نرم افزار کاملاً مستقل به نظر بیاید. |
minimal-ui | این حالت شبیه به همان standalone است با این تفاوت که دکمه‌های refresh و back از رابط کاربری مرورگر در آن وجود خواهند داشت. |
browser | PWA را به صورت یک برنامه‌ی تحت وب عادی در مرورگر باز می‌کند. |
display_override
ویژگی display یک مشکل دارد، آن هم اینکه همه‌ی مرورگرها لزوماً همه‌ی حالت‌های display را پشتیبانی نمی‌کنند. ولی از زنجیره‌ی جایگزینی پشتیبانی می‌کنند ("fullscreen" → "standalone" → "minimal-ui" → "browser").
اگر مرورگری display مورد نظر ما را پشتیبانی نکند طبق دنباله‌ی فوق به سراغ display بعدی می‌رود و بر اساس آن کار می‌کند.
این رفتار در برخی موارد خاص مشکل ایجاد می‌کند، مثلاً اگر برنامه‌نویسی بخواهد به صورت کلی از minimal-ui استفاده کند، ولی در صورت عدم پشتیبانی بخواهد از حالت standalone استفاده کند نمی‌تواند چنین تنظیمی انجام دهد! مشکل بعدی این است که اگر قرار باشد در آینده یک حالت جدید به ویژگی display اضافه شود جایگاهی در این دنباله ندارد و اگر سازندگان مرورگرها بخواهند آن حالت جدید را در این دنباله قرار دهند، کدهای قدیمی به مشکل می‌خورند.
برای حل این دو مشکل ویژگی جدیدی به نام display_override اضافه شد که به عنوان مقدار، آرایه‌ای از حالت‌های مختلف display را می‌گیرد. مرورگر به ترتیب عناصر آرایه را بررسی می‌کند و همین که به اوّلین حالتی رسید که آن را پشتیبانی می‌کرد همان را اعمال می‌کند.
در صورتی که display_override مقدار داشته باشد، مرورگر ویژگی display را نادیده می‌گیرد، مگر اینکه هیچکدام از حالت‌هایی را که در display_override نوشته‌ایم پشتیبانی نکند!
هشدار: اگر در اعلامیه‌ی وب‌اپلیکیشن مقداری برای display ننویسید، مرورگر display_override را نیز نادیده می‌گیرد! یعنی هرچند با وجود display_override نیازی به display دیده نمی‌شود، ولی تعیین مقدار display ضروری است در این حالت!
برای درک بهتر مثال زیر را بررسی می‌کنیم:
{
"display_override": ["window-control-overlay", "minimal-ui"],
"display": "standalone",
}در اینجا مرورگر به این ترتیب پیش می‌رود، و طبق روال زیر همین که به اوّلین حالتی برسد که بتواند آن را پشتیبانی کند، از همان استفاده می‌کند:
window-control-overlay(مرورگر ابتدا فقطdisplay_overrideرا بررسی می‌کند).minimal-uistandalone(اگر هیچکدام از آیتم‌هایdisplay_overrideپشتیبانی نمی‌شدند به سراغdisplayمی‌رود).minimal-ui(طبق زنجیره‌ی جایگزینی به سراغ حالت بعد ازstandaloneمی‌رود).browser
scope
این ویژگی مشخّص می‌کند مرورگر دقیقاً چه urlهایی از سایت ما را زیرمجموعه‌ی PWA در نظر بگیرد، و برای اینکه متوجّه بشویم چه زمانی کاربر از اپلیکیشن خارج شده است استفاده می‌شود. توجّه داشته باشید که start_url حتماً باید درون scope باشد.
هشدار: اگر کاربری روی لینکی خارج از scope کلیک کند، باز هم آن لینک درون خود اپلیکیشن باز می‌شود، مگر اینکه صراحتاً روی تگ a صفت target="_blank" گذاشته باشید. در اندروید چنین لینک‌هایی در Chrome Custom Tab باز می‌شوند.
اگر در اعلامیه‌ی خود صراحتاً scope را تعیین نکنید، پیش‌فرض آن همان پوشه‌ای است که فایل اعلامیه در آن قرار دارد.
scope می‌تواند به صورت آدرسی نسبی نوشته شود (../)، یا حتّی در سطوح بالاتر (/).
start_url باید درون scope باشد، و آدرس آن نسبت به آدرس scope تعیین می‌شود.
theme_color
این ویژگی رنگ نوار ابزار مرورگر را تعیین می‌کند. مقدار آن باید با theme-color که در تگ meta نوشته می‌شود یکسان باشد.
از نسخه ۹۳ کروم قابلیت تعیین theme color بر اساس media query هم اضافه شده است، که مثلاً با استفاده از آن می‌شود برای حالت dark و light رنگ متفاوتی را تعیین کرد. برای این کار باید از تگ meta به این شکل استفاده شود، و هنوز فیلدی در اعلامیه‌ی وب‌اپلیکیشن برای این کار وجود ندارد:
<meta name="theme-color" media="(prefers-color-scheme: light)" content="white">
<meta name="theme-color" media="(prefers-color-scheme: dark)" content="black">shortcuts
این فیلد شامل آرایه‌ای از میانبرها به قسمت‌های کلیدی وب‌اپلیکیشن است و با هدف ساده‌سازی دسترسی به آن بخش‌ها تعبیه گردیده است. آیتم‌های این آرایه اشیائی است که حداقل یک فیلد name و یک url را دارند.
برای اطلاعات بیشتر در مورد این ویژگی به لینک مقابل مراجعه کنید: //web.dev/app-shortcuts
description
این ویژگی هدف و کار برنامه را توضیح می‌دهد.
screenshots
آرایه‌ای از تصاویرِ قسمت‌های مختلف PWA است.
این تصاویر در مرورگر کروم باید ضوابط زیر را داشته باشند:
- طول و عرض تصاویر باید بین ۳۲۰px و ۳۸۴۰px باشد.
- نباید نسبت بین طول و عرض بیش از ۲٫۳ برابر باشد.
- نسبت طول و عرض همه‌ی تصاویر باید یکسان باشد.
- فرمت تصاویر فقط می‌تواند jpg یا png باشد.
در حال حاضر ویژگی screenshots و description فقط در مرورگر Chrome، و آن هم تنها در سیستم عامل Android پشتیبانی می‌شود، که در زمان نصب PWA به کاربر نمایش داده می‌شود.
آزمایش web app manifest
برای اینکه مطمئن شوید اعلامیه وب‌اپلیکیشن را به درستی نوشته اید، در DevTools مرورگر Chrome به سربرگ Application بروید.
این صفحه بسیاری از ویژگی‌های اعلامیه وب‌اپلیکیشن را به صورتی که برای آدمیزاد قابل فهم‌تر باشد نمایش می‌دهد، و برای اینکه مطمئن شوید url همه‌ی تصاویر درست است خیلی خوب است.
صفحه‌ی Splash در موبایل
زمانی که PWA بسته است و کاربر با کلیک روی آیکونش آن را باز می‌کند کمی طول می‌کشد تا بالا بیاید و محتوای صفحه را نمایش دهد. در این زمان مرورگر به جای نمایش یک صفحه‌ی سفید که باعث می‌شود کاربر خیال کند برنامه خراب شده است، صفحه‌ای را تحت عنوان Splash screen نمایش می‌دهد، تا اینکه یک چیزی در صفحه قابل نمایش باشد.
مرورگر کروم این صفحه را از روی ویژگی‌های زیر در اعلامیه وب‌اپلیکیشن می‌سازد:
namebackground_coloricons
توجه داشته باشید که background_color باید هم‌رنگ پس‌زمینه‌ی صفحه‌ی اصلی برنامه باشد، تا در انتقال از Splash screen به برنامه، رنگ کلّ صفحه دگرگون نشود.