跳转到内容

Manifest 中的清单成员

related_applications 与 prefer_related_applications

发布于

有限可用不支持的浏览器: Chrome (Desktop)、Firefox (Desktop)、Firefox (Android)、Safari (macOS)、Safari (iOS)WICG 草案

清单成员 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 时,同一个调用还能 发现过时的原生应用。

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 条目对可安装性和安装提示没有任何影响。

规范

规范状态
Web 应用清单:related_applicationsWICG 草案
Manifest Incubations: prefer_related_applications memberWICG 草案
  • 图例
  • 支持
  • 部分支持
  • 需开启标志
  • 不支持
  • 未知
浏览器 / 平台支持版本置信度来源备注
Chrome (Desktop)#不支持—高来源1
Chrome (Android)#支持44高来源—
Edge (Desktop)#支持17高来源—
Firefox (Desktop)#不支持—高来源2
Firefox (Android)#不支持—高来源3
Safari (macOS)#不支持—高来源4
Safari (iOS)#不支持—高来源56
Samsung Internet#支持4.0高来源7
WebView (Android)#支持44高来源8

源数据: /compatibility/manifest-related-applications.json · 全球使用占比: 42 % (StatCounter 2026-09, CC BY-SA 4.0)

来源: 规范 · MDN · 最近核验 2026-10-03 · 置信度: 高 (由来源计算)