From 8c2f68e2c212b22b605df3b37238fa1476ae0b98 Mon Sep 17 00:00:00 2001 From: Mike Taylor Date: Mon, 27 Mar 2023 12:40:43 -0400 Subject: [PATCH 1/3] Add a Sec-CH-UA-Form-Factor hint Fixes #333 --- index.bs | 75 ++++++++++++++++++++++++++++++++++++++++++-------------- 1 file changed, 56 insertions(+), 19 deletions(-) diff --git a/index.bs b/index.bs index 8ea9963..68e4c37 100644 --- a/index.bs +++ b/index.bs @@ -435,13 +435,16 @@ has defined a number of properties for itself: * brand - 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. -* significant version - 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). +* form-factor - The form-factor of a device, historically + represted as a <[=deviceCompat=]> token in the User-Agent string (e.g., "Tablet", "VR", + etc.) * full version - 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. +* model - The [=user agent=]'s device model (e.g., "", or + "Pixel 2 XL") +* mobileness - A boolean indicating if the [=user agent=]'s + device is a mobile device. (e.g., ?0 or ?1) * platform brand - The [=user agent=]'s operating system's commercial name. (e.g., "Windows", "iOS", or "AmazingOS") * platform version - The [=user agent=]'s operating system's @@ -450,10 +453,10 @@ has defined a number of properties for itself: architecture (e.g., "ARM", or "x86") * platform bitness - The [=user agent=]'s underlying CPU architecture bitness (e.g., "32" or "64") -* model - The [=user agent=]'s device model (e.g., "", or - "Pixel 2 XL") -* mobileness - A boolean indicating if the [=user agent=]'s - device is a mobile device. (e.g., ?0 or ?1) +* significant version - 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). * wow64-ness - A boolean indicating if the [=user agent=]'s binary is running in 32-bit mode on 64-bit Windows. (e.g., ?0 or ?1) @@ -536,8 +539,8 @@ The 'Sec-CH-UA-Bitness' Header Field {#sec-ch-ua-bitness} ------------------------------ The `Sec-CH-UA-Bitness` 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: @@ -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 `Sec-CH-UA-Form-Factor` 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} -------------------------------- @@ -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} ================= @@ -741,16 +761,17 @@ dictionary NavigatorUABrandVersion { }; dictionary UADataValues { - sequence<NavigatorUABrandVersion> brands; - boolean mobile; DOMString architecture; DOMString bitness; + sequence<NavigatorUABrandVersion> brands; + DOMString formFactor; + sequence<NavigatorUABrandVersion> fullVersionList; DOMString model; + boolean mobile; DOMString platform; DOMString platformVersion; DOMString uaFullVersion; // deprecated in favor of fullVersionList boolean wow64; - sequence<NavigatorUABrandVersion> fullVersionList; }; dictionary UALowEntropyJSON { @@ -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=]. @@ -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. @@ -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} ---------------------------- From c23a246afa205cc934c5d77c022cf36f91d099a7 Mon Sep 17 00:00:00 2001 From: Mike Taylor Date: Wed, 29 Mar 2023 16:49:35 -0400 Subject: [PATCH 2/3] Include Form-Factor hint in explainer --- README.md | 14 +++++++++++++- 1 file changed, 13 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 6c6b4da..7d492f8 100644 --- a/README.md +++ b/README.md @@ -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` @@ -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. @@ -254,6 +265,7 @@ accomplish this as follows: boolean mobile; // true DOMString architecture; // "arm" DOMString bitness; // "64" + DOMString formFactor; // "Automobile" FrozenArray fullVersionList; // [ {brand: "Google Chrome", version: "84.0.4147.0"}, {brand: "Chromium", version: "84.0.4147"} ] DOMString model; // "X644GTM" DOMString platform; // "PhoneOS" @@ -266,7 +278,7 @@ accomplish this as follows: readonly attribute FrozenArray brands; // [ {brand: "Google Chrome", version: "84"}, {brand: "Chromium", version: "84"} ] readonly attribute boolean mobile; // false readonly attribute platform; // "PhoneOS" - Promise getHighEntropyValues(sequence 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 getHighEntropyValues(sequence 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 { From 2fbf40bb763ffafdf130641d05b9e42179fe15f4 Mon Sep 17 00:00:00 2001 From: Mike Taylor Date: Wed, 29 Mar 2023 16:50:08 -0400 Subject: [PATCH 3/3] Fix typo --- index.bs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/index.bs b/index.bs index 68e4c37..6a3e69e 100644 --- a/index.bs +++ b/index.bs @@ -436,7 +436,7 @@ has defined a number of properties for itself: "cURL", "Edge", "The World's Best Web Browser"), which MUST be shorter than 32 [=ASCII alpha=] characters. * form-factor - The form-factor of a device, historically - represted as a <[=deviceCompat=]> token in the User-Agent string (e.g., "Tablet", "VR", + represented as a <[=deviceCompat=]> token in the User-Agent string (e.g., "Tablet", "VR", etc.) * full version - The build version (e.g., "72.0.3245.12", "3.14159", or "297.70E04154A") that corresponds to the [=user agent=], or any