如何提供您自己的应用内安装体验

许多浏览器允许您直接在其用户界面中启用和推广 Progressive Web App (PWA) 的安装。安装(有时以前称为“添加到主屏幕”)允许用户在其移动设备或桌面设备上安装您的 PWA。安装 PWA 会将其添加到用户的启动器,使其可以像任何其他已安装的应用一样运行。

除了浏览器提供的安装体验之外,您还可以直接在您的应用内提供您自己的自定义安装流程。

Install App button provided in the Spotify PWA
Spotify PWA 中提供的“安装应用”按钮。

在考虑是否推广安装时,请考虑用户通常如何使用您的 PWA。例如,如果有一部分用户每周多次使用您的 PWA,那么这些用户可能会从手机主屏幕或桌面操作系统中的“开始”菜单启动您的应用所带来的额外便利中受益。某些生产力和娱乐应用程序也受益于在已安装的 standaloneminimal-uiwindow-control-overlay 模式下,通过删除浏览器工具栏而创建的额外屏幕空间。

先决条件

在开始之前,请确保您的 PWA 符合可安装性要求,这些要求通常包括拥有Web 应用清单

推广安装

要显示您的 Progressive Web App 是可安装的,并提供自定义的应用内安装流程

  1. 监听 beforeinstallprompt 事件。
  2. 保存 beforeinstallprompt 事件,以便稍后可以触发安装流程。
  3. 提醒用户您的 PWA 是可安装的,并提供一个按钮或其他元素来启动应用内安装流程。

监听 beforeinstallprompt 事件

如果您的 Progressive Web App 符合要求的安装标准,浏览器将触发 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 属性是一个 Promise,它会使用用户的选择来解析。 您只能在延迟事件上调用 prompt() 一次。 如果用户关闭它,您需要等到 beforeinstallprompt 事件再次触发,通常是在 userChoice 属性解析后立即触发。

检测 PWA 何时成功安装

您可以使用 userChoice 属性来确定用户是否从您的用户界面内安装了您的应用。 但是,如果用户从地址栏或其他浏览器组件安装您的 PWA,userChoice 将不起作用。 相反,您应该监听 appinstalled 事件,无论使用何种机制安装 PWA,该事件都会在您的 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 如何处理 Web 应用清单的更新,以了解这些更改何时以及如何在 Chrome 中反映出来。