מניפסט של אפליקציית אינטרנט הוא קובץ JSON שמנחה את הדפדפן איך להתנהג ב-Progressive Web App (PWA) כשמתקינים אותה במחשב או במכשיר הנייד של המשתמש. לכל הפחות, קובץ מניפסט טיפוסי כולל:
- שם האפליקציה
- הסמלים שבהם צריך להשתמש באפליקציה
- כתובת ה-URL שאמורה להיפתח כשהאפליקציה מופעלת
יצירה של קובץ המניפסט
לקובץ המניפסט יכול להיות כל שם, אבל בדרך כלל השם שלו הוא manifest.json והוא מוצג מהשורש (הספרייה ברמה העליונה של האתר). לפי המפרט, הסיומת צריכה להיות .webmanifest, אבל כדאי להשתמש בקובצי JSON כדי שהמניפסטים יוכלו לקרוא בצורה ברורה יותר.
מניפסט טיפוסי נראה כך:
{
"short_name": "Weather",
"name": "Weather: Do I need an umbrella?",
"icons": [
{
"src": "/images/icons-vector.svg",
"type": "image/svg+xml",
"sizes": "512x512"
},
{
"src": "/images/icons-192.png",
"type": "image/png",
"sizes": "192x192"
},
{
"src": "/images/icons-512.png",
"type": "image/png",
"sizes": "512x512"
}
],
"id": "/?source=pwa",
"start_url": "/?source=pwa",
"background_color": "#3367D6",
"display": "standalone",
"scope": "/",
"theme_color": "#3367D6",
"shortcuts": [
{
"name": "How's the 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 the 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",
"form_factor": "narrow"
},
{
"src": "/images/screenshot2.jpg",
"type": "image/jpg",
"sizes": "720x540",
"form_factor": "wide"
}
]
}
מאפייני המניפסט העיקריים
short_name וגם name
יש לציין במניפסט לפחות אחד מתוך short_name או name. אם תספקו את שניהם, האפליקציה name תשמש להתקנה, ו-short_name בשימוש במסך הבית של המשתמש, במרכז האפליקציות או במקומות אחרים שבהם יש שטח מוגבל.
icons
כשמשתמש מתקין את ה-PWA, אפשר להגדיר קבוצת סמלים לשימוש בדפדפן במסך הבית, במרכז האפליקציות, במעבר בין המשימות, במסך הפתיחה ובמקומות אחרים.
המאפיין icons הוא מערך של אובייקטים מסוג תמונה. כל אובייקט צריך לכלול את src, את המאפיין sizes ואת type של התמונה. כדי להשתמש בסמלים שניתנים למיסוך, שלפעמים נקראים סמלים מותאמים ב-Android, צריך להוסיף את הערך "purpose": "any maskable" לנכס icon.
ב-Chromium, עליך לספק סמל בגודל 192x192 פיקסלים לפחות וסמל של 512x512 פיקסלים. אם תספקו רק את שני גודלי הסמלים האלה, Chrome ישנה את גודל הסמלים באופן אוטומטי כך שיתאימו למכשיר. אם אתם מעדיפים לשנות את קנה המידה של הסמלים שלכם ולהתאים אותם לפי שלמות הפיקסלים, עליכם להוסיף סמלים במרווחים של 48dp.
id
המאפיין id מאפשר להגדיר במפורש את המזהה שמשמש את האפליקציה. הוספת המאפיין id למניפסט מסירה את התלות ב-start_url או במיקום של המניפסט, ומאפשרת לעדכן אותם בעתיד. מידע נוסף זמין במאמר זיהוי ייחודי של PWA באמצעות הנכס של מזהה המניפסט של אפליקציית האינטרנט.
start_url
השדה start_url הוא מאפיין חובה. הוא מציין לדפדפן איפה האפליקציה צריכה להתחיל כשהיא מופעלת, ומונעת מהאפליקציה להתחיל לפעול בכל דף שהמשתמש היה בו כשהוסיף את האפליקציה למסך הבית שלו.
השדה start_url צריך להפנות את המשתמשים ישירות לאפליקציה, ולא לדף הנחיתה של המוצר. חשבו מה המשתמש ירצה לעשות מיד אחרי שהוא פותח את האפליקציה והצבו אותה שם.
background_color
נעשה שימוש במאפיין background_color במסך הפתיחה כשהאפליקציה מופעלת בנייד בפעם הראשונה.
display
ניתן להתאים אישית את ממשק המשתמש של הדפדפן שמוצג כשהאפליקציה מופעלת. לדוגמה, אפשר להסתיר את סרגל הכתובות ואת רכיבי ממשק המשתמש של הדפדפן. אפשר אפילו להגדיר הפעלה של משחקים במסך מלא. המאפיין display מקבל אחד מהערכים הבאים:
| מאפיין (property) | התנהגות |
|---|---|
fullscreen |
פתיחת אפליקציית האינטרנט ללא צורך בממשק משתמש של הדפדפן, והצגה של כל אזור התצוגה הזמין. |
standalone |
פתיחה של אפליקציית האינטרנט להיראות ולהרגיש כמו אפליקציה עצמאית. האפליקציה פועלת
בחלון נפרד, בנפרד מהדפדפן ומסתירה
רכיבים סטנדרטיים בממשק המשתמש של הדפדפן, כמו סרגל הכתובות.
|
minimal-ui |
המצב הזה דומה ל-standalone, אבל הוא מספק למשתמש קבוצה מינימלית של רכיבים בממשק המשתמש לשליטה בניווט, כמו הלחצנים 'הקודם' ו'טעינה מחדש'.
|
browser |
חוויית דפדפן רגילה. |
display_override
על מנת לבחור את אופן הצגת אפליקציית האינטרנט, צריך להגדיר מצב display במניפסט, כפי שהסברנו קודם. הדפדפנים לא חייבים לתמוך בכל מצבי התצוגה, אבל הם חייבים לתמוך בשרשרת החלופית המוגדרת לפי המפרט ("fullscreen" ← "standalone" ← "minimal-ui" ← "browser"). אם הם לא תומכים במצב מסוים, הם יחזרו למצב התצוגה הבא בשרשרת. במקרים נדירים, החלופות האלה עלולות לגרום לבעיות. לדוגמה, המפתח לא יכול לבקש "minimal-ui" בלי לאלץ אותו לחזור למצב התצוגה של "browser" כאשר אין תמיכה ב-"minimal-ui". בהתאם להתנהגות הנוכחית, גם אי אפשר להציג מצבי תצוגה חדשים באופן תואם לאחור, כי אין להם מקום בשרשרת החלופה.
אתם יכולים להגדיר רצף חלופי משלכם באמצעות הנכס display_override, שהדפדפן לוקח אותו בחשבון לפני הנכס display. הערך שלו הוא רצף של מחרוזות שנחשבות לפי הסדר שנקבע, והמערכת מחילה את מצב התצוגה הנתמך הראשון. אם אין תמיכה בשדה display, הדפדפן יחזור לבצע הערכה של השדה display. אם אין שדה display, הדפדפן יתעלם מ-display_override.
הדוגמה הבאה ממחישה איך להשתמש ב-display_override. הפרטים של "window-control-overlay" לא נכללים בדף הזה.
{
"display_override": ["window-control-overlay", "minimal-ui"],
"display": "standalone",
}
בזמן טעינת האפליקציה, הדפדפן ינסה להשתמש קודם ב-"window-control-overlay". אם האפשרות הזו לא זמינה, הערך יוחזר לערך "minimal-ui", ולאחר מכן
ל-"standalone" מהנכס display. אם אף אחת מהאפשרויות האלה לא זמינה, הדפדפן יחזור לשרשרת החלופית הרגילה.
scope
scope של האפליקציה הוא קבוצת כתובות ה-URL שהדפדפן מחשיב כחלק מהאפליקציה. scope שולט במבנה של כתובות ה-URL שכולל את כל נקודות הכניסה והיציאה לאפליקציה, והדפדפן משתמש בו כדי לקבוע מתי המשתמש יצא מהאפליקציה.
כמה הערות נוספות לגבי scope:
- אם לא כוללים
scopeבמניפסט, ברירת המחדל המשתמעת שלscopeהיא כתובת ה-URL להתחלה, אבל לאחר הסרה של שם הקובץ, השאילתה והקטע. - המאפיין
scopeיכול להיות נתיב יחסי (../), או כל נתיב ברמה גבוהה יותר (/) שמאפשר להגדיל את הכיסוי של הניווטים באפליקציית האינטרנט. - השדה
start_urlחייב להיכלל בהיקף. - הערך
start_urlהוא יחסי לנתיב שמוגדר במאפייןscope. start_urlשמתחיל ב-/יהיה תמיד השורש של המקור.
theme_color
השדה theme_color קובע את הצבע של סרגל הכלים, ואפשר לראות אותו בתצוגה המקדימה של האפליקציה במעבר בין המשימות. הערך של theme_color צריך להתאים לצבע העיצוב meta שצוין בכותרת המסמך.
theme_color בהתאמה אישית.
theme_color בשאילתות מדיה
אפשר לשנות את theme_color בשאילתת מדיה באמצעות המאפיין media של רכיב צבע העיצוב meta. לדוגמה, אפשר להגדיר צבע אחד למצב בהיר וצבע אחר למצב כהה באופן הזה. עם זאת, לא ניתן להגדיר את ההעדפות האלה במניפסט. למידע נוסף, קרא את הבעיה w3c/manifest#975 ב-GitHub.
<meta name="theme-color" media="(prefers-color-scheme: light)" content="white">
<meta name="theme-color" media="(prefers-color-scheme: dark)" content="black">
shortcuts
המאפיין shortcuts הוא מערך של אובייקטים של קיצורי דרך של אפליקציות שמספקים גישה מהירה למשימות עיקריות באפליקציה. כל חבר הוא מילון שמכיל לפחות name ו-url.
description
המאפיין description מתאר את מטרת האפליקציה.
ב-Chrome, אורך התיאור המקסימלי הוא 300 תווים בכל הפלטפורמות. אם התיאור ארוך יותר, הדפדפן יקצר אותו בעזרת תו שלוש נקודות. ב-Android, התיאור צריך גם לכלול שבע שורות טקסט לכל היותר.
screenshots
המאפיין screenshots הוא מערך של אובייקטים של תמונות שמייצגים את האפליקציה בתרחישי שימוש נפוצים. כל אובייקט צריך לכלול את src, את המאפיין sizes ואת type של התמונה. המאפיין form_factor הוא אופציונלי.
ניתן להגדיר אותה לערך "wide" לצילומי מסך שרלוונטיים למסכים רחבים בלבד, או ל-"narrow" לצילומי מסך צרים בלבד.
ב-Chrome, התמונה צריכה לעמוד בקריטריונים הבאים:
- הרוחב והגובה חייבים להיות לפחות 320 פיקסלים ולא יותר מ-3840 פיקסלים.
- המאפיין המקסימלי לא יכול להיות גדול מפי 2.3 מאורך המאפיין המינימלי.
- לכל צילומי המסך שתואמים לגורם הצורה המתאים צריך להיות אותו יחס גובה-רוחב.
- החל מ-Chrome 109, רק צילומי מסך שבהם
form_factorמוגדר ל-"wide"מוצגים במחשב.
- החל מ-Chrome 109, רק צילומי מסך שבהם
- החל מ-Chrome 109, המערכת מתעלמת מצילומי מסך שבהם
form_factorמוגדר ל-"wide". צילומי מסך בליform_factorעדיין מוצגים לצורך תאימות לאחור.
Chrome במחשב מציג לפחות צילום מסך אחד ועד שמונה צילומי מסך שעומדים בקריטריונים האלה. המערכת מתעלמת מהשאר.
Chrome ב-Android מציג לפחות צילום מסך אחד ועד חמישה צילומי מסך שעומדים בקריטריונים האלה. המערכת מתעלמת מהשאר.
הוספת המניפסט של אפליקציית האינטרנט לדפים שלך
אחרי יצירת המניפסט, צריך להוסיף את התג <link> לכל הדפים של Progressive Web App. לדוגמה:
<link rel="manifest" href="/manifest.json">
בדיקת המניפסט
כדי לוודא שהמניפסט מוגדר בצורה תקינה, צריך להשתמש בחלונית Manifest בחלונית Application ב-Chrome DevTools.
בחלונית הזו מוצגת גרסה של רבים ממאפייני המניפסט, שבודק אנושי יכול לקרוא, ומאפשרת לוודא שכל התמונות נטענות בצורה תקינה.
מסכי פתיחה בנייד
כשהאפליקציה נפתחת לראשונה בנייד, יכול להיות שייקח רגע עד שהדפדפן יתחיל לעבד את התוכן הראשוני ועד שהוא יתחיל לעבד את התוכן. במקום להציג מסך לבן שעלול לגרום למשתמש לחשוב שהאפליקציה לא פועלת, יוצג בדפדפן מסך פתיחה עד להצגת השקף הראשון.
Chrome יוצר באופן אוטומטי את מסך הפתיחה מהמקורות הבאים: name, background_color ו-icons שצוינו במניפסט. על מנת ליצור מעבר חלק ממסך הפתיחה לאפליקציה, עליכם לבחור background_color באותו צבע כמו בדף הטעינה.
Chrome בוחר את הסמל שהכי מתאים לרזולוציית המכשיר של מסכי הפתיחה. ברוב המקרים מספיק להציג סמלים בגודל 192px ו-512px, אבל תוכלו להוסיף סמלים נוספים כדי להתאים אותם.
קריאה נוספת
מידע נוסף על מאפיינים אחרים שאפשר להוסיף למניפסט של אפליקציית האינטרנט זמין במסמכי התיעוד של MDN Web App Manifest.