应用添加横幅

    引导用户将 PWA 添加至主屏幕，可以给用户提供更好的应用体验，更为重要的是，添加至主屏幕后用户可以方便快捷地打开站点，既增加了站点访问量，同时也提高了用户粘性。

    如下图所示，打开浏览器菜单，会看到的功能，用户可以点击该选项手动将 PWA 站点添加至主屏幕。

    很明显对于大部分用户来说，都不会主动去完成上述操作，因此需要适时地弹出应用安装横幅去引导用户进行添加操作。PWA 提供的应用安装横幅如下图所示：

    应用安装横幅

    用户只需点击横幅上的添加应用按钮，即可将 PWA 添加到他们的主屏幕。相比起用户主动操作，弹出应用安装横幅的形式更直观，操作更简便，用户的应用添加率也会更高。

    浏览器在 PWA 站点满足以下条件时会自动显示横幅：

    • 站点部署 manifest.json，该文件需配置如下属性：
      • short_name （用于主屏幕显示）
      • （用于安装横幅显示）
      • icons （其中必须包含一个 mime 类型为 image/png 的图标声明）
      • （应用启动地址）
      • display （必须为 standalone 或 fullscreen）
    • 站点注册 Service Worker。
    • 站点支持 HTTPS 访问。
    • 站点在同一浏览器中被访问至少两次，两次访问间隔至少为 5 分钟。

    注 应用安装横幅是一种新兴的技术，对应的显示横幅的条件在将来可能会有所变化。

    浏览器会根据 manifest.json 提供的相关配置生成应用安装横幅，同时使用一组条件和访问频率启发式算法来确定何时显示横幅。一般来说，浏览器管理触发提示的时间，不一定满足网站需求，因此浏览器也提供了一些事件接口供网站开发者使用。

    warn

    注意

    判断用户是否安装此应用

    beforeinstallprompt 事件返回一个名为 userChoice 的 Promise 对象，并在当用户对横幅进行操作时进行解析。promise 会返回属性 outcome，该属性的值为 dismissed 或 accepted，如果用户将网页添加到主屏幕，则返回 accepted。

    例如：

    利用 userChoice 返回的 Promise 对象，可以根据用户的安装选择结果进行互动。

    取消或延迟安装横幅的触发事件

    网站虽然不能主动触发安装横幅的显示事件，但是当该事件被浏览器触发之后，可以对其进行取消或者延迟。

    通过阻止 beforeinstallprompt 事件的默认行为，即可取消横幅弹出：

    1. window.addEventListener('beforeinstallprompt', function (e) {
    2.     e.preventDefault();
    3.     return false;
    4. });

    beforeinstallprompt 事件返回一个名为 prompt 的方法，通过执行该方法可以触发安装横幅的显示。为了实现显示事件的延迟操作，可以将 beforeinstallprompt 事件的返回值给存储起来，再异步地调用 prompt()。

    1. var deferredPrompt = null;
    3. window.addEventListener('beforeinstallprompt', function (e) {
    4.     // 将事件返回存储起来
    5.     deferredPrompt = e;
    7.     // 取消默认事件
    8.     e.preventDefault();
    9.     return false;
    10. });
    12. button.addEventListener('click', function () {
    14.         // 异步触发横幅显示
    15.         deferredPrompt.prompt();
    16.         deferredPrompt = null;
    17.     }
    18. });

    通过 prompt() 触发显示的横幅，同样可以通过 userChoice 去监测用户的安装行为：

    更多关于 beforeinstallprompt 的介绍，请阅读

    本示例展示了添加到桌面横幅及其事件的捕获的一个简单流程。

    完整的项目代码可以戳这里。

    您可以使用支持添加到桌面的浏览器访问 测试浏览器弹出添加到桌面的功能，也可以使用 Chrome Beta for Android 直接访问 添加到桌面横幅事件拦截示例 进行测试。

    注 在测试的时候请留意安装横幅的。

    示例项目结构如下：

    1. |
    2. |----index.html
    3. |
    4. |----manifest.json
    5. |
    6. |----sw.js // Service Worker

    manifest.json 的配置如下：

    1. {
    2.     "short_name": "短名称",
    3.     "name": "这是一个完整名称",
    4.     "icon": [
    5.         {
    6.             "src": "../../images/logo-144x144.png",
    7.             "type": "image/png",
    8.             "sizes": "144x144"
    9.         }
    10.     ],
    11.     "start_url": "./index.html"
    12. }

    代码添加事件监听：

    则点击添加效果如下图所示：

    点击添加效果

    将事件监听更改如下：

    1. var dfdPrompt = null;
    2. var button = document.getElementById('btn');
    4. window.addEventListener('beforeinstallprompt', function (e) {
    5.     // 存储事件
    6.     dfdPrompt = e;
    7.     // 显示按钮
    8.     button.style.display = 'block';
    10.     return false;
    11. });
    13. button.addEventListener('click', function (e) {
    14.     if (dfdPrompt == null) {
    15.         return;
    16.     }
    17.     // 通过按钮点击事件触发横幅显示
    18.     dfdPrompt.prompt();
    19.     // 监控用户的安装行为
    20.     dfdPrompt.userChoice.then(function (choiceResult) {
    21.         alert(choiceResult.outcome);
    22.     });
    23.     // 隐藏按钮
    24.     button.style.display = 'none';
    25.     dfdPrompt = null;
    26. });

    当浏览器触发横幅显示事件时，页面中的按钮将显示出来，同时横幅显示事件被取消；点击按钮时，应用安装横幅才会显示出来：

    2. 浏览器触发横幅显示事件时页面截图

    4. 点击添加到主屏幕触发监听事件

    引导用户安装原生应用

    PWA 站点允许定义类似应用安装横幅的形式去推广原生应用。

    浏览器在 PWA 站点满足以下条件时会自动显示横幅：

    • 站点部署 manifest.json，该文件需配置如下属性：
      • （用于主屏幕显示）
      • name （用于安装横幅显示）
      • （其中必须包含一个 192x192 且 mime 类型为 image/png 的图标声明）
      • 包含原生应用相关信息的 related_applications 对象
    • 站点注册 Service Worker。
    • 站点支持 HTTPS 访问。
    • 站点在同一浏览器中被访问至少两次，两次访问间隔至少为 2 天。

    其中 related_applications 的定义如下：

    • related_applications:
      Array.<AppInfo> 关联应用列表

    AppInfo 的属性值包括：

    • platform:
      {string} 应用平台
    • id:
      {string} 应用id
    1. "related_applications": [
    2.     {
    3.         "platform": "play",
    4.         "id": "com.baidu.samples.apps.iosched"
    5.     }

    如果只希望用户安装原生应用，而不需要弹出横幅引导用户安装 PWA，那么可以在 manifest.json 设置：