Skip to content

Commit

Permalink
Client hints, general updates
Browse files Browse the repository at this point in the history
  • Loading branch information
@hamishwillee
hamishwillee committed May 11, 2021
1 parent 306b354 commit 57bedf7
Show file tree
Hide file tree
Showing 4 changed files with 57 additions and 36 deletions.
24 changes: 16 additions & 8 deletions files/en-us/glossary/client_hints/index.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -8,23 +8,29 @@
- Reference
- Web Performance
---
<p><span class="seoSummary"><strong>Client Hints</strong> are a set of <a href="/en-US/docs/Web/HTTP/Headers">HTTP request header</a> fields for proactive content negotiation allowing clients to indicate a list of device and agent specific preferences.</span></p>
<p><strong>Client Hints</strong> are a set of <a href="/en-US/docs/Web/HTTP/Headers">HTTP request header</a> fields that a server can proactively
request from a client in order to get its device and agent specific preferences. The set of "hint" headers are listed here: <a href="/en-US/docs/Web/HTTP/Headers#client_hints">HTTP Headers > Client hints</a>.</p>

<p>Use of client hints isn't automatic: rather, servers must announce that they support client hints. Servers announce support for Client Hints using the <code><a href="https://datatracker.ietf.org/doc/html/draft-grigorik-http-client-hints-03#section-2.2.1">Accept-CH</a></code> (accept client hints) header or an equivalent HTML meta element with the <code><a href="/en-US/docs/Web/HTML/Element/meta#attributes">http-equiv</a></code> attribute.</p>
<p>A server must announce that it supports client hints, using the {{HTTPHeader("Accept-CH")}} header to specify the hints that it is interested in recieving.
When a client that supports client hints receives the <code>Accept-CH</code> header it appends client hint headers that match the advertised field-values to subsequent requests.</p>

<p><code>Accept-CH: Width, Viewport-Width, Downlink</code></p>
<p>For example, following <code>Accept-CH</code> in a response below, the client could append {{HTTPHeader("Width")}}, {{HTTPHeader("Viewport-Width")}}, and {{HTTPHeader("Downlink")}} headers to all subsequent requests.</p>

<p>and / or</p>
<pre>Accept-CH: Width, Viewport-Width, Downlink</pre>

<p><code>&lt;meta http-equiv="Accept-CH" content="Width, Viewport-Width, Downlink</code><code>"&gt;</code></p>
<p>The server can then determine which resources to send based on the client information.</p>

<div class="notecard note">
<h4>Note</h4>
<p>Client hints can also be specified in HTML using the <code>meta</code> element with the <code><a href="/en-US/docs/Web/HTML/Element/meta#attr-http-equiv">http-equiv</a></code> attribute.</p>
<pre>&lt;meta http-equiv="Accept-CH" content="Width, Viewport-Width, Downlink"&gt;</pre>
</div>

<p>When a client receives the <code>Accept-CH</code> header, if supported, it appends Client Hint headers that match the advertised field-values. For example, based on Accept-CH example above, the client could append Width, Viewport-Width, and Downlink headers to all subsequent requests. In the second example, the server gives the browser the hints by setting the Accept-CH meta tag.</p>

<p>Basically, with the Client Hints header, the developer or application can tell the browser to advertise information about itself to the server, such as the device pixel ratio, the viewport width, and the display width. The client can then give the server information about the client's environment, and the server can determine which resources to send based on that information.</p>

<h2 id="Varying_Client_Hints">Varying Client Hints</h2>

<p>To convey to caches that different <a href="/en-US/docs/Web/HTTP/Headers#client_hints">Client Hints</a> may affect the response, the <code><a href="/en-US/docs/Web/HTTP/Headers/Vary">Vary</a></code> HTTP header must be used.</p>
<p>To convey to caches that different <a href="/en-US/docs/Web/HTTP/Headers#client_hints">Client Hints</a> may affect the response, the {{HTTPHeader("Vary")}} HTTP header must be used.</p>

<p id="Example_varying_response">Example varying response:</p>

Expand All @@ -35,4 +41,6 @@ <h2 id="See_also">See also</h2>
<ul>
<li><a href="/en-US/docs/Web/HTTP/Headers#client_hints">Client Hints headers</a></li>
<li><a href="/en-US/docs/Web/HTTP/Headers/Vary"><code>Vary</code> HTTP Header</a></li>
<li><a href="https://wicg.github.io/client-hints-infrastructure/">Client Hints Infrastructure, W3C Draft Community Group Report, 29 April 2021</a></li>

</ul>
12 changes: 4 additions & 8 deletions files/en-us/web/http/headers/accept-ch-lifetime/index.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -5,8 +5,9 @@
- Client hints
- HTTP
- header
browser-compat: http.headers.Accept-CH-Lifetime
---
<div>{{HTTPSidebar}}{{securecontext_header}}{{Deprecated_header}}{{Non-standard_header}}</div>
<div>{{HTTPSidebar}}{{securecontext_header}}{{Deprecated_header}}</div>

<p>The <code><strong>Accept-CH-Lifetime</strong></code> header is set by the server to
specify the persistence of {{HTTPHeader("Accept-CH")}} header value that specifies for
Expand All @@ -28,7 +29,7 @@

<div class="notecard note">
<p><strong>Note:</strong> Client Hints are accessible only on secure origins (via TLS).
Accept-CH and Accept-CH-Lifetime headers should be persisted for all secure requests
{{HTTPHeader("Accept-CH")}} and {{HTTPHeader("Accept-CH-Lifetime")}} headers should be persisted for all secure requests
to ensure Client Hints are sent reliably.</p>
</div>

Expand All @@ -45,12 +46,7 @@ <h2 id="Examples">Examples</h2>

<h2 id="Browser_compatibility">Browser compatibility</h2>

<p class="hidden">The compatibility table in this page is generated from structured data.
If you'd like to contribute to the data, please check out <a
href="https://github.com/mdn/browser-compat-data">https://github.com/mdn/browser-compat-data</a>
and send us a pull request.</p>

<p>{{Compat("http.headers.Accept-CH-Lifetime")}}</p>
<p>{{Compat}}</p>

<h2 id="See_also">See also</h2>

Expand Down
43 changes: 27 additions & 16 deletions files/en-us/web/http/headers/accept-ch/index.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -5,11 +5,12 @@
- Client hints
- HTTP
- HTTP Header
browser-compat: http.headers.Accept-CH
---
<div>{{HTTPSidebar}}{{securecontext_header}}{{SeeCompatTable}}</div>

<p>The <code><strong>Accept-CH</strong></code> header is set by the server to specify
which <a href="/en-US/docs/Glossary/Client_hints">Client Hints</a> headers a client
<p>The <code><strong>Accept-CH</strong></code> header may be set by a server to specify
which <a href="/en-US/docs/Glossary/Client_hints">client hints</a> headers a client
should include in subsequent requests.</p>

<table class="properties">
Expand All @@ -20,15 +21,15 @@
</tr>
<tr>
<th scope="row">{{Glossary("Forbidden header name")}}</th>
<td>?</td>
<td>no</td>
</tr>
</tbody>
</table>

<div class="notecard note">
<p><strong>Note:</strong> Client Hints are accessible only on secure origins (via TLS).
Accept-CH and Accept-CH-Lifetime headers should be persisted for all secure requests
to ensure Client Hints are sent reliably.</p>
<p><strong>Note:</strong> Client hints are accessible only on secure origins (via TLS).
<code>Accept-CH</code> (and <code>Accept-CH-Lifetime</code>) headers should be persisted for all secure requests
to ensure client hints are sent reliably.</p>
</div>

<h2 id="Syntax">Syntax</h2>
Expand All @@ -38,9 +39,7 @@ <h2 id="Syntax">Syntax</h2>

<h2 id="Examples">Examples</h2>

<pre>Accept-CH: Viewport-Width
Accept-CH: Width
Accept-CH-Lifetime: 86400
<pre>Accept-CH: Viewport-Width, Width
Vary: Viewport-Width, Width
</pre>

Expand All @@ -50,18 +49,30 @@ <h2 id="Examples">Examples</h2>
based on the accepted client hints.</p>
</div>

<h2 id="Browser_compatibility">Browser compatibility</h2>

<p class="hidden">The compatibility table in this page is generated from structured data.
If you'd like to contribute to the data, please check out <a
href="https://github.com/mdn/browser-compat-data">https://github.com/mdn/browser-compat-data</a>
and send us a pull request.</p>
<h2 id="Specifications">Specifications</h2>

<table class="standard-table">
<thead>
<tr>
<th scope="col">Specification</th>
<th scope="col">Title</th>
</tr>
</thead>
<tbody>
<tr>
<td>{{RFC("8942", "Accept-CH")}}</td>
<td>HTTP Client Hints</td>
</tr>
</tbody>
</table>

<h2 id="Browser_compatibility">Browser compatibility</h2>

<p>{{Compat("http.headers.Accept-CH")}}</p>
<p>{{Compat}}</p>

<h2 id="See_also">See also</h2>

<ul>
<li>{{HTTPHeader("Accept-CH-Lifetime")}}</li>
<li>{{HTTPHeader("Vary")}}</li>
</ul>
14 changes: 10 additions & 4 deletions files/en-us/web/http/headers/index.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,7 @@

<p><span class="seoSummary"><strong>HTTP headers</strong> let the client and the server pass additional information with an HTTP request or response. An HTTP header consists of its case-insensitive name followed by a colon (<code>:</code>), then by its value.</span> {{Glossary("Whitespace")}} before the value is ignored.</p>

<p>Custom proprietary headers have historically been used with an <code>X-</code> prefix, but this convention was deprecated in June 2012 because of the inconveniences it caused when nonstandard fields became standard in <a href="https://datatracker.ietf.org/doc/html/rfc6648">RFC 6648</a>; others are listed in an <a href="http://www.iana.org/assignments/message-headers/perm-headers.html">IANA registry</a>, whose original content was defined in <a href="https://datatracker.ietf.org/doc/html/rfc4229">RFC 4229</a>. IANA also maintains a <a href="http://www.iana.org/assignments/message-headers/prov-headers.html">registry of proposed new HTTP headers</a>.</p>
<p>Custom proprietary headers have historically been used with an <code>X-</code> prefix, but this convention was deprecated in June 2012 because of the inconveniences it caused when nonstandard fields became standard in <a href="https://datatracker.ietf.org/doc/html/rfc6648">RFC 6648</a>; others are listed in an <a href="https://www.iana.org/assignments/message-headers/perm-headers.html">IANA registry</a>, whose original content was defined in <a href="https://datatracker.ietf.org/doc/html/rfc4229">RFC 4229</a>. IANA also maintains a <a href="https://www.iana.org/assignments/message-headers/prov-headers.html">registry of proposed new HTTP headers</a>.</p>

<p>Headers can be grouped according to their contexts:</p>

Expand Down Expand Up @@ -88,6 +88,8 @@ <h2 id="Client_hints">Client hints</h2>
<dd>Indicates that the request has been conveyed in early data.</dd>
<dt>{{HTTPHeader("Device-Memory")}} {{experimental_inline}}</dt>
<dd>Technically a part of Device Memory API, this header represents an approximate amount of RAM client has.</dd>
<dt>{{HTTPHeader("DPR")}} {{deprecated_inline}}</dt>
<dd>Client device pixel ratio (DPR), which is the number of physical device pixels corresponding to every CSS pixel.</dd>
<dt>{{HTTPHeader("Save-Data")}} {{experimental_inline}}</dt>
<dd>A boolean that indicates the user agent's preference for reduced data usage.</dd>
<dt>{{HTTPHeader("Viewport-Width")}} {{experimental_inline}}</dt>
Expand Down Expand Up @@ -140,7 +142,11 @@ <h2 id="Connection_management">Connection management</h2>
<dd>Controls how long a persistent connection should stay open.</dd>
</dl>

<h2 id="Content_negotiation"><a href="/en-US/docs/Web/HTTP/Content_negotiation">Content negotiation</a></h2>

<h2 id="Content_negotiation">Content negotiation</h2>

<p>Learn more about <a href="/en-US/docs/Web/HTTP/Content_negotiation">Content negotiation</a> here.</p>


<dl>
<dt>{{HTTPHeader("Accept")}}</dt>
Expand Down Expand Up @@ -327,9 +333,9 @@ <h2 id="Security">Security</h2>
<dd>Enables cross-site scripting filtering.</dd>
</dl>

<h3 id="HTTP_Public_Key_Pinning_GlossaryHPKP">HTTP Public Key Pinning ({{Glossary("HPKP")}})</h3>
<h3 id="HTTP_Public_Key_Pinning_GlossaryHPKP">HTTP Public Key Pinning (HPKP)</h3>

<p>HTTP Public Key Pinning has been deprecated and removed in favor of Certificate Transparency and {{HTTPHeader("Expect-CT")}}.</p>
<p>{{Glossary("HPKP", "HTTP Public Key Pinning")}} has been deprecated and removed in favor of Certificate Transparency and {{HTTPHeader("Expect-CT")}}.</p>

<dl>
<dt>{{HTTPHeader("Public-Key-Pins")}}</dt>
Expand Down

0 comments on commit 57bedf7

Please sign in to comment.