Enable developers to know if a web app has been installed

[aarongustafson]

We’ve gotten signal that some developers have an interest in making adjustments to their content and/or resource payload based on installation status. Currently, folks are relying on querying "display mode" on the client side as a proxy, but display mode does not indicate installation status (e.g., a "fullscreen" display mode is indicated even if the site was put in fullscreen mode via the JavaScript API.

This issue thread is intended to catalog the use cases folks have for wanting to know about installation status.

Related: #32 and https://github.com/w3c/manifest/pull/977

[aarongustafson]

Use Case 1: Web apps are currently forced to deliver the same content and scripts to all users and cannot vary those based on whether the app is installed. For example, they may choose not to include the content and images advertising the availability of their app in an app catalog if they know it is already installed on this device.

Use Case 2: (via @dmurph) Established properties use server-side logging frameworks for metrics and experiments, and it is really difficult to pipe back data from JavaScript on the client to join with the server side logs to know 'is this user viewing the site as a webapp?'. Providing this information as a Client Hints unblocks these sites from putting major resources towards webapps because they can now run experiments to determine things like "relation between user satisfaction / retention and web app usage."

Use Case 3: (via @hrantabelyan) Serving different layout/content based on installation status, for example excluding footer or displaying different content in header—it's not about show/hide something, that's possible on client side—but we also don't want to make DB queries for that layout/content that DB query is not something complex for the case that we have right now, but imagine if it's something with multiple SQL DB joins and/or heavy API calls.

Use Case 4: (via @comp615) When an app catalog-installed PWA is launched by clicking a link from another web property—and the link is captured and redirected into the app—the Referer value would be the referring property as opposed to the app catalog. The app catalog Referer is a solid proxy for knowing a web app is installed, but that signal is lost in this scenario.

[dmurph]

Thinking in terms of the display-mode client hint solving these:

@aarongustafson said:

Use Case 1: Web apps are currently forced to deliver the same content and scripts to all users and cannot vary those based on whether the app is installed. For example, they may choose not to include the content and images advertising the availability of their app in an app catalog if they know it is already installed on this device.

Is it a non-starter if they are shown when the site is opened in a tab? If the site requires an install to function properly, then the UX will still need to show up if the user opens in a tab instead of in the desired app display mode.

I see one use-case here that display mode client hints doesn't solve as "We want users to know they can install the app, but we don't want to force them".

Use Case 2: (via @dmurph) Established properties use server-side logging frameworks for metrics and experiments, and it is really difficult to pipe back data from JavaScript on the client to join with the server side logs to know 'is this user viewing the site as a webapp?'. Providing this information as a Client Hints unblocks these sites from putting major resources towards webapps because they can now run experiments to determine things like "relation between user satisfaction / retention and web app usage."

I believe this is solved by display mode client hints.

Use Case 3: (via @hrantabelyan) Serving different layout/content based on installation status, for example excluding footer or displaying different content in header—it's not about show/hide something, that's possible on client side—but we also don't want to make DB queries for that layout/content that DB query is not something complex for the case that we have right now, but imagine if it's something with multiple SQL DB joins and/or heavy API calls.

I believe this is solved by display mode client hints, and perhaps better! If the user views the web content in the tab, the developer would, I imagine, want to serve UX that is suited to a browser experience instead of the windowed experience.

Use Case 4: (via @comp615) When an app catalog-installed PWA is launched by clicking a link from another web property—and the link is captured and redirected into the app—the Referer value would be the referring property as opposed to the app catalog. The app catalog Referer is a solid proxy for knowing a web app is installed, but that signal is lost in this scenario.

I'm less familiar with this case - but is this stardarized? Is this solved by the url handlers project? This doesn't seem like a use-case as much as way to possibly expose this? I'm a little confused.

[aarongustafson]

Is it a non-starter if they are shown when the site is opened in a tab? If the site requires an install to function properly, then the UX will still need to show up if the user opens in a tab instead of in the desired app display mode.

We are considering an "isInstalled" DOM flag as well. I don’t see any reason why providing this in a tab would be problematic. Some apps may not choose to link capture and may be ok with their app living in either a tab or a standalone window (or both).

I believe this is solved by display mode client hints.

At present there is at least one major issue with relying on display mode as an indicator if installation: fullscreen. Right now, if you put an app in fullscreen using the DOM API, the display mode setting collected via matchMedia is the same as if the app was a "fullscreen" pwa. This may not be the only isolated instance going forward. While it may be possible that display mode may be useful for some apps to inform their delivery, it seems like it would not cover all cases (especially when red herrings like "fullscreen" exist). If someone wants to make decisions based on whether the app is installed or not, they should be able to query that explicitly rather than relying on a proxy like display mode.

I'm less familiar with this case - but is this stardardized?

It’s non-standard at present, but may become a de facto standard (since app catalogs are not—presently—considered to be implementors). Edge is doing this for Store-installed PWAs. The Play Store does something similar with TWAs (and we are trying to get them to align on the format). We have also approached Samsung about doing the same with their TWAs.

Is this solved by the url handlers project?

No. URL Handlers would handle the redirection into the PWA (and cause the true Referer to be passed). They would not present any info about whether the app was installed.

This doesn't seem like a use-case as much as way to possibly expose this? I'm a little confused.

We have some partners who are using the app catalog-derived Referer header as an indication that the launched session exists within an installed app, but that information is not passed along when there is a true referrer as that referrer takes precedence. Therefore, any app using that app catalog Referer as a proxy for "is installed" would not get the signal. Does that make it clear? The link I included walks through the feature in a bit more detail.

[dmurph]

Use case 4: Got it (regarding the referer). This doesn't seem like a 'use case' to me as much as an unreliable signal for installed - is that right? Could we design that app catalog API so that the site would continue to work if it was uninstalled?

Use case 2: Fullscreen - seems to be what we want for differential rendering (rendering for a given display purpose). Regarding metrics, the server-side logging framework case, that partner actually explicitly wanted display mode, not installed - they want to know which UX experience their users were using, so fullscreen made sense, and having browser even if the app was installed was preferred.

Questions about 1 and 2 and 3: How would this behavior change if the site was installed, but showing in a tab? Would the behavior want to be the same as 'not installed'?

Regarding this signal in general, I have voiced in the past the view that we should avoid giving a reliable signal here, as it would be bad for users if web sites have a way to force users to install their web sites. Especially if user agents initiate OS integration with installation, or make decisions based on installation status.

Use Case 5: App catalogs need a way to differentiate between "Install" and "Open" if the app is already installed. I'm not sure how we would get around that without exposing this information to the app catalog.

[aarongustafson]

This doesn't seem like a 'use case' to me as much as an unreliable signal for installed - is that right?

It’s another inference (like display mode) that indirectly indicates installation, but is unreliable. I brought it up because it creates a gap.

Could we design that app catalog API so that the site would continue to work if it was uninstalled?

The site would always work, regardless. The Referer header is only sent by Edge if the Microsoft Store triggers the install (much the same as how TWAs work).

Use case 2: Fullscreen - seems to be what we want for differential rendering (rendering for a given display purpose). Regarding metrics, the server-side logging framework case, that partner actually explicitly wanted display mode, not installed - they want to know which UX experience their users were using, so fullscreen made sense, and having browser even if the app was installed was preferred.

To be clear, I am not saying there’s no value in knowing the display mode. There absolutely is. If that’s the signal that gets you the info you need to make an informed decision about rendering, resources, etc. that’s awesome. I am saying that if someone wants to make a similar decision gated specifically on the question of installation, display mode may seem like an attractive (and often accurate) proxy, but it isn’t the same thing as being explicitly told your site has been installed.

Questions about 1 and 2 and 3: How would this behavior change if the site was installed, but showing in a tab? Would the behavior want to be the same as 'not installed'?

As with so many things, it will depend on the specific adjustments someone is making…

• For UC#1, I would expect no difference in what gets sent over the wire because it’s not about how the site is being displayed that would govern whether you advertise your site for installation (though it may govern how).
• For UC#2, it would depend on the metrics that are being tracked and/or AB tests being run. It’s possible that some developer might want to run an experiment only for their installed user base, for instance. We do have a partner that is only allowing installation of their PWA via the Microsoft Store while they experiment, so that doesn’t seem too far afield. Once installed, I’d imagine that same experiment would run in-app and in-tab, but that it may also be further informed by the display mode Client Hint.
• For UC#3, as I read the use case, it’s not about differential rendering so much as it is streamlining the assembly of a response that is somehow predicated on the question of installation. I don’t know the specifics of their implementation, but it sounds like one permutation of the experience is far more expensive to generate than another and, if given the option, they’d prefer to choose the least expensive codepath for generating the markup prior to generating that response. Without knowing the particulars as to how installation factors in, I can’t say for sure, but they did say that installation status (as opposed to display mode) created the delta, so I have to assume that they’d provide the same rendering either in-tab or in whatever display mode they chose for their app.

Regarding this signal in general, I have voiced in the past the view that we should avoid giving a reliable signal here, as it would be bad for users if web sites have a way to force users to install their web sites.

To be clear, I am not advocating that “web sites have a way to force users to install their web sites.” I agree it’s possible that an app developer might use a dark pattern wherein they did not allow sign-in without installation, but I don’t see much of a difference between that and sites that force you to accept certain permissions in order to use them (which is also currently possible). My sense is that approach would backfire in a similar way and they’d change their behavior to not create lock-in.

Especially if user agents initiate OS integration with installation, or make decisions based on installation status.

I’m not sure I follow. Could you expand on this?

Use Case 5: App catalogs need a way to differentiate between "Install" and "Open" if the app is already installed. I'm not sure how we would get around that without exposing this information to the app catalog.

This is something else we’re trying to figure out, to be honest. I don’t think there’s a way to do it without the catalog itself having knowledge of (or potentially being able to detect) the installation status of a given app. The various ideas I’d considered are (to the best of my recollection):

• The app catalog has an account and tracks installation on behalf of the user. Sadly this could get out of sync if the user uninstalls the app from the browser or OS side of things.
• The app catalog install/open button has a specific attribute or attribute/path combination that informs the browser of its intent to prompt for installation (e.g., link with a download attribute and an href pointing to a manifest). The browser could then augment the link text and behavior dynamically based on installation status. The catalog would not inherently know whether the app was installed, but it could observe the link for changes and track installation client-side (unless we suppressed such capabilities on that element).

To truly avoid the potential privacy violation, we could just have the link be a link to the app and recommend the text be "Install / Launch" :-)

[tomayac]

Limited to just Android, a site pwa.example.com run in a browser tab can detect if the PWA pwa.example.com (that is, itself) is installed by calling the getInstalledRelatedApps() method. This works both from in-scope and from out-of-scope, the latter thanks to an assetlinks.json file in a /.well-known directory.

[rayankans]

Yes, you can use getInstalledRelatedApps to figure out if a PWA is installed. However, I believe the use-cases mentioned here are geared towards figuring out whether the user is using the website or the PWA, which gIRA can't help with.

[tomayac]

Right. It would help with Use Case 1, though, where it's purely about delivery:

Use Case 1: Web apps are currently forced to deliver the same content and scripts to all users and cannot vary those based on whether the app is installed. For example, they may choose not to include the content and images advertising the availability of their app in an app catalog if they know it is already installed on this device.

[aarongustafson]

Interesting. Thanks for that info @tomayac. I wasn't aware gIRA had that capability. Unfortunately, gIRA is client side only, so we still need the Client Hint for server side, but it sounds like we don't need to add another DOM API.

[jcayzac]

If implemented as a client hint, wouldn't the information be sent to any 3rd-party origin as well? A DOM API feels more appropriate to me. Also there's no need to send the information repeatedly anywhere if nobody is asking for it.

[aarongustafson]

If implemented as a client hint, wouldn't the information be sent to any 3rd-party origin as well? A DOM API feels more appropriate to me. Also there's no need to send the information repeatedly anywhere if nobody is asking for it.

No. It would only be sent to the start_url. We’re looking at a DOM API as well, but that is client-side only, however, and would not allow for content negotiation on the server.

I imagine you’re asking about 3rd parties in terms of being able to know, as a catalog, if an app has been installed already. There are valid reasons we’d like to find a solution for this, however, there are serious privacy implications. There might be a way to build an allow-list within the Manifest (or maybe via a file in /.well-known/) for advertising a PWA’s installation status, however. I’m certainly open to discussing that.