Manifest 中的清单成员
start_url 清单成员
发布于 更新于
清单成员 start_url 指定用户点击图标时已安装应用打开的 URL,让你单独设置启动页,不受安装时所在页面影响。
它相对清单 URL 解析,必须与链接该清单的文档同源;声明的 scope 若不包含它,这个 scope 会被忽略。没有 id 时,浏览器还用它确定应用身份。
提供安装入口的引擎会读取它:Chrome 39、Edge 79、Samsung Internet 4.0、Android 上的 Firefox 79、
iOS 上的 Safari 11.3 与 macOS 上的 Safari 17(BCD manifests.webapp.start_url)。Chromium 还把有效的
start_url 作为可安装性的必要条件。
| 属性 | 值 |
|---|---|
| 类型 | 字符串,按相对清单 URL 的 URL 解析。 |
| 默认值 | 链接该清单的文档 URL。Chromium 丢弃跨源值时也回退到该文档 URL,并提示 property 'start_url' ignored, should be same origin as document.(manifest_parser.cc)。 |
| 示例值 | "/app/?utm_source=homescreen"。 |
如果 start_url 不在声明的 scope 内,Chromium 保留 start_url
而丢弃 scope,记录 property 'scope' ignored. Start url should be within scope of scope URL.,
应用随即静默得到默认作用域(去掉文件名、查询串和片段的启动 URL)。另外,处理后的 id 默认取去掉片段的
start_url(查询串保留),所以在从未设置 id 的应用上改动 start_url 的路径,清单的身份就变了,
浏览器会把它当作新的 PWA,已安装的那个不会被更新(Chrome for Developers,“Uniquely identify PWAs with the web app manifest id property”)。
启动 URL 提供默认入口。通知点击、shortcuts、share_target 和 file_handlers 都可能打开作用域内的其他
URL,所以这些路由也应该支持冷启动。
示例使用同一份由 https://app.example/manifest.webmanifest 提供的清单。
解析到同一启动页的相对与绝对写法
链接到“解析到同一启动页的相对与绝对写法”一节相对值相对清单 URL 解析,而不是相对链接它的页面。位于 /manifest.webmanifest 的清单写
"start_url": "app/",启动的是 https://app.example/app/,与绝对写法相同。
{ "start_url": "app/", "scope": "/app/"}绝对写法 "https://app.example/app/" 与之等价。浏览器会丢弃 "https://cdn.example/app/" 等跨源值,
改用文档 URL。
给启动打分析标记并在启动时读取
链接到“给启动打分析标记并在启动时读取”一节没有专用 API 时,start_url 上的查询串是区分已安装应用启动与浏览器访问的简便办法,不过任何人也可以在标签页里打开带标记的 URL。脚本读一次参数、
上报,然后把它从地址里删掉,刷新或复制链接就不会再算成一次启动;参数不存在时什么也不发。
{ "start_url": "/app/?utm_source=homescreen&utm_medium=pwa"}const params = new URLSearchParams(location.search);if (params.get('utm_source') === 'homescreen') { navigator.sendBeacon('/analytics', JSON.stringify({ launch: 'installed-app' })); params.delete('utm_source'); params.delete('utm_medium'); history.replaceState(history.state, '', `${location.pathname}${params.size ? `?${params}` : ''}`);}start_url 变化(包括查询串)是让 Chrome 把新清单排入更新队列的条件之一(web.dev,“How Chrome handles updates to the web
app manifest”)。清单 24 小时内没检查过时,启动时会触发检查;桌面版 Chrome 在应用的所有窗口关闭后才安装更新,
而且 start_url 的变化要求设置了 id。
迁移启动页而不产生第二个安装
链接到“迁移启动页而不产生第二个安装”一节在已上线应用上改动 start_url 之前,先把 id 固定为浏览器已经推导出的值,也就是 DevTools 里的 Computed App Id(去掉片段的旧 start_url,查询串保留)。
有了 id,新的 start_url 作为更新应用;没有它,Chromium 会把清单当作另一个应用。这里旧的 start_url 是 /app/。
{ "id": "/app/", "start_url": "/app/home/?utm_source=homescreen", "scope": "/app/"}id 一旦设定,只要源不变,start_url 就可以随意改动(Chrome for Developers)。
另请参阅
链接到“另请参阅”一节- id 清单成员
- scope 清单成员
- 已安装的 PWA 如何获取清单更新
- 可安装性条件:PWA 如何才能被安装
- Web Application Manifest: start_url member(w3.org)
- Uniquely identify PWAs with the web app manifest id property(developer.chrome.com)
规范
| 规范 | 状态 |
|---|---|
| Web 应用清单:start_url | W3C |
- 图例
- 支持
- 部分支持
- 需开启标志
- 不支持
- 未知
| 浏览器 / 平台 | 支持 | 版本 | 置信度 | 来源 | 备注 |
|---|---|---|---|---|---|
| Chrome (Desktop)# | 支持 | 39 | 高 | 来源 | 1 |
| Chrome (Android)# | 支持 | 39 | 高 | 来源 | 23 |
| Edge (Desktop)# | 支持 | 79 | 高 | 来源 | 45 |
| Firefox (Desktop)# | 不支持 | — | 高 | 来源 | 6 |
| Firefox (Android)# | 支持 | 79 | 高 | 来源 | — |
| Safari (macOS)# | 支持 | 17 | 高 | 来源 | — |
| Safari (iOS)# | 支持 | 11.3 | 高 | 来源 | — |
| Samsung Internet# | 支持 | 4.0 | 高 | 来源 | 78 |
| WebView (Android)# | 支持 | 39 | 高 | 来源 | 910 |
- Web 应用可安装的前提是提供 `start_url`。
- Web 应用可安装的前提是提供 `start_url`。
- 由 browser-compat-data 镜像自 Chrome 的数据推导。
- Web 应用可安装的前提是提供 `start_url`。
- 由 browser-compat-data 镜像自 Chrome 的数据推导。
- browser-compat-data 未记录 Firefox 的支持。
- Web 应用可安装的前提是提供 `start_url`。
- 由 browser-compat-data 镜像自 Chrome Android 的数据推导。
- Web 应用可安装的前提是提供 `start_url`。
- 由 browser-compat-data 镜像自 Chrome Android 的数据推导。