Skip to content

Describe how pieces of an application can be user agents. #21

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 4 commits into
base: main
Choose a base branch
from
Open

Describe how pieces of an application can be user agents. #21

Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
e1f0df0
Describe how pieces of an application can be user agents.
jyasskin Aug 27, 2025
458f561
Try to be clearer/shorter about what allows an app to treat only part…
jyasskin Sep 17, 2025
f283e29
Be clearer that applications need to work to follow the Duties when u…
jyasskin Sep 17, 2025
8bdbffe
Add an address bar example for confusing 3p and 1p content.
jyasskin Sep 17, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
51 changes: 50 additions & 1 deletion index.bs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -48,6 +48,54 @@ user agents choose which specifications to implement in order to best serve thei
and they implement proprietary user interfaces and other behavior
around the specifications they do implement.

## User agents as software components ## {#ua-as-software}

As software entities, user agents can be parts of larger applications,
and they can call libraries that implement the web platform or parts of it.

If an overall application makes a clear distinction
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I agree with @NiklasMerz that whether 3p contents are hosted makes a much bigger difference than whether the users can distinguish 1p vs. 3p parts. We shouldn't assume users can understand the difference between the browser chrome and the web content.

As a counterexample to the proposed text, consider PWA, which hides the browser chrome and everything displayed to the user is 3p. But user might consider that content 1p as they may not understand that a PWA is running inside a UA.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

In a PWA (e.g. example.com), the user agent (e.g. Chrome) is showing 3p content, and has to obey the duties. Example.com is showing 1p data and doesn't have to obey the duties.

between its pieces that are [=user agents=] and its pieces that aren't,
then only the [=user agent=] parts,
which browse "third-party" content,
need to follow the [=user agent duties=].
Parts that are clearly only showing the application's own content
can act on their own behalf,
but the application should still
give its users clear expectations about
what behavior they should expect from different parts of the app.
If the distinction between third-party and first-party content is too small,
the application should also follow the [=user agent duties=]
for its first-party content.
Comment on lines +66 to +68
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

"too small" leaves room for subjective interpretation / inconsistent implementations. We should clarify criteria or give examples, e.g., availability or visibility of the address bar, permission prompts, TLS indicator / padlock, Origin display, other visual separation (like marking embedded iframes / ads differently).

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think it's fine to leave this subjective, and merely set the ground for future discussion. The duties are subjective too. I've added an address bar example.

For example, if the application doesn't show a distinct address bar
when browsing third-party content,
that likely means that
its first-party pieces should also follow the [=user agent duties=].

Similarly a library that implements the web platform
may or may not be a full [=user agent=].
Some, like [`SFSafariViewController`](https://developer.apple.com/documentation/safariservices/sfsafariviewcontroller)
and [Android Custom Tabs](https://developer.chrome.com/docs/android/custom-tabs)
take the responsibility of implementing the [=user agent duties=]
and of making a clear distinction between the third-party content they browse
and the first-party content controlled by the embedded application.
These libraries are [=user agents=].
Comment on lines +74 to +81
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Do thes platform-specific example libraries fully comply with UA duties in all contexts? Are there test results showing that they make a distinction between 1p and 3p content? They may also be subject to change in the future. It may be better to generalise the characteristics rather than naming specific ones. As I understand it, they show the address bar but that may just be one example and I don't doubt that there is are others ones that can signal to the user to help make the distinction between 1p and 3p.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I believe they do, at least as far as the underlying browsers do, and that their developers will consider it a bug if an application can cause these libraries to behave "worse" than the underlying browsers. On the other hand, the WebView libraries don't make any such effort.

These libraries treat everything inside them as 3p content, even if you happen to browse back to the embedding app's site, and that's totally acceptable behavior w.r.t. the duties.

If these libraries change to stop following the UA duties, or to let applications override their defaults, that'll be a bad change for any application relying on them, and I hope that including them here will help us push against such a change. I could say "as of 2025" to hedge a bit, but if that change does happen, we will want to update this document.


Other libraries, like the
[Android](https://developer.android.com/reference/android/webkit/WebView),
[iOS](https://developer.apple.com/documentation/webkit/wkwebview),
and [Windows](https://developer.microsoft.com/en-us/Microsoft-edge/webview2/)
WebView libraries,
are designed to support many kinds of applications.
Because some of these applications only include first-party content,
WebView libraries aren't meant to be [=user agents=] on their own,
and they don't implement the [=user agent duties=].
Comment on lines +89 to +91
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't disagree and I get the point this is trying to make but saying that WebViews aren't meant to be UAs shifts the burden of responsibility without specifying safeguards.

Copy link

@NiklasMerz NiklasMerz Sep 14, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't disagree, too. For WebViews it's really complicated. On on hand they aren't user agents because the embedding app has a lot of control over it and they are often used to only load first party content. Developers implementing might not even know about the responsibilities. On the other hand WebViews apply a lot over user agent duties today that don't necessarily make sense since the app can work around them using WebView APIs.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@csarven I'm trying to improve safety by having this document inform the WebView embedders that if they let the WebView navigate to content they didn't provide, they suddenly have a bunch more responsibilities. Until this, I don't think any document exists to warn them about that.


Ultimately, an embedding application is responsible for ensuring
that it follows the [=user agent duties=] if it or part of it is a [=user agent=].
This can be nearly trivial if it only browses third-party content using a [=user agent=] library.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This phrasing may mislead devs into underestimating potential risk.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What risks are you worried they'll miss because of this? I think it's right to say that if a developer uses Android Custom Tabs or SFSafariViewController for opening links, they don't need to do anything more to deal with the Duties, but I could mention a particular thing if you know of it.

Developers need to take extra care
to follow the [=user agent duties=]
when implementing an in-app browser using a non-[=user agent=] WebView.

# How the ecosystem works # {#ecosystem}

Expand All @@ -71,7 +119,8 @@ fast enough to prevent the culture-loss from spreading.

Each user agent serves its user ([[!RFC8890 inline]]),
not any of the other constituencies.
A user agent owes its user various duties,
A user agent owes its user various
<dfn lt="user agent duties|UA duties">duties</dfn>,
which should be established through collective discussions
and embodied in the various standards that user agents implement.

Expand Down