Manifest 中的清单成员
related_applications 与 prefer_related_applications
发布于
清单成员 related_applications 列出 Web 应用对应的原生应用或 Web 版本。它是对象数组,每项包含 platform,以及商店 url 或 id。prefer_related_applications 是布尔提示,告诉浏览器可以推荐其中一个对应应用,
而不是提议安装 Web 应用本身。navigator.getInstalledRelatedApps() 在运行时读取的也是同一个数组。
Android 上的 Chrome 44、Samsung Internet 4.0、Android WebView 44 与 Edge 17 处理这两个成员(BCD
manifests.webapp.related_applications)。桌面端 Chrome 在 Windows 上为 getInstalledRelatedApps()
读取数组,并在 prefer_related_applications 为 true 时报告可安装性错误。BCD 记录 Firefox 与
Safari 均不支持,并注明在 Android 版 Firefox 上该属性会被解析但没有效果。
| 属性 | 值 |
|---|---|
| 类型 | related_applications 是对象数组,字段有 platform(字符串,必填)、url(字符串)、id(字符串)、min_version(字符串)与 fingerprints({ type, value } 数组)。url 与 id 至少要有一个。prefer_related_applications 是布尔值。 |
允许的 platform 值 |
play(Google Play)、itunes(App Store)、windows(Microsoft Store)、chrome_web_store、f-droid、amazon,以及 webapp(以清单 id 标识的 PWA)。 |
| 默认值 | 空数组,以及 false。省略 prefer_related_applications 等同于写 false。 |
| 示例值 | [{ "platform": "play", "id": "com.example.app" }] 搭配 "prefer_related_applications": true。 |
Chromium 逐条校验:缺少 platform 的条目记录
'platform' is a required field, related application ignored.,既没有 url 也没有 id 的条目记录
one of 'url' or 'id' is required, related application ignored.。Chromium 静默跳过非对象条目,保留符合这些检查要求的条目。这种关系是单向的:原生应用不需要反过来指向 Web 应用,唯一的
例外是 getInstalledRelatedApps(),它在 Android 上会先核验 Play 应用的 Digital Asset Links 声明,
再报告其已安装(Digital Asset Links,developers.google.com)。
在 Chromium 里,prefer_related_applications: true 会让可安装性检查报告 Manifest specifies prefer_related_applications: true。Chromium 的日志文件还定义了一个独立的错误
prefer_related_applications is only supported on Chrome Beta and Stable channels on Android,用于不符合条件的渠道。
先在清单中声明对应应用,再在运行时查询数组。
指向 Play 商店应用与 Microsoft Store 页面
链接到“指向 Play 商店应用与 Microsoft Store 页面”一节Web 应用如果有对应的原生应用,可以同时列出两个商店版本。Play 条目以包名作 id、以商店页面作 url;Microsoft
Store 条目只有 url。省略 prefer_related_applications 时,这个列表不会阻断可安装性,
getInstalledRelatedApps() 会读取它。
{ "name": "Trail Maps", "start_url": "/", "display": "standalone", "related_applications": [ { "platform": "play", "url": "https://play.google.com/store/apps/details?id=com.example.trailmaps", "id": "com.example.trailmaps" }, { "platform": "windows", "url": "https://apps.microsoft.com/store/detail/trail-maps/9WZDNCRFHVJL" } ]}只有希望浏览器优先推荐原生应用而不是 Web 应用时才加 "prefer_related_applications": true;它为 true 期间,Chromium 的可安装性检查会报告错误。
原生应用已安装时隐藏安装按钮
链接到“原生应用已安装时隐藏安装按钮”一节navigator.getInstalledRelatedApps() 以数组中已安装在本设备上的条目兑现(Android 上的 Chrome 80;
Windows 上的 Chrome 85 支持 windows 条目)。它只能在应用自身源的顶层框架中调用,且 Play 应用必须
为该源发布 Digital Asset Links 声明。回退分支为没有该方法的浏览器保留按钮。
async function nativeAppInstalled() { if (typeof navigator.getInstalledRelatedApps !== 'function') { return false; // Safari、Firefox、iOS 版 Chrome:展示 Web 安装路径 } try { const apps = await navigator.getInstalledRelatedApps(); return apps.some((app) => app.platform === 'play' || app.platform === 'windows'); } catch { return false; // 不在顶层框架,或 asset links 校验未通过 }}
nativeAppInstalled().then((installed) => { document.querySelector('#install-web-app').hidden = installed;});兑现的对象带有 platform、url、id 与 version,所以设置了 min_version 时,同一个调用还能
发现过时的原生应用。
检测 PWA 自身是否已经安装
链接到“检测 PWA 自身是否已经安装”一节id 等于清单自身 id 的 webapp 条目,让在浏览器标签页里打开的站点能询问本设备是否已安装它的
PWA。Chrome 85 及之后会兑现这一查询;其他浏览器落到 display-mode 检查,而后者只知道当前窗口的
情况。
{ "id": "/", "related_applications": [ { "platform": "webapp", "url": "https://trailmaps.example/manifest.webmanifest" } ]}async function pwaInstalled() { if (matchMedia('(display-mode: standalone)').matches) return true; // 正以应用形式运行 if (typeof navigator.getInstalledRelatedApps !== 'function') return false; const apps = await navigator.getInstalledRelatedApps(); return apps.some((app) => app.platform === 'webapp');}根据返回结果,把“安装”按钮改成“打开应用”;webapp 条目对可安装性和安装提示没有任何影响。
另请参阅
链接到“另请参阅”一节- getInstalledRelatedApps():检测已安装的原生或 PWA 对应应用
- id 清单成员
- 可安装性条件:PWA 如何才能被安装
- Trusted Web Activity(TWA):PWA 进入 Play 商店
- Manifest Incubations: related_applications member(wicg.github.io)
- Navigator: getInstalledRelatedApps() method(developer.mozilla.org)
规范
| 规范 | 状态 |
|---|---|
| Web 应用清单:related_applications | WICG 草案 |
| Manifest Incubations: prefer_related_applications member | WICG 草案 |