Skip to content

Commit

Permalink
Add a Sec-CH-UA-Form-Factor hint (#338)
Browse files Browse the repository at this point in the history 
* Add a Sec-CH-UA-Form-Factor hint
* Include Form-Factor hint in explainer

Fixes #333
  • Loading branch information
@miketaylr
miketaylr committed Mar 30, 2023
1 parent ec059e9 commit e24995c
Show file tree
Hide file tree
Showing 2 changed files with 69 additions and 20 deletions.
14 changes: 13 additions & 1 deletion README.md
View file
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
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

0 comments on commit e24995c

Please sign in to comment.