From db6fab2569b78666c40e84e4d0458dbdf59d336b Mon Sep 17 00:00:00 2001 From: Aaron Tagliaboschi Date: Wed, 16 Oct 2019 10:57:40 -0400 Subject: [PATCH] Add `Sec-CH-UA-Mobile`. Closes https://github.com/WICG/ua-client-hints/issues/5 and https://github.com/WICG/ua-client-hints/pull/8. --- README.md | 20 ++++++++ draft-west-ua-client-hints.md | 44 +++++++++++++++- index.bs | 50 +++++++++++++++++- index.html | 95 +++++++++++++++++++++++++++++------ 4 files changed, 193 insertions(+), 16 deletions(-) diff --git a/README.md b/README.md index c19281d..d76e06b 100644 --- a/README.md +++ b/README.md @@ -127,6 +127,13 @@ accomplish this as follows: ```http Sec-CH-UA-Model: "Pixel 2 XL" ``` + + 5. The `Sec-CH-UA-Mobile` header field represents whether the user agent should receive a specifically "mobile" + UX. + + ```http + Sec-CH-UA-Mobile: ?1 + ``` 4. These client hints should also be exposed via JavaScript APIs, perhaps hanging off a new `navigator.getUserAgent()` method as something like: @@ -144,6 +151,7 @@ accomplish this as follows: readonly attribute DOMString platform; // "Win 10" readonly attribute DOMString architecture; // "ARM64" readonly attribute DOMString model; // "" + readonly attribute bool mobile; // false }; ``` @@ -267,3 +275,15 @@ it seems reasonable to forbid access to these headers from JavaScript, and demar browser-controlled client hints so they can be documented and included in requests without triggering CORS preflights. A `Sec-CH-` prefix seems like a viable approach. _This bit might shift as the broader Client Hints discussions above coalesce into something more solid that lands in specs_. + +## How does `Sec-CH-UA-Mobile` define "mobile"? + +This is a tough question. The motiviation for the header is that a majority of user-agent header +sniffing is used by the server to decide if a "desktop" or "mobile" UX should be served. This is +currently implicitly defined in most modern browsers because they have two distinct UIs, a +"desktop" version (i.e. Windows, Mac OS, etc.) and a "mobile" version (i.e. Android, iOS). In general, +most browsers will also explicitly send "Mobile" in user-agent strings on "mobile" platforms. As +such, servers will usually use the platform or presence of this "mobile" identifier. It's also worth +pointing out that most modern browsers also have an explicit "request desktop site" UI element in their +mobile versions which should be honored. In a more general sense, though, a "mobile" experience could be +seen as a UX designed with smaller screens and touch-based interface in mind. diff --git a/draft-west-ua-client-hints.md b/draft-west-ua-client-hints.md index b1dead2..44b53ac 100644 --- a/draft-west-ua-client-hints.md +++ b/draft-west-ua-client-hints.md @@ -179,7 +179,7 @@ shown here. The following sections define a number of HTTP request header fields that expose detail about a given user agent, which servers can opt-into receiving via the Client Hints infrastructure defined in {{I-D.ietf-httpbis-client-hints}}. The definitions below assume that each user agent has defined -a number of properties for itself (all of which are strings): +a number of properties for itself: * `brand` (for example: "cURL", "Edge", "The World's Best Web Browser") * `major version` (for example: "72", "3", or "28") @@ -188,6 +188,7 @@ a number of properties for itself (all of which are strings): * `platform version` (for example: "10", "12", or "17G") * `platform architecture` (for example: "ARM64", or "ia32") * `model` (for example: "", or "Pixel 2 XL") +* `mobile` (for example: ?0 or ?1) User agents SHOULD keep these strings short and to the point, but servers MUST accept arbitrary values for each, as they are all values constructed at the user agent's whim. @@ -260,6 +261,30 @@ To generate a `Sec-CH-Platform` header value for a given request, user agents MU 2. Set a header in request's header list whose name is `Sec-CH-Platform`, and whose value is `value`. + +## The 'Sec-CH-Mobile' Header Field {#sec-ch-mobile} + +The `Sec-CH-Mobile` request header field gives a server information about whether or not a user agent +prefers a "mobile" user experience. It is a Structured Header ({{I-D.ietf-httpbis-header-structure}}) +whose value MUST be a boolean ({{I-D.ietf-httpbis-header-structure}}, Section 3.7). + +The header's ABNF is: + +~~~ abnf7230 + Sec-CH-Mobile = sh-boolean +~~~ + +To generate a `Sec-CH-Mobile` header value for a given request, user agents MUST: + +1. If the request's client-hints set includes `Mobile`, then: + + 1. Let `value` be a Structured Header whose value indicated a boolean preference for `mobile` + user experiences. + + 2. Set a header in request's header list whose name is `Sec-CH-Mobile`, and whose value is + `value`. + + ## The 'Sec-CH-UA' Header Field {#sec-ch-ua} The `Sec-CH-UA` request header field gives a server information about a user agent's branding and @@ -453,6 +478,23 @@ Author/Change controller: Specification document: : this specification ({{sec-ch-platform}}) +## 'Sec-CH-Platform' Header Field + +Header field name: +: Sec-CH-Mobile + +Applicable protocol: +: http + +Status: +: deprecated + +Author/Change controller: +: IETF + +Specification document: +: this specification ({{sec-ch-mobile}}) + ## 'Sec-CH-UA' Header Field Header field name: diff --git a/index.bs b/index.bs index b510913..32b89e5 100644 --- a/index.bs +++ b/index.bs @@ -167,7 +167,7 @@ User Agent Hints {#http-ua-hints} The following sections define a number of HTTP request header fields that expose detail about a given user agent, which servers can opt-into receiving via the Client Hints infrastructure defined in [[I-D.ietf-httpbis-client-hints]]. The definitions below assume that each user agent has defined -a number of properties for itself (all of which are strings): +a number of properties for itself: * brand (for example: "cURL", "Edge", "The World's Best Web Browser") * major version (for example: "72", "3", or "28") @@ -176,6 +176,7 @@ a number of properties for itself (all of which are strings): * platform version (for example: "10", "12", or "17G") * platform architecture (for example: "ARM64", or "ia32") * model (for example: "", or "Pixel 2 XL") +* mobileness (for example: ?0 or ?1) User agents SHOULD keep these strings short and to the point, but servers MUST accept arbitrary values for each, as they are all values constructed at the user agent's whim. @@ -231,6 +232,8 @@ user agents MUST: 2. [=header list/Set a structured header=] in |r|'s [=request/header list=] whose name is `Sec-CH-Model`, and whose value is `value`. +ISSUE(wicg/ua-client-hints): Perhaps `Sec-CH-Mobile` is enough, and we don't need to expose the model? + The 'Sec-CH-Platform' Header Field {#sec-ch-platform} ---------------------------------- @@ -306,6 +309,31 @@ user agents MUST: 6. [=header list/Set a structured header=] in |r|'s [=request/header list=] whose name is `Sec-CH-UA`, and whose value is |value|. +The 'Sec-CH-Mobile' Header Field {#sec-ch-mobile} +-------------------------------- + +The `Sec-CH-Mobile` request header field gives a server information about +whether or not a user agent prefers a "mobile" user experience. It is a [=Structured Header=] +whose value MUST be a [=structured header/boolean=] [[I-D.ietf-httpbis-header-structure]]. + +The header's ABNF is: + +``` abnf + Sec-CH-Mobile = sh-boolean +``` + +To set the `Sec-CH-Mobile` header for a request, given a [=request=] (|r|), +user agents MUST: + +1. If the request's client-hints set includes `Mobile`, then: + + 1. Let `value` be a [=Structured Header=] whose value is the user agent's + [=user agent/mobileness=]. + + 2. [=header list/Set a structured header=] in |r|'s [=request/header list=] whose name is + `Sec-CH-Mobile`, and whose value is `value`. + + Integration with Fetch {#fetch-integration} ---------------------- @@ -320,6 +348,8 @@ execute the following steps: 2. [$Set the `Sec-CH-Arch` header for a request$], given |r|. +3. [$Set the `Sec-CH-Mobile` header for a request$], given |r|. + 3. [$Set the `Sec-CH-Model` header for a request$], given |r|. 4. [$Set the `Sec-CH-Platform` header for a request$], given |r|. @@ -500,6 +530,24 @@ Author/Change controller: Specification document: : this specification ([[#sec-ch-ua]]) +'Sec-CH-Mobile' Header Field {#iana-mobile} +---------------------------- + +Header field name: +: Sec-CH-Mobile + +Applicable protocol: +: http + +Status: +: standard + +Author/Change controller: +: IETF + +Specification document: +: this specification ([[#sec-ch-mobile]]) + 'User-Agent' Header Field {#iana-user-agent} ------------------------- diff --git a/index.html b/index.html index 5ef1120..9ed7c64 100644 --- a/index.html +++ b/index.html @@ -1215,7 +1215,7 @@ - +