Skip to content

Commit

Permalink
docs(manifest): Improvements to name, short_name, start_url (#3…
Browse files Browse the repository at this point in the history 
…5847)

* updated name and short_name

* start_url wip

* start_url updates

* update syntax blocks

* update keys headings

* fix feedback wip

* fix start_url value interpretation

* update glossary app context

* add meaning of applied manifest

* Update files/en-us/web/manifest/name/index.md

* apply feedback

* remove chromium notes

* fix feedback

* update note

* Improve description and browser flexibility link

* Update files/en-us/web/manifest/start_url/index.md

---------

Co-authored-by: Hamish Willee <[email protected]>
  • Loading branch information
@dipikabh @hamishwillee
dipikabh and hamishwillee authored Oct 22, 2024
1 parent 3730011 commit 5d4cc96
Show file tree
Hide file tree
Showing 4 changed files with 188 additions and 57 deletions.
22 changes: 17 additions & 5 deletions files/en-us/glossary/application_context/index.md
View file
Original file line number Diff line number Diff line change
@@ -1,18 +1,30 @@
---
title: Application Context
title: Application context
slug: Glossary/Application_context
page-type: glossary-definition
---

{{GlossarySidebar}}

An **application context** is a top-level {{glossary("browsing context")}} that has a [manifest](/en-US/docs/Web/Manifest) applied to it.
**Application context** refers to the top-level {{glossary("browsing context")}} of a [web application](/en-US/docs/Web/Progressive_web_apps).
It determines how an app's browsing context, such as a tab or a window, is presented and behaves.

If an application context is created as a result of the user agent being asked to navigate to a deep link, the user agent must immediately navigate to the deep link with replacement enabled. Otherwise, when the application context is created, the user agent must immediately navigate to the start URL with replacement enabled.
Web developers define the application context in the [web app's manifest file](/en-US/docs/Web/Manifest).
They use the [`scope`](/en-US/docs/Web/Manifest/scope) member in the manifest to specify the set of URLs that are considered part of the application context and to which the manifest applies.

Please note that the start URL is not necessarily the value of the start_url member: the user or user agent could have changed it when the application was added to home-screen or otherwise bookmarked.
The manifest is applied after the application context is created but before navigation begins to either a start URL or a deep link.
A **start URL** is the initial page of the web app.
A **deep link** is a URL that directs users to a specific page within the web app, bypassing the home page.
The application context ensures that the app's defined behavior and presentation are maintained within its scope.

When an application context is created, browsers must immediately navigate to a start URL or a deep link.
This navigation replaces the current entry in the browsing history.
If the application context is created to navigate to a deep link, the browser navigates directly to that deep link; otherwise, it navigates to the start URL.

Note that the start URL is not necessarily the value of the [`start_url`](/en-US/docs/Web/Manifest/start_url) member in the manifest. Browsers may ignore the specified `start_url` or may allow users to change its value when adding the web app to their device's home screen or bookmarking it.

## See also

- [Progressive web apps (PWA)](/en-US/docs/Web/Progressive_web_apps)
- [`scope`](/en-US/docs/Web/Manifest/scope)
- [Web app manifests](/en-US/docs/Web/Manifest)
- [Progressive web apps (PWA)](/en-US/docs/Web/Progressive_web_apps)
61 changes: 46 additions & 15 deletions files/en-us/web/manifest/name/index.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -7,31 +7,57 @@ browser-compat: html.manifest.name

{{QuickLinksWithSubpages("/en-US/docs/Web/Manifest")}}

<table class="properties">
<tbody>
<tr>
<th scope="row">Type</th>
<td><code>String</code></td>
</tr>
</tbody>
</table>
The `name` manifest member is used to specify the full name of your web application as it's usually displayed to users, such as in application lists or as a label for your application's icon.

The `name` member is a string that represents the name of the web application as it is usually displayed to the user (e.g., amongst a list of other applications, or as a label for an icon). `name` is directionality-capable, which means it can be displayed left-to-right or right-to-left based on the values of the [`dir`](/en-US/docs/Web/Manifest) and [`lang`](/en-US/docs/Web/Manifest) manifest members.
## Syntax

```json-nolint
/* Full names of web apps */
"name": "Daily Task Planner"
"name": "Recipe and Pantry Tracker"
```

### Values

- `name`
- : A string that specifies the full name of your web app.

## Description

The `name` manifest member serves as the {{Glossary("Accessible_name", "accessible name")}} for your installed app. It is displayed to users in various contexts, such as in a list of other installed web apps, as a label for your app's icon, or in the application switcher or task manager.

In space-constrained contexts where the full `name` may not fit, such as on a device's home screen or in the application switcher, the value of the [`short_name`](/en-US/docs/Web/Manifest/short_name) property (if defined) may be used instead.

### Best practices for naming your web app

Consider the following factors when selecting a name for your web app:

- Length of the name, especially if you're not providing a separate `short_name`
- How well it indicates the purpose or nature of your app
- Whether it is clear and easy to understand and remember
- How it appears in different contexts, such as in app lists or home screen
- How easily it can be differentiated from other similar apps
- Cultural sensitivity and appropriateness for your target audience
- How well it translates or is perceived in different languages if your app target is a global audience
- Potential trademark conflicts

## Examples

Simple `name` in left-to-right language:
### Adding a name for your web app

For a web app that helps users navigate trails and plan their hiking adventures, you might add the following `name` to the app manifest:

```json
"name": "Awesome application"
"name": "Trail Navigator"
```

Right-to-left `name` in Arabic:
The app name `Trail Navigator` effectively describes the app's purpose, is easy to read and remember, and is likely to be understood by a wide audience. It uses familiar terms that outdoor enthusiasts might readily understand.

If you want, you can also add a `short_name`:

```json
"dir": "rtl",
"lang": "ar",
"name": "!أنا من التطبيق"
"name": "Trail Navigator",
"short_name": "TrailNav"
```

## Specifications
Expand All @@ -41,3 +67,8 @@ Right-to-left `name` in Arabic:
## Browser compatibility

{{Compat}}

## See also

- [`short_name`](/en-US/docs/Web/Manifest/short_name) manifest member
- [The web app manifest](/en-US/docs/Web/Progressive_web_apps/Guides/Making_PWAs_installable#the_web_app_manifest) for making your web app installable
55 changes: 35 additions & 20 deletions files/en-us/web/manifest/short_name/index.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -7,39 +7,54 @@ browser-compat: html.manifest.short_name

{{QuickLinksWithSubpages("/en-US/docs/Web/Manifest")}}

<table class="properties">
<tbody>
<tr>
<th scope="row">Type</th>
<td><code>String</code></td>
</tr>
</tbody>
</table>
The `short_name` manifest member is used to specify a short name for your web application, which may be used when the full [`name`](/en-US/docs/Web/Manifest/name) is too long for the available space.

The `short_name` member is a string that represents the name of the web application displayed to the user if there is not enough space to display [`name`](/en-US/docs/Web/Manifest/name) (e.g., as a label for an icon on the phone home screen). `short_name` is directionality-capable, which means it can be displayed left-to-right or right-to-left based on the value of the [`dir`](/en-US/docs/Web/Manifest) and [`lang`](/en-US/docs/Web/Manifest) manifest members.
## Syntax

## Examples
```json-nolint
/* Short names of web apps */
"short_name": "TaskPlanner"
"short_name": "RecipePantry"
```

Simple `short_name` in left-to-right language:
### Values

```json
"name": "Awesome application",
"short_name": "Awesome app"
```
- `short_name`
- : A string that specifies a short version of your web app's [`name`](/en-US/docs/Web/Manifest/name).

## Description

Browsers may use `short_name` in place of [`name`](/en-US/docs/Web/Manifest/name) when there is insufficient space to display the full name, such as on a device's home screen, in the application switcher, or in other space-constrained contexts.

Keep the following points in mind when selecting a short name for your web app:

`short_name` in Arabic, which will be displayed right-to-left:
- It should be a concise version of your app's `name`.
- While aiming for brevity, it should still be recognizable and meaningful.
- Consider how it will appear in space-constrained contexts.
- Follow the same guidelines for cultural sensitivity and trademark as for `name`.

## Examples

### Adding a short name for your web app

Consider a web app that helps users plan and log their hiking adventures. The `name` has been defined as `Trail Navigator`. A `short_name` can be added to the manifest as follows:

```json
"dir": "rtl",
"lang": "ar",
"name": "تطبيق رائع",
"short_name": "رائع"
"name": "Trail Navigator",
"short_name": "TrailNav"
```

The app's shorter name `TrailNav` is concise and is suitable for limited space contexts. It maintains a connection to the app's full name and is easy to remember.

## Specifications

{{Specifications}}

## Browser compatibility

{{Compat}}

## See also

- [`name`](/en-US/docs/Web/Manifest/name) manifest member
- [The web app manifest](/en-US/docs/Web/Progressive_web_apps/Guides/Making_PWAs_installable#the_web_app_manifest) for making your web app installable
107 changes: 90 additions & 17 deletions files/en-us/web/manifest/start_url/index.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -7,36 +7,102 @@ browser-compat: html.manifest.start_url

{{QuickLinksWithSubpages("/en-US/docs/Web/Manifest")}}

<table class="properties">
<tbody>
<tr>
<th scope="row">Type</th>
<td><code>String</code></td>
</tr>
</tbody>
</table>
The `start_url` manifest member is used to specify the URL that should be opened when a user launches your web application, such as when tapping the application's icon on their device's home screen or in an application list.

The `start_url` member is a string that represents the _start URL of the web application_ — the preferred URL that should be loaded when the user launches the web application (e.g., when the user taps on the web application's icon from a device's application menu or homescreen).
> [!NOTE]
> The `start_url` is a hint for browsers. [Browsers have flexibility](#description) in how they the handle `start_url` and may not always use the specified value.
A valid `start_url` needs to be same-origin with the document that references the manifest. If `start_url` is unspecified or invalid in any way (such as not a string, not a valid URL, or not a same-origin with the document), the document URL is used.
## Syntax

> [!NOTE]
> The `start_url` member is purely advisory, and a user agent may ignore it or allow the user to alter it at install time or afterwards.
```json-nolint
/* Absolute URLs */
"start_url": "https://example.com/myapp"
"start_url": "https://myapp.com/home"
/* Relative URLs */
"start_url": "/"
"start_url": "../index.html"
```

### Values

- `start_url`

- : A string that represents the starting URL of a web app.
The URL can be absolute or relative.
If the value is relative, it is resolved against the manifest URL.

The `start_url` must be within the [scope](/en-US/docs/Web/Manifest/scope) of the web app and must be same-origin with the manifest URL.

If `start_url` is unspecified or the value is invalid (i.e., not a string, not a valid URL, or not same-origin with the manifest URL), the URL of the page that links to the manifest is used.

## Description

The `start_url` allows you to recommend an appropriate common entry point for all users.

Note, however, that browsers are not required to use the specified URL.
They may ignore the specified value or provide users with a choice not to use it.
They may also allow users to modify the URL when creating a bookmark for the web app or at a later time.
Keep this in mind when designing your app to allow for variations in `start_url`.

### Best practices

This URL should navigate users to an important page of your app, such as a dashboard.
Consider features that users would want to access immediately after launching the app.
If your app's main page is at the root of your site, you can set the `start_url` to `/`.
You can also specify a deep link (e.g., `https://myapp.com/product/whatsnew`) to direct users to specific content within your app.
Avoid specifying a generic starting page.

For security reasons, the `start_url` must be same-origin with the manifest URL.
If a non-same-origin `start_url` is specified, browsers will fallback to using the page that links to the manifest as the default starting page.

## Privacy considerations

- **Fingerprinting**:

Encoding strings into `start_url` to uniquely identify users (e.g., server-assigned identifiers, such as `?user=123`, `/user/123/`, or `https://user123.foo.bar`) creates a persistent fingerprint.
Users may not be aware that their privacy-sensitive information can persist even after they've cleared site data.
It is bad practice to include any information in `start_url` that could uniquely identify users.

Browsers may offer protection against this type of fingerprinting.
For example, when users clear data from an origin, browsers may prompt them to uninstall apps that are within that origin's scope.
This removes any potential fingerprint from the app's `start_url`.

- **Launch tracking**:

Adding parameters to a `start_url` to indicate that the app was launched from outside the browser (e.g., `"start_url": "index.html?launcher=homescreen"`) can be useful for analytics and customizations.
However, this information could be used as part of a user's digital fingerprint.
Consider the potential privacy implications when implementing such tracking.

## Examples

### Absolute URL
### Specifying an absolute starting URL

Let's say the manifest file for your hiking web app is at `https://hikingpro.com/resources/manifest.json`, and `https://hikingpro.com/index.html` links to the manifest file.
You want users to land on the `trailhub.html` page when they launch the app.
You can specify this starting URL in your manifest file like so:

```json
"start_url": "https://example.com"
"start_url": "https://hikingpro.com/trailhub.html"
```

### Relative URL
This `start_url` value is valid because it is same-origin with the manifest URL (`https://hikingpro.com/resources/manifest.json`).

If the URL is relative, the manifest URL is used as the base URL to resolve it.
The following `start_url` is invalid because it is not the same-origin with the manifest URL:

```json example-bad
"start_url": "https://other-domain.com/trailhub.html"
```

In the above case, `https://hikingpro.com/index.html` will be used as the default starting page when users launch the app.

### Specifying a relative starting URL

For your hiking app in the previous scenario, you can specify the same starting point using a relative URL, as shown below.
This relative URL will resolve to `https://hikingpro.com/trailhub.html` using the manifest file's URL (`https://hikingpro.com/resources/manifest.json`) as the base.

```json
"start_url": "../startpoint.html"
"start_url": "../trailhub.html"
```

## Specifications
Expand All @@ -46,3 +112,10 @@ If the URL is relative, the manifest URL is used as the base URL to resolve it.
## Browser compatibility

{{Compat}}

## See also

- {{Glossary("Application_context", "Application context")}}
- {{Glossary("Same-origin_policy", "Same-origin policy")}}
- [The web app manifest](/en-US/docs/Web/Progressive_web_apps/Guides/Making_PWAs_installable#the_web_app_manifest) for making your web app installable
- [Security on the web](/en-US/docs/Web/Security)

0 comments on commit 5d4cc96

Please sign in to comment.