应用添加横幅
- 引导用户添加应用至主屏幕
- 引导用户安装原生应用
  - 显示原生应用安装横幅的条件

应用添加横幅

PWA 提供两种添加应用横幅的形式，分别实现引导用户添加 PWA 至桌面和引导用户下载原生应用的功能。本文将介绍应用安装横幅的实现及管理。

引导用户添加应用至主屏幕
引导用户安装原生应用

warn

注意

应用添加横幅功能目前仅有部分浏览器支持，具体支持情况可以查看 App Manifest 的相关统计。因此在开发应用时请做好功能降级工作。

引导用户添加应用至主屏幕

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

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

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

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

显示应用安装横幅的条件

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

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

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

应用安装横幅事件

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

warn

注意

这些事件接口仍处于 Working Draft 阶段，仅有部分浏览器支持。这也就意味着，即使支持弹出安装横幅的浏览器，也不一定支持应用安装横幅事件。想要进行完整的功能体验，建议使用 Chrome Beta for Android 浏览器进行测试。

判断用户是否安装此应用

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

例如：

window.addEventListener('beforeinstallprompt', function (e) {
    // beforeinstallprompt event fired
    e.userChoice.then(function (choiceResult) {
        if (choiceResult.outcome === 'dismissed') {
            console.log('用户取消安装应用');
        }
        else {
            console.log('用户安装了应用');
        }
    });
});

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

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

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

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

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

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

var deferredPrompt = null;
window.addEventListener('beforeinstallprompt', function (e) {
    // 将事件返回存储起来
    deferredPrompt = e;
    // 取消默认事件
    e.preventDefault();
    return false;
});
// 当按钮点击事件触发的时候，再去触发安装横幅的显示
button.addEventListener('click', function () {
    if (deferredPrompt != null) {
        // 异步触发横幅显示
        deferredPrompt.prompt();
        deferredPrompt = null;
    }
});

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

button.addEventListener('click', function () {
    if (deferredPrompt != null) {
        // 异步触发横幅显示
        deferredPrompt.prompt();
        // 检测用户的安装行为
        deferredPrompt.userChoice.then(function (choiceResult) {
            console.log(choiceResult.outcome);
        });
        deferredPrompt = null;
    }
});

更多关于 beforeinstallprompt 的介绍，请阅读 MDN Window.onbeforeinstallprompt

示例

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

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

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

注在测试的时候请留意安装横幅的触发条件。

示例项目结构如下：

|
|----index.html
|
|----manifest.json
|
|----sw.js // Service Worker

manifest.json 的配置如下：

{
    "short_name": "短名称",
    "name": "这是一个完整名称",
    "icon": [
        {
            "src": "../../images/logo-144x144.png",
            "type": "image/png",
            "sizes": "144x144"
        }
    ],
    "start_url": "./index.html"
}

对应的横幅显示如下图所示：

代码添加事件监听：

window.addEventListener('beforeinstallprompt', function (e) {
    e.userChoice.then(function (choiceResult) {
        alert(choiceResult.outcome);
    });
});

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

将事件监听更改如下：

var dfdPrompt = null;
var button = document.getElementById('btn');
window.addEventListener('beforeinstallprompt', function (e) {
    // 存储事件
    dfdPrompt = e;
    // 显示按钮
    button.style.display = 'block';
    // 阻止默认事件
    e.preventDefault();
    return false;
});
button.addEventListener('click', function (e) {
    if (dfdPrompt == null) {
        return;
    }
    // 通过按钮点击事件触发横幅显示
    dfdPrompt.prompt();
    // 监控用户的安装行为
    dfdPrompt.userChoice.then(function (choiceResult) {
        alert(choiceResult.outcome);
    });
    // 隐藏按钮
    button.style.display = 'none';
    dfdPrompt = null;
});

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

引导用户安装原生应用

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

显示原生应用安装横幅的条件

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

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

其中 related_applications 的定义如下：

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

AppInfo 的属性值包括：

platform:
{string} 应用平台
id:
{string} 应用id

例如：

"related_applications": [
    {
        "platform": "play",
        "id": "com.baidu.samples.apps.iosched"
    }
]

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

"prefer_related_applications": true