Progressive Web App Manifest 配置屬性、啟動和更新機制深入介紹

Web App 的 manifest 是一個 JSON 形式的配置檔，瀏覽器透過配置檔就會知道 Progressive Web App 該怎麼去安裝在用戶的電腦或手機裝置上，所以最基本的 manifest 會包含 App 的名稱、Icon、App 開啟時要顯示的 URL。

建立 manifest file

命名上其實沒有特別規定，但通常會是 manifest.json 並且放置在專案的根目錄，規格上的副檔名是有特別建議 .webmanifest 所以其實也可以，但 JSON 格式較容易廣泛的辨識和理解。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50

{
  "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"
    }
  ]
}

manifest 屬性 (Key manifest properties)

• name/short_name: 安裝後的 App 名稱 short_name 會用在顯示上有限制的地方
• icons: 主畫面或是任務切換時顯示
• start_url: App 開啟預設頁，須注意為相對路徑跟 manifest 位置相關，有填 Chrome 才會跳提示
• background_color: 在加入主畫面後，啟動時 splash screen 的背景主視覺，在還沒安裝前的網址列也會改變顏色
• display: 定義 App 開啟後的顯示方式目前有三種，各有細微差異 fullscreen、standalone、minimal-ui

short_name、name

兩個必須擇一填，若兩者都填

• short_name: 用在主畫面、啟動畫面或是其他顯示受限的地方
• name: 安裝時使用

background_color

啟動畫面的 splash screen 背景色

theme_color

網址列的顏色，注意要和 meta 中的顏色相同。

<meta name="theme-color" content="#3c553c" />

icons

當用戶安裝 PWA 的時候，我們可以預先提供一套不同解析度的 icon 給瀏覽器用在不同的位置，icons 是包含圖片物件的陣列，對 Chrome 來說, PWA 至少要提供 192x192 和 512x512 兩種解析度的 icon，剩下的情境 Chrome 會自動針對裝置做優化。

每一個圖片物件須包含以下屬性:

• src
• sizes
• type
• purpose: 選填，可填入 “any maskable”，在 Android 手機中可以發現 icon 會依照手機主題樣式變成圓形或其他形狀，所以 icon 在設計上可以特別注意。
  • https://web.dev/maskable-icon/

Photo Credit: https://web.dev/
透過開發者工具勾選 Show only the minimum safe area for maskable icons 來看現在的 Icon 是否 maskable

description

說明這個 App 的一些介紹。

screenshots

screenshots 是包含圖片物件的陣列, 就是 App 的使用說明截圖，description 和 screenshots 主要都是安裝相關訊息，所以目前只會用在 Android 上的 Chrome。

要滿足以下條件:

• 長寬介於 320px - 3840px
• 最大解析度不能超過最小的 2.3 倍
• 截圖要同樣的長寬比
• 僅支援 JPEG、PNG

display

透過這個屬性我們可以選擇 App 開啟後的介面，舉例來說我們可隱藏網址列使用全螢幕去操作，但並非所有的瀏覽器都完整支援，支援度會以下面的順序向下支援:

"fullscreen" → "standalone" → "minimal-ui" → "browser"

若想要跳過上面順序的某個階段，就需要透過 display_override 來蓋掉:

1
2
3
4

{
  "display_override": ["window-control-overlay", "minimal-ui"],
  "display": "standalone"
}

1. “window-control-overlay” (蓋掉)
2. “minimal-ui”
3. “standalone” (回到原來 display 設定的 standalone)
4. “minimal-ui”
5. “browser”

start_url

start_url 算是最重要的一個必填屬性，要告訴瀏覽器當 App 啟動時要顯示什麼畫面，避免 App 因為用戶是從其他頁面加入至主畫面導致啟動頁面是從其他頁面開始。start_url 就是用戶打開的第一個頁面，可以看成產品專用的到達頁面。所以也值得從用戶想要開啟 App 的原因去規劃 start_url 位置。

shortcuts

shortcuts 相對於 start_url 則可以看成其他常用的子功能，以訂票系統來說就可以分為餘票查詢、時刻查詢等子功能，透過捷徑的配置就能夠讓用戶透過子選單直接開啟 App 並且使用功能，目前的支援度如下

• Android (Chrome 84)
• Windows (Chrome 85 and Edge 85)
• Chrome OS (Chrome 92)

1. 長按 App 開啟選單

Photo Credit: https://web.dev/ >

2. 桌面版 App 按右鍵開啟選單

Photo Credit: https://web.dev/ >

如果對捷徑功能有興趣，可以試玩看看底下這個 App:

https://app-shortcuts.glitch.me/

驗證 manifest

透過開發者工具中的 Application Tab 可以輕鬆的察看是否我們的 manifest 有被正確的使用。

Photo Credit: https://web.dev/ >

Progressive Web App 啟動

要怎麼知道 Web App 是在 PWA 已經被安裝情況下被開啟的，靠 CSS 中有個 display-mode，不管透過 tab 或是安裝的情況下，去測試都可以看得出來。

• display-mode 搭配 matchMedia()
• navigator.standalone: 不支援 matchMedia() 就透過屬性直接判斷

1
2
3
4
5
6
7
8
9

function getPWADisplayMode() {
  const isStandalone = window.matchMedia("(display-mode: standalone)").matches;
  if (document.referrer.startsWith("android-app://")) {
    return "twa";
  } else if (navigator.standalone || isStandalone) {
    return "standalone";
  }
  return "browser";
}

偵測 display mode 改變

也是透過 matchMedia() 搭配 change 的事件，但還想不到什麼情境底下會發生。

1
2
3
4
5
6
7
8
9
10

window
  .matchMedia("(display-mode: standalone)")
  .addEventListener("change", (evt) => {
    let displayMode = "browser";
    if (evt.matches) {
      displayMode = "standalone";
    }
    // Log display mode change to analytics
    console.log("DISPLAY_MODE_CHANGED", displayMode);
  });

針對 display mode 改變 UI

最簡單就是透過 CSS 的 media query 條件設定:

1
2
3
4
5

@media all and (display-mode: standalone) {
  body {
    background-color: yellow;
  }
}

Progressive Web App 更新機制

當想要更新 App 的名稱或是 Icon 的時候，其實也是透過修改 manifest 配置檔。

Chrome 桌面版

以下屬性改變的時候，Chrome 會自動抓取新的 manifest 配置檔, Chrome 會把新的配置暫存，等到所有視窗關閉時會進行更新安裝。當安裝完成時，除了 name, short_name, start_url, icons 以外的欄位都會更新。

哪幾個欄位會觸發更新?

• display: manifest 的配置、使用者 window/browser tab setting 同時存在會以使用者為主
• scope
• shortcuts
• theme_color

測試 manifest 更新

• about://internals/web-app

Chrome Android 版

哪幾個欄位會觸發更新?

• background_color
• display
• orientation
• scope
• shortcuts
• start_url
• theme_color
• web_share_target

如果 Chrome 無法從伺服器取得更新版的 manifest，會延長到 30 才進行更新確認。

測試 manifest 更新

• about://webapks:　點選 “Update” 按鈕

• ← 上一篇
• 下一篇 →