docs(manifest): Improvements to related_applications and prefer_related_applications
#35906
Conversation
|
Preview URLs External URLs (1)URL:
(comment last updated: 2024-10-07 19:27:46) |
|
@dipikabh I'm away next week and am unlikely to get to this today/Friday (want to tidy release stuff). If it feels urgent, perhaps seek another reviewer :-) |
|
|
||
| ## Description | ||
|
|
||
| A "related application" is an application accessible to the underlying platform that has a relationship with your web app. The `related_applications` manifest member lets you inform users about the platform-specific versions of your web app. These native applications, which are installable by or accessible to the underlying platform, provide functionality similar to your web app and might offer additional features or better integration with user's device. For example, you could specify a native Android application available through the Google Play Store, which offers the same core features as your web app but better integration with the device's notification system. |
There was a problem hiding this comment.
We could make this a little shorter. Is this accurate?
| A "related application" is an application accessible to the underlying platform that has a relationship with your web app. The `related_applications` manifest member lets you inform users about the platform-specific versions of your web app. These native applications, which are installable by or accessible to the underlying platform, provide functionality similar to your web app and might offer additional features or better integration with user's device. For example, you could specify a native Android application available through the Google Play Store, which offers the same core features as your web app but better integration with the device's notification system. | |
| A "related application" is a native application that provides functionality similar to your web app but may offer additional features or better integration with the user's device. For example, you could specify a native Android application available through the Google Play Store, which provides the same core features as your web app but better integration with the device's notification system. The `related_applications` manifest member lets you inform users about the platform-specific versions of your web app. |
There was a problem hiding this comment.
Good one, thanks!
The para can do with some reorganizing and removal of some repeated ideas. However, the Android app example should follow only after we've mentioned related_applications, though there is scope for improving the example itself for clarity. How's this:
A "related application" is a {{Glossary("native")}} application that provides functionality similar to your web app.
It may offer additional features or better integration with users' devices.
Therelated_applicationsmanifest member lets you specify these platform-specific native versions of your web app.
For example, consider you have a native Android app for your product available through the Google Play Store.
It provides the same core features as your web app and integrates better with the device's notification system.
You can userelated_applicationsto specify this native Android app in your web app's manifest file.
There was a problem hiding this comment.
Slight update here, adding the word "relationship" as it seems to be key in defining "related application". Also introducing a para break after defining "related application":
A "related application" is a {{Glossary("native")}} application that has a relationship with your web app.
This relationshop means the native app provides functionality similar to your web app, often with additional features or better integration with users' devices.
The
related_applicationsmanifest member lets you specify these platform-specific native applications that are related to your web app.
For example, consider you have a native Android app for your product available through the Google Play Store.
It provides the same core features as your web app and integrates better with the device's notification system.
You can userelated_applicationsto specify this native Android app in your web app's manifest file.
| </tr> | ||
| </tbody> | ||
| </table> | ||
| The `prefer_related_applications` manifest member is used to provide a hint to browsers about whether to prefer related native applications over your web application. It is typically used in conjunction with the [`related_applications`](/en-US/docs/Web/Manifest/related_applications) manifest member. |
There was a problem hiding this comment.
- Typically? What is the point of setting this without related_applications? What is the point of related_applications without this? It might not be mandatory, but we should still say "should" or "is used"
- I think it is worth stating what preferred means here - i.e. a hint from your examples below about the use case.
- Why would you ever specify related applications and not have this set true?
There was a problem hiding this comment.
Updated intro to be more direct (closer to what it was originally) to state that prefer_related_applications directly depends on related_applications:
The
prefer_related_applicationsmanifest member is used to provide a hint to browsers whether to prioritize native applications specified in therelated_applicationsmanifest member over your web application.
I think that answers 1 and 2. (also changed "prefer" to "prioritize")
- From the
related_applicationsspec, it seems that browsers may still suggest native applications as options (that is, whenprefer_related_applicationsis not set):
" Example of usages of the related_applications could be a crawler that would use that information to gather more information about the web application or a browser that could suggest a listed application as an alternative if the user wants to install the web application. "
But I'm not really sure about if in real world, folks specify related apps as well as omit/set false prefer_related_applications. So I haven't mentioned it on either page.
There was a problem hiding this comment.
Updated the examples on this page as well to make the prose more specific to the example scenarios.
|
Hi Hamish, all comments addressed or answered now. For the |
There was a problem hiding this comment.
@dipikabh I made a few minor improvements to some parts of the text and merged them. Approving so you can merge if you like, or revert if you hate the changes.
|
Your suggested changes are all good, Hamish. No strong objections :). |
Description
This work is part of improving the web/manifest docs.
Apart from normalizing the page layout to include "Syntax" and "Values", this PR includes the following changes:
related_apps:prefer_related_apps:Motivation
To ensure all sections have sufficient explanation, all caveats from spec are covered, and the pages follow a similar template
Additional details
Related issues and pull requests
Tracking issue: mdn/mdn#560