הוספת מניפסט של אפליקציית אינטרנט

François Beaufort

Pete LePage

Thomas Steiner

Alexey Rodionov

מניפסט של אפליקציית אינטרנט הוא קובץ JSON שמסביר לדפדפן איך ההתנהגות של Progressive Web App (PWA) אמורה לפעול כאשר היא מותקנת במחשב של המשתמש, או מהמכשיר הנייד. לכל הפחות, קובץ מניפסט טיפוסי כולל:

• שם האפליקציה
• הסמלים שהאפליקציה צריכה להשתמש בהם
• כתובת ה-URL שאמורה להיפתח כשהאפליקציה מופעלת

יצירה של קובץ המניפסט

קובץ המניפסט יכול להיות בכל שם, אבל בדרך כלל השם שלו הוא manifest.json וגם מוצג מהרמה הבסיסית (root) (הספרייה ברמה העליונה של האתר שלכם). המפרט מציע שהתוסף צריך להיות .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 לוקח לאחד את הערכים הבאים:

נכס	התנהגות
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_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 שמתחיל ב-/ תמיד יהיה הרמה הבסיסית (root).

theme_color

השדה theme_color קובע את הצבע של סרגל הכלים, והוא יכול לבוא לידי ביטוי את התצוגה המקדימה של האפליקציה בכלי למעבר בין משימות. הערך של theme_color צריך להתאים צבע עיצוב אחד (meta) צוין בכותרת המסמך.

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 פיקסלים לפחות, ולא יותר מ-3,840 פיקסלים.
• המאפיין המקסימלי לא יכול להיות גדול פי 2.3 מהאורך המינימלי המאפיין.
• כל צילומי המסך שתואמים לגורם הצורה המתאים חייבים להיות זהים יחס גובה-רוחב.
  • החל מגרסה 109 של Chrome, רק צילומי מסך שבהם form_factor מוגדר לערך "wide" מוצגות במחשב.
• החל מ-Chrome 109, צילומי מסך שבהם form_factor מוגדר ל-"wide" הם המערכת מתעלמת ממנו ב-Android. צילומי מסך בלי form_factor עדיין מוצגים עבור של תאימות לאחור.

Chrome במחשב מציג לפחות צילום מסך אחד, ולכל היותר שמונה צילומי מסך שעומדים קריטריונים אלה. המערכת מתעלמת מהשאר.

ב-Chrome ב-Android מוצג צילום מסך אחד לפחות, חמישה צילומי מסך שעומדים בתנאים קריטריונים אלה. המערכת מתעלמת מהשאר.

הוספת המניפסט של אפליקציית האינטרנט לדפים שלך

אחרי יצירת המניפסט, עליך להוסיף תג <link> לכל הדפים Progressive Web App. מוצרים לדוגמה:

<link rel="manifest" href="/manifest.json">

בדיקת המניפסט

כדי לוודא שהמניפסט מוגדר כראוי, משתמשים בחלונית מניפסט שנמצאת ב החלונית אפליקציה ב-Chrome DevTools.

בחלונית הזו מוצגת גרסה קריאה לאנשים של חלק גדול מקובצי המניפסט למאפיינים, ומאפשר לכם לוודא שכל התמונות נטענות כראוי.

מסכי פתיחה בנייד

כשהאפליקציה מופעלת בפעם הראשונה בנייד, ייתכן שיחלפו כמה רגעים עד שהדפדפן יחלוף כדי להתחיל ברינדור, ועל התוכן הראשוני להתחיל בעיבוד. במקום להציג מסך לבן שעלול לגרום למשתמש לחשוב שהאפליקציה לא פועלת, הדפדפן מציג מסך פתיחה עד לצביעה הראשונה.

Chrome יוצר את מסך הפתיחה באופן אוטומטי מ-name, background_color ו-icons שצוינו במניפסט. כדי ליצור החלקה לעבור ממסך הפתיחה לאפליקציה, להפוך background_color זהה לצבע של דף הטעינה.

Chrome בוחר את הסמל שהכי מתאים לרזולוציית המכשיר עבור מסכי פתיחה. ברוב המקרים מספיק לציין סמלים בגודל 192 פיקסלים ו-512 פיקסלים, אבל אפשר להוסיף סמלים נוספים להתאמה טובה יותר.

קריאה נוספת

מידע נוסף על נכסים אחרים שאפשר להוסיף למניפסט של אפליקציית האינטרנט זמין בכתובת מסמכי התיעוד של MDN Web App Manifest.