Skip to content
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

Add a Sec-CH-UA-Form-Factor hint #338

Merged
merged 3 commits into from
Mar 30, 2023
+69 −20
Merged

Add a Sec-CH-UA-Form-Factor hint #338

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
8c2f68e
Add a Sec-CH-UA-Form-Factor hint
miketaylr Mar 27, 2023
c23a246
Include Form-Factor hint in explainer
miketaylr Mar 29, 2023
2fbf40b
Fix typo
miketaylr Mar 29, 2023
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
14 changes: 13 additions & 1 deletion README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,6 +12,7 @@ a corresponding JavaScript API:
* `Sec-CH-UA-Platform`
* `Sec-CH-UA-Platform-Version`
* `Sec-CH-UA`
* `Sec-CH-UA-Form-Factor`
* `Sec-CH-UA-Full-Version` (deprecated in favor of `Sec-CH-UA-Full-Version-List`)
* `Sec-CH-UA-Full-Version-List`
* `Sec-CH-UA-WoW64`
Expand Down Expand Up @@ -202,6 +203,16 @@ accomplish this as follows:
Sec-CH-UA-Bitness: "64"
```

1. The `Sec-CH-UA-Form-Factor` header field represents the form-factor of a device, historically
represented as a <deviceCompat> token in the User-Agent string (e.g., "Tablet", "VR",
etc.)

For example:

```http
Sec-CH-UA-Form-Factor: "XR"
```

1. The `Sec-CH-UA-Mobile` header field represents whether the user agent should receive a
specifically "mobile" UX.

Expand Down Expand Up @@ -254,6 +265,7 @@ accomplish this as follows:
boolean mobile; // true
DOMString architecture; // "arm"
DOMString bitness; // "64"
DOMString formFactor; // "Automobile"
FrozenArray<NavigatorUABrandVersion> fullVersionList; // [ {brand: "Google Chrome", version: "84.0.4147.0"}, {brand: "Chromium", version: "84.0.4147"} ]
DOMString model; // "X644GTM"
DOMString platform; // "PhoneOS"
Expand All @@ -266,7 +278,7 @@ accomplish this as follows:
readonly attribute FrozenArray<NavigatorUABrandVersion> brands; // [ {brand: "Google Chrome", version: "84"}, {brand: "Chromium", version: "84"} ]
readonly attribute boolean mobile; // false
readonly attribute platform; // "PhoneOS"
Promise<UADataValues> getHighEntropyValues(sequence<DOMString> hints); // { architecture: "arm", bitness: "64", model: "X644GTM", platform: "PhoneOS", platformVersion: "10A", fullVersionList: [ {brand: "Google Chrome", version: "84.1.2.3"}, {brand: "Chromium", version: "84.1.2.3"}, {brand: "Not A;Brand", version: "101.3.2.9"} ] }
Promise<UADataValues> getHighEntropyValues(sequence<DOMString> hints); // { architecture: "arm", bitness: "64", model: "X644GTM", platform: "PhoneOS", platformVersion: "10A", formFactor: "VR", fullVersionList: [ {brand: "Google Chrome", version: "84.1.2.3"}, {brand: "Chromium", version: "84.1.2.3"}, {brand: "Not A;Brand", version: "101.3.2.9"} ] }
};

interface mixin NavigatorUA {
Expand Down
75 changes: 56 additions & 19 deletions index.bs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -435,13 +435,16 @@ has defined a number of properties for itself:
* <dfn for="user agent" export>brand</dfn> - The [=user agent=]'s commercial name (e.g.,
"cURL", "Edge", "The World's Best Web Browser"), which MUST be shorter than 32 [=ASCII alpha=]
characters.
* <dfn for="user agent" export>significant version</dfn> - The marketing version which includes
distinguishable web-exposed features (e.g., "72", "3", or "12.1"), corresponding to the
[=user agent=], or any of the brands in its [=brands=] list (e.g., rendering engine or
any other [=equivalence classes=] full version).
* <dfn for="user agent" export>form-factor</dfn> - The form-factor of a device, historically
represented as a &lt;[=deviceCompat=]&gt; token in the User-Agent string (e.g., "Tablet", "VR",
etc.)
* <dfn for="user agent" export>full version</dfn> - The build version (e.g.,
"72.0.3245.12", "3.14159", or "297.70E04154A") that corresponds to the [=user agent=], or any
of the brands in its [=brands=] list.
* <dfn for="user agent" export>model</dfn> - The [=user agent=]'s device model (e.g., "", or
"Pixel 2 XL")
* <dfn for="user agent" export>mobileness</dfn> - A boolean indicating if the [=user agent=]'s
device is a mobile device. (e.g., ?0 or ?1)
* <dfn for="user agent" export>platform brand</dfn> - The [=user agent=]'s operating system's
commercial name. (e.g., "Windows", "iOS", or "AmazingOS")
* <dfn for="user agent" export>platform version</dfn> - The [=user agent=]'s operating system's
Expand All @@ -450,10 +453,10 @@ has defined a number of properties for itself:
architecture (e.g., "ARM", or "x86")
* <dfn for="user agent" export>platform bitness</dfn> - The [=user agent=]'s underlying CPU
architecture bitness (e.g., "32" or "64")
* <dfn for="user agent" export>model</dfn> - The [=user agent=]'s device model (e.g., "", or
"Pixel 2 XL")
* <dfn for="user agent" export>mobileness</dfn> - A boolean indicating if the [=user agent=]'s
device is a mobile device. (e.g., ?0 or ?1)
* <dfn for="user agent" export>significant version</dfn> - The marketing version which includes
distinguishable web-exposed features (e.g., "72", "3", or "12.1"), corresponding to the
[=user agent=], or any of the brands in its [=brands=] list (e.g., rendering engine or
any other [=equivalence classes=] full version).
* <dfn for="user agent" export>wow64-ness</dfn> - A boolean indicating if the [=user agent=]'s binary is running in 32-bit mode on 64-bit Windows. (e.g., ?0 or ?1)


Expand Down Expand Up @@ -536,8 +539,8 @@ The 'Sec-CH-UA-Bitness' Header Field {#sec-ch-ua-bitness}
------------------------------

The <dfn http-header>`Sec-CH-UA-Bitness`</dfn> request header field gives a server information about
the bitness of the architecture of the platform on which a given [=user agent=] is executing. It is
a [=Structured Header=] whose value MUST be a [=structured header/string=]
the [=platform bitness=] of the architecture of the platform on which a given [=user agent=] is
executing. It is a [=Structured Header=] whose value MUST be a [=structured header/string=]
[[!RFC8941]].

The header's ABNF is:
Expand All @@ -546,6 +549,23 @@ The header's ABNF is:
Sec-CH-UA-Bitness = sf-string
~~~

The 'Sec-CH-UA-Form-Factor' Header Field {#sec-ch-ua-form-factor}
------------------------------

The <dfn http-header>`Sec-CH-UA-Form-Factor`</dfn> request header field gives a server information
about the [=user agent=]'s [=form-factor=]. It is a [=Structured Header=] whose value MUST be a
[=structured header/string=]. Its value SHOULD match one of the following common form-factor values:
"Automobile", "Mobile", "Tablet", "TV", "VR", "XR", "Unknown" or the empty string.
[[!RFC8941]].

Note: A "desktop" form-factor would be represented by the empty string.

The header's ABNF is:

~~~ abnf
Sec-CH-UA-Form-Factor = sf-string
~~~

The 'Sec-CH-UA-Full-Version' Header Field {#sec-ch-ua-full-version}
--------------------------------

Expand Down Expand Up @@ -727,9 +747,9 @@ The header's ABNF is:
```

Note: These client hints can be evoked with the following set of [=client hints tokens=]:
`Sec-CH-UA`, `Sec-CH-UA-Arch`, `Sec-CH-UA-Bitness`, `Sec-CH-UA-Full-Version`,
`Sec-CH-UA-Full-Version-List`, `Sec-CH-UA-Mobile`, `Sec-CH-UA-Model`, `Sec-CH-UA-Platform`,
`Sec-CH-UA-Platform-Version`, `Sec-CH-UA-WoW64`
`Sec-CH-UA`, `Sec-CH-UA-Arch`, `Sec-CH-UA-Bitness`, `Sec-CH-UA-Form-Factor`,
`Sec-CH-UA-Full-Version`, `Sec-CH-UA-Full-Version-List`, `Sec-CH-UA-Mobile`, `Sec-CH-UA-Model`,
`Sec-CH-UA-Platform`, `Sec-CH-UA-Platform-Version`, `Sec-CH-UA-WoW64`

Interface {#interface}
=================
Expand All @@ -741,16 +761,17 @@ dictionary NavigatorUABrandVersion {
};

dictionary UADataValues {
sequence&lt;NavigatorUABrandVersion&gt; brands;
boolean mobile;
DOMString architecture;
DOMString bitness;
sequence&lt;NavigatorUABrandVersion&gt; brands;
DOMString formFactor;
sequence&lt;NavigatorUABrandVersion&gt; fullVersionList;
DOMString model;
boolean mobile;
DOMString platform;
DOMString platformVersion;
DOMString uaFullVersion; // deprecated in favor of fullVersionList
boolean wow64;
sequence&lt;NavigatorUABrandVersion&gt; fullVersionList;
};

dictionary UALowEntropyJSON {
Expand Down Expand Up @@ -936,6 +957,8 @@ ISSUE(wicg/ua-client-hints): We can improve upon when and why a UA decides to re
the [=user agent=]'s [=user agent/platform architecture=].
1. If |hints| [=list/contains=] "bitness", set |uaData|["{{UADataValues/bitness}}"] to
the [=user agent=]'s [=user agent/platform bitness=].
1. If |hints| [=list/contains=] "formFactor", set |uaData|["{{UADataValues/formFactor}}"] to
the [=user agent=]'s [=user agent/form-factor=].
1. If |hints| [=list/contains=] "fullVersionList", set |uaData|["{{UADataValues/fullVersionList}}"]
to [=this=]'s [=relevant global object=]'s
[=WindowOrWorkerGlobalScope/full version list frozen array=].
Expand Down Expand Up @@ -1098,9 +1121,10 @@ IANA Considerations {#iana}
===================

This document intends to define the `Sec-CH-UA`, `Sec-CH-UA-Arch`, `Sec-CH-UA-Bitness`,
`Sec-CH-UA-Full-Version`, `Sec-CH-UA-Mobile`, `Sec-CH-UA-Model`, `Sec-CH-UA-Platform`,
`Sec-CH-UA-Platform-Version`, `Sec-CH-UA-WoW64`, and the `Sec-CH-UA-Full-Version-List` HTTP request
header fields, and register them in the permanent message header field registry ([[RFC3864]]).
`Sec-CH-UA-Form-Factor`, `Sec-CH-UA-Full-Version`, `Sec-CH-UA-Mobile`, `Sec-CH-UA-Model`,
`Sec-CH-UA-Platform`, `Sec-CH-UA-Platform-Version`, `Sec-CH-UA-WoW64`, and the
`Sec-CH-UA-Full-Version-List` HTTP request header fields, and register them in the permanent message
header field registry ([[RFC3864]]).

It also intends to deprecate usage of the `User-Agent` header field.

Expand Down Expand Up @@ -1143,6 +1167,19 @@ Author/Change controller: IETF

Specification document: this specification ([[#sec-ch-ua-bitness]])

'Sec-CH-UA-Form-Factor' Header Field {#iana-form-factor}
--------------------------

Header field name: Sec-CH-UA-Form-Factor

Applicable protocol: http

Status: standard

Author/Change controller: IETF

Specification document: this specification ([[#sec-ch-ua-form-factor]])

'Sec-CH-UA-Full-Version' Header Field {#iana-full-version}
----------------------------

Expand Down