דף זה תורגם על ידי Cloud Translation API.

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

François Beaufort

Pete LePage

Thomas Steiner

Alexey Rodionov

תמיכה בדפדפנים

מקור

מניפסט של אפליקציית אינטרנט הוא קובץ JSON שמציין לדפדפן איך אפליקציית האינטרנט המתקדמת (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 יכול לקבל אחד מהערכים הבאים:

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

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

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

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

צילומי מסך של ממשק משתמש עשיר יותר של התקנה במחשבים ובניידים. — ממשק משתמש עשיר יותר להתקנה במחשב ובנייד.

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

אחרי שיוצרים את המניפסט, מוסיפים תג <link> לכל הדפים של אפליקציית האינטרנט המתקדמת. לדוגמה:

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

הבקשה למניפסט נשלחת ללא פרטי כניסה, גם אם הוא נמצא באותו דומיין. אם המניפסט מחייב פרטי כניסה, צריך לכלול את crossorigin="use-credentials" בתג המניפסט.

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

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

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

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

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

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

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

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

קריאה נוספת

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

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

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

מאפייני המניפסט העיקריים

short_name וגם name

icons

id

start_url

background_color

display

display_override

scope

theme_color

theme_color בשאילתות מדיה

shortcuts

description

screenshots