許多瀏覽器都可讓您直接在使用者介面中,啟用及宣傳漸進式網頁應用程式 (PWA) 的安裝程序。 安裝 (有時稱為「新增至主畫面」) 可讓使用者在行動裝置或電腦上安裝您的 PWA。安裝 PWA 後,系統會將 PWA 加入使用者的啟動器,這樣就能像任何其他已安裝的應用程式一樣執行。
除了瀏覽器提供的安裝體驗之外,您也可以直接在應用程式中提供自訂安裝流程。
考慮是否要宣傳安裝功能時,請考量使用者通常如何使用 PWA。舉例來說,如果有使用者在一週內多次使用您的 PWA,這些使用者可能會從從手機主畫面或電腦作業系統的「開始」選單啟動應用程式這項額外便利功能中受益。部分效率提升和娛樂應用程式可從已安裝的 standalone
、minimal-ui
或 window-control-overlay
模式的視窗中移除瀏覽器工具列,進而受益於額外的螢幕空間。
必要條件
開始前,請確認您的 PWA 符合可安裝性規定,通常包括具備網頁應用程式資訊清單。
升級安裝作業
如要顯示漸進式網頁應用程式可供安裝,並提供自訂的應用程式內安裝流程,請按照下列步驟操作:
- 監聽
beforeinstallprompt
事件。 - 儲存
beforeinstallprompt
事件,以便日後觸發安裝流程。 - 提醒使用者您的 PWA 可供安裝,並提供按鈕或其他元素,以便啟動應用程式內安裝流程。
監聽 beforeinstallprompt
事件
如果漸進式網頁應用程式符合必要的安裝標準,瀏覽器就會觸發 beforeinstallprompt
事件。儲存事件參照,並更新使用者介面,指出使用者可以安裝 PWA。
// Initialize deferredPrompt for use later to show browser install prompt.
let deferredPrompt;
window.addEventListener('beforeinstallprompt', (e) => {
// Prevent the mini-infobar from appearing on mobile
e.preventDefault();
// Stash the event so it can be triggered later.
deferredPrompt = e;
// Update UI notify the user they can install the PWA
showInstallPromotion();
// Optionally, send analytics event that PWA install promo was shown.
console.log(`'beforeinstallprompt' event was fired.`);
});
應用程式內安裝流程
如要提供應用程式內安裝功能,請提供按鈕或其他介面元素,讓使用者點按或輕觸安裝應用程式。當使用者點按或輕觸元素時,請針對已儲存的 beforeinstallprompt
事件 (儲存在 deferredPrompt
變數中) 呼叫 prompt()
。系統會顯示強制安裝對話方塊,要求使用者確認是否要安裝您的 PWA。
buttonInstall.addEventListener('click', async () => {
// Hide the app provided install promotion
hideInstallPromotion();
// Show the install prompt
deferredPrompt.prompt();
// Wait for the user to respond to the prompt
const { outcome } = await deferredPrompt.userChoice;
// Optionally, send analytics event with outcome of user choice
console.log(`User response to the install prompt: ${outcome}`);
// We've used the prompt and can't use it again, throw it away
deferredPrompt = null;
});
userChoice
屬性是可讓使用者自行選擇問題的保證。您只能對延遲事件呼叫 prompt()
一次。如果使用者關閉通知,您就需要等到 beforeinstallprompt
事件再次觸發後,通常會在 userChoice
屬性解決後立即執行。
偵測 PWA 安裝成功的時間
您可以使用 userChoice
屬性,判斷使用者是否透過使用者介面安裝您的應用程式。不過,如果使用者從網址列或其他瀏覽器元件安裝 PWA,userChoice
就無法派上用場。
相反地,您應該改為監聽 appinstalled
事件,這個事件會在安裝 PWA 時觸發,無論其使用哪種機制都能觸發。
window.addEventListener('appinstalled', () => {
// Hide the app-provided install promotion
hideInstallPromotion();
// Clear the deferredPrompt so it can be garbage collected
deferredPrompt = null;
// Optionally, send analytics event to indicate successful install
console.log('PWA was installed');
});
偵測 PWA 的啟動方式
CSS display-mode
媒體查詢會指出 PWA 的啟動方式 (瀏覽器分頁或已安裝的 PWA)。這樣就能根據應用程式啟動方式套用不同的樣式。舉例來說,您可以將其設為一律隱藏安裝按鈕,並在以已安裝 PWA 的形式啟動時提供返回按鈕。
追蹤 PWA 的啟動方式
如要追蹤使用者啟動 PWA 的方式,請使用 matchMedia()
測試 display-mode
媒體查詢。
function getPWADisplayMode() {
if (document.referrer.startsWith('android-app://'))
return 'twa';
if (window.matchMedia('(display-mode: browser)').matches)
return 'browser';
if (window.matchMedia('(display-mode: standalone)').matches || navigator.standalone)
return 'standalone';
if (window.matchMedia('(display-mode: minimal-ui)').matches)
return 'minimal-ui';
if (window.matchMedia('(display-mode: fullscreen)').matches)
return 'fullscreen';
if (window.matchMedia('(display-mode: window-controls-overlay)').matches)
return 'window-controls-overlay';
return 'unknown';
}
追蹤顯示模式變更
如要追蹤使用者是否在 browser
和其他顯示模式之間變更,請監聽 display-mode
媒體查詢的變更。
// Replace "standalone" with the display mode used in your manifest
window.matchMedia('(display-mode: standalone)').addEventListener('change', () => {
// Log display mode change to analytics
console.log('DISPLAY_MODE_CHANGED', getPWADisplayMode());
});
根據目前的顯示模式更新 UI
如要讓 PWA 在以已安裝的 PWA 形式啟動時套用不同的背景顏色,請使用條件式 CSS:
@media all and (display-mode: standalone) {
body {
background-color: yellow;
}
}
更新應用程式的圖示和名稱
如果需要更新應用程式名稱或提供新圖示,該怎麼辦? 如要瞭解 Chrome 會如何反映這些變更的時間和方式,請參閱 Chrome 如何處理網頁應用程式資訊清單的更新。