###### tags: `PWA`

# [Installation prompt](https://web.dev/learn/pwa/installation-prompt/)安裝提示

For sites that pass the PWA install criteria, the browser triggers an event to prompt the user to install it. The good news is that you can use this event to customize your prompt and invite users to install your app.

對於通過 PWA 安裝標準的網站，瀏覽器會觸發一個事件來提示用戶安裝它。好消息是您可以使用此事件來自定義您的提示並邀請用戶安裝您的應用程序。

Users may not be familiar with the PWA install process. As the developer, you will understand when it is the right time to invite the user to install the app. The default browser installation prompts can also be enhanced. Let's check out the tools available.

用戶可能不熟悉 PWA 安裝過程。作為開發者，您會明白什麼時候是邀請用戶安裝應用程序的合適時機。還可以增強默認瀏覽器安裝提示。讓我們檢查一下可用的工具。

## Enhancing the install dialog 增強安裝對話框

Browsers provide default installation prompts when PWAs pass the install criteria. The browser uses the <kbd> name </kbd> and <kbd> icons </kbd> properties from your [Web App Manifest](https://web.dev/learn/pwa/web-app-manifest/) to build the prompt.

當 PWA 通過安裝標準時，瀏覽器會提供默認安裝提示。瀏覽器使用 Web 應用程序清單中的名稱和圖標屬性來構建提示。


Some browsers enhance the installation prompt experience using the [promotional fields](https://web.dev/learn/pwa/web-app-manifest/#promotional-fields) in the manifest, including <kbd> description </kbd> ,<kbd> categories </kbd> , and <kbd> screenshots </kbd> . For example, using Chrome on Android, if your PWA provides values for the <kbd> description </kbd> and <kbd> screenshots </kbd> fields, the installation dialog experience transforms from a small **Add to home screen** info bar to a bigger, more detailed dialog, similar to the install prompts from an app store.

一些瀏覽器使用清單中的促銷字段來增強安裝提示體驗，包括描述、類別和屏幕截圖。例如，在 Android 上使用 Chrome，如果您的 PWA 為描述和屏幕截圖字段提供值，則安裝對話框體驗會從一個小的“添加到主屏幕”信息欄轉變為一個更大、更詳細的對話框，類似於來自應用程序的安裝提示店鋪。


See promotional fields in action:查看實際的促銷字段：


[learn-pwa-web-app-manifest-promotional](https://glitch.com/~learn-pwa-web-app-manifest-promotional)

## The beforeinstallprompt event 在安裝提示前事件

The browser's installation prompts are the first step in getting users to install your PWA. To implement your own install experience, your app still needs to pass the install criteria: when the browser detects that your app is installable, it fires the beforeinstallprompt event. You need to implement this event handler to customize the user's experience. Here's how:

瀏覽器的安裝提示是讓用戶安裝你的 PWA 的第一步。要實現您自己的安裝體驗，您的應用仍需要通過安裝標準：當瀏覽器檢測到您的應用可安裝時，它會觸發 beforeinstallprompt 事件。您需要實施此事件處理程序來自定義用戶體驗。這是如何做：

1. Listen for the beforeinstallprompt event.
1. Save it (you'll need it later).
1. Trigger it from your UI.
<!-- -->

1. 監聽 beforeinstallprompt 事件。
2. 保存它（稍後你會需要它）。
3. 從您的用戶界面觸發它。

<div style="padding:1rem;background-color:#fff5e3;margin-bottom:1.5em">

<div style="display:flex;color:#c34900">

:warning:
<p style="color:#c34900;margin-top:-1.5em">
Caution
</p>
</div>

<p style="color:#c34900;">
all browsers support this event, and it has been moved from the Web App Manifest spec to a [separate incubator](https://wicg.github.io/manifest-incubations/) .
</p>

</div>

<div style="padding:1rem;background-color:#fff5e3;margin-bottom:1.5em">

<div style="display:flex">

:warning:
<p style="color:#c34900;margin-top:-1.5em">
Caution警告
</p>
</div>

<p style="color:#c34900;">
所有瀏覽器都支持此事件，並且它已從 Web App Manifest 規範移至單獨的孵化器。
</p>

</div>

Check the code below for an example of an event listener for the <kbd> beforeinstallprompt </kbd> event, its capture and later custom use.
查看下面的代碼，了解 beforeinstallprompt 事件的事件偵聽器示例、它的捕獲和稍後的自定義使用。

// This variable will save the event for later use.
let deferredPrompt;
window.addEventListener('beforeinstallprompt', (e) => {
  // Prevents the default mini-infobar or install dialog from appearing on mobile
  e.preventDefault();
  // Save the event because you'll need to trigger it later.
  deferredPrompt = e;
  // Show your customized install prompt for your PWA
  // Your own UI doesn't have to be a single element, you
  // can have buttons in different locations, or wait to prompt
  // as part of a critical journey.
  showInAppInstallPromotion();
});

Then, if the user clicks on your customized install button, use the <kbd> deferredPrompt </kbd> that has previously been saved and call its <kbd> prompt() </kbd> method, because the user still needs to go through the browser's process to install your app. What you did was delay the event until you gave the user the right context to encourage them to install the PWA.
然後，如果用戶點擊你定制的安裝按鈕，使用之前保存的 deferredPrompt 並調用它的 prompt() 方法，因為用戶仍然需要通過瀏覽器的過程來安裝你的應用程序。您所做的是延遲事件，直到您為用戶提供正確的上下文以鼓勵他們安裝 PWA。

Capturing the event gives you the opportunity to add hints and incentives for your users to install your app, and to choose to prompt for installation when you know the users are more engaged.
捕獲事件讓您有機會為用戶添加提示和激勵以安裝您的應用程序，並在您知道用戶參與度更高時選擇提示安裝。

<div style="padding:1rem;background-color:#fff5e3;margin-bottom:1.5em">

<div style="display:flex">

:warning:
<p style="color:#c34900;margin-top:-1.5em">
Caution
</p>
</div>

<p style="color:#c34900;">

You can only call <kbd> prompt() </kbd> on the deferred event once. If the user dismisses it, you need to wait until the <kbd> beforeinstallprompt </kbd> event is fired again.
</p>

</div>
<div style="padding:1rem;background-color:#fff5e3;margin-bottom:1.5em">

<div style="display:flex">

:warning:
<p style="color:#c34900;margin-top:-1.5em">
Caution警告
</p>
</div>

<p style="color:#c34900;">

您只能對延遲事件調用 prompt() 一次。如果用戶關閉它，則需要等到再次觸發 beforeinstallprompt 事件。
</p>

</div>

The event will not fire if:

* The user has already installed the current PWA (valid only for desktop and WebAPK on Android).
* The app does not pass the [PWA installation criteria](https://web.dev/learn/pwa/installation/#installation-criteria).
* The PWA is not installable on the current device for other reasons (for example, a device in kiosk mode or without permissions).

如果出現以下情況，事件將不會觸發：

* 用戶已經安裝了當前的 PWA（僅對桌面和 Android 上的 WebAPK 有效）。
* 該應用未通過 PWA 安裝標準。
* 由於其他原因（例如，設備處於 kiosk 模式或沒有權限），PWA 無法安裝在當前設備上。

<div style="padding:1rem;background-color:#faf6fe;color:#6001ff;">

<span style="display:flex">

:bulb:
<p style="color:#6001ff;margin-top:-1.5em">
Gotchas
</p>
</span>

<p style="color:#6001ff;">

Chrome and Edge on iOS and iPadOS do not support PWA installation, so the <kbd> beforeinstallprompt </kbd> event can't fire. In this case, the only option is to open the PWA using Safari, where it is installable from the [share, add to the home screen menu.](https://web.dev/learn/pwa/installation/#installation-criteria)

</p>

</div>

<div style="padding:1rem;background-color:#faf6fe;color:#6001ff;margin-top:2rem">

<span style="display:flex">

:bulb:
<p style="color:#6001ff;margin-top:-1.5em">
Gotchas 陷阱
</p>
</span>

<p style="color:#6001ff;">

iOS 和 iPadOS 上的 Chrome 和 Edge 不支持 PWA 安裝，因此無法觸發 beforeinstallprompt 事件。在這種情況下，唯一的選擇是使用 Safari 打開 PWA，它可以從共享中安裝，添加到主屏幕菜單。

</p>

</div>

## The best place to prompt 提示的最佳位置

Where to prompt depends on your application and when your users are most engaged with your content and services. When you capture the <kbd> beforeinstallprompt </kbd> , you can guide users through the reasons to keep using your app and the advantages they will gain from installing it. You can choose to display install hints anywhere in your app. Some common patterns are: in the side menu, after a critical user journey such as completing an order, or after a sign-up page. You can read more about this in Patterns for [promoting PWA installation](https://web.dev/promote-install/).

在何處提示取決於您的應用程序以及您的用戶何時最關注您的內容和服務。當您捕獲 beforeinstallprompt 時，您可以引導用戶了解繼續使用您的應用程序的原因以及安裝它後他們將獲得的優勢。您可以選擇在應用程序的任何位置顯示安裝提示。一些常見的模式是：在側邊菜單中，在完成訂單等關鍵用戶旅程之後，或在註冊頁面之後。您可以在促進 PWA 安裝的模式中閱讀更多相關信息。

## Gathering analytics收集分析

Using analytics will help you to understand better where and when to present your prompts. You can use the <kbd> userChoice </kbd> property from the <kbd> beforeinstallprompt </kbd> event; <kbd> userChoice </kbd> is a promise that will resolve with the action the user took.

使用分析將幫助您更好地了解何時何地呈現您的提示。您可以使用 beforeinstallprompt 事件中的 userChoice 屬性； userChoice 是一個承諾，它將隨著用戶採取的行動而解決。

// Gather the data from your custom install UI event listener
installButton.addEventListener('click', async () => {
  // deferredPrompt is a global variable we've been using in the sample to capture the `beforeinstallevent`
  deferredPrompt.prompt();
  // Find out whether the user confirmed the installation or not
  const { outcome } = await deferredPrompt.userChoice;
  // The deferredPrompt can only be used once.
  deferredPrompt = null;
  // Act on the user's choice
  if (outcome === 'accepted') {
    console.log('User accepted the install prompt.');
  } else if (outcome === 'dismissed') {
    console.log('User dismissed the install prompt');
  }
});

<div style="background-color:#D2DEF9;padding:1rem;line-height:1.9">

Chromium browsers trigger the <kbd> [appinstalled](https://developer.mozilla.org/zh-CN/docs/Web/API/Window/appinstalled_event) </kbd> event on the window object. The event is fired when the user accepts the install, whether action was triggered by a custom install button or by the browser.

</div>

<div style="background-color:#D2DEF9;padding:1rem;line-height:1.9;margin-top:2rem">

Chromium 瀏覽器觸發 window 對像上的 appinstalled 事件。當用戶接受安裝時會觸發該事件，無論操作是由自定義安裝按鈕還是由瀏覽器觸發。

</div>

## See it in action 看看它的實際效果

Try the following sample in action on a Chromium browser (desktop or Android).在 Chromium 瀏覽器（桌面或 Android）上嘗試以下示例。


### [Installation Prompt Demo](https://glitch.com/~mlearn-pwa-web-app-install-prompt)

## Fallback 倒退

If the browser doesn't support the <kbd> beforeinstallprompt </kbd> or the event does not fire, there is no other way to trigger the browser's installation prompt. However, on platforms that allow the user to install PWAs manually, like iOS, you can display these instructions to the user.

如果瀏覽器不支持 beforeinstallprompt 或者事件沒有觸發，則沒有其他方法可以觸發瀏覽器的安裝提示。但是，在允許用戶手動安裝 PWA 的平台上，例如 iOS，您可以向用戶顯示這些說明。

You should only render these instructions in browser mode; other display options, such as <kbd> standalone </kbd> or
<kbd>fullscreen </kbd>mean the user has already installed the app.

To render the element only in browser mode, use the display-mode media query:

您應該只在瀏覽器模式下呈現這些說明；其他顯示選項，例如獨立或
全屏意味著用戶已經安裝了該應用程序。

要僅在瀏覽器模式下呈現元素，請使用顯示模式媒體查詢：

#installInstructions {
   display: none
}
@media (display-mode: browser) {
   #installInstructions {
     display: block
   }
}

## Codelab

<div style="background-color:#f4fcfe;padding:1rem;line-height:1.9;color:#007b83">

<>Try it

Try it yourself with the Make it installable codelab.

</div>

<div style="background-color:#f4fcfe;padding:1rem;line-height:1.9;color:#007b83;margin-top:2rem">

<>Try it

使用 Make it installable codelab 親自嘗試。

</div>

## Libraries

Check out these libraries for help with rendering a custom install prompt:

[PWA Builder](https://github.com/pwa-builder/pwa-install)
[PWA Installer Prompt for React](https://github.com/shnaveen25/react-pwa-installer-prompt)
[React PWA Install](https://www.npmjs.com/package/react-pwa-install)
[Vue PWA Install](https://github.com/Bartozzz/vue-pwa-install)
[Add to Home Screen](https://github.com/docluv/add-to-homescreen)

## Resources

[Patterns for Promoting PWA installation](https://web.dev/promote-install/)
[How to provide your own in-app install experience](https://web.dev/customize-install/)
[MDN: Add to Home Screen](https://developer.mozilla.org/zh-CN/docs/Web/Progressive_web_apps/Add_to_home_screen)
[Web Manifest Incubations](https://wicg.github.io/manifest-incubations/)